.. push to trigger TC

.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



######################################
OpenEye Applications |appspkgversion|
######################################

..  toctree::
    :maxdepth: 2

    releasenotes/index
    Applications <app_list>


.. Applications Release Notes Master File

########################
OEApplications 2026.1
########################

..  toctree::

    highlights
    detailed_notes
    previous_notes


Highlights of Applications Release 2026.1
=============================================

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |PRELIMINARY-API| replace:: This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

.. |PRELIMINARY-CONSTANTS| replace:: These constants are preliminary and may be improved based on user feedback.

.. |TWOLANGUAGE| replace:: This API is currently available in C++ and Python.

.. |CPPONLY| replace:: This functionality is only available in the C++ toolkits. For other languages, we recommend using language-specific functionality instead.

.. |PYTHONONLY| replace:: This functionality is only available in the Python toolkits.

.. |NOPDFIMAGE| replace:: *There is no image available for the PDF version of this book.*

.. |DEPRECATED-API| replace:: This is a deprecated API.

.. |SUBWORKING| replace:: Substitutions are working!


OEChem TK: Peptide Informatics Support 
-----------------------------------------------------------------------------

This release delivers a comprehensive set of peptide informatics capabilities in 
**OEChem TK**, including reliable conversion between molecular structures and HELM 
representations. Support for custom monomer dictionaries enables seamless incorporation 
of proprietary nonstandard amino acids into peptide discovery workflows.
The release also includes a built-in monomer dictionary containing more than 260 monomers 
commonly encountered in peptide chemistry projects.

In addition, enhanced visualization capabilities in **Grapheme TK** enable clear and
intuitive representation of complex peptides, facilitating the interpretation and communication 
of diverse peptide chemistries.

.. figure:: /_images/helm-conversion.png
   :width: 500pt
   :align: center
  
   **Figure 1.** Conversion between HELM strings generated with different monomer sets.


OMEGA: Torsion Driving with Thompson Sampling
-----------------------------------------------------------------------------

Conformer generation using **OMEGA** with torsion driving now automatically
uses Thompson sampling. The algorithm for Thompson sampling in **OMEGA** has been
optimized for performance and extended to the generation of larger ensembles, such
as those used in the ``classic`` and ``pose`` modes of **OMEGA**.

Thompson sampling is a Bayesian approach that drives conformer generation toward
low energy structures, enabling conformer generation at speed without sacrificing accuracy. 
In general, the speed increase with Thompson sampling is larger when working with larger
molecules and generating smaller ensembles. On a dataset of ~40K compounds, compiled 
from multiple vendor databases consisting of molecules of varied sizes, an overall
2x speedup over torsion driving without Thompson sampling is observed when generating
conformers in the ``classic`` mode. Conformer generation for the same dataset using
the ``fastrocs`` mode provides a 3x speedup over torsion driving without Thompson sampling.
A comparison of timings for the dataset of the ~40K compounds from multiple vendor
databases is shown in Figure 2.

.. figure:: /_images/OMEGA_TS_SpeedRotor.png
   :width: 550pt
   :align: center

   **Figure 2.** Comparison of **OMEGA** performance in the ``classic`` mode
   between exhaustive and Thompson sampling. The box plots show the distribution
   of processing time binned by rotor count.

**OMEGA** maintains high accuracy while achieving this performance gain.
As seen in Figure 3, both exhaustive and Thompson sampling methods in the
``classic`` mode reproduce conformations within 1 Å RMSD of the experimental
conformation for 80% of ligands across the 6,000 PDB structures with HT 
(Highly Trustworthy) Iridium scores. Structure-based virtual 
screening performance is equivalent to that obtained from exhaustive sampling.

.. figure:: /_images/OMEGA_TS_RMSD.png
   :width: 350pt
   :align: center

   **Figure 3.** Distribution of RMSD between the best pose from the generated ensemble
   and the crystal pose for the two sampling methods using ``classic`` mode in **OMEGA**.


Bioisostere TK: Multiquery Replacements
-----------------------------------------------------------------------------

**Bioisostere TK** now includes new API functionality for simultaneous replacement of
multiple query fragments in a molecule. With the addition of the new functionality,
**Bioisostere TK** is uniquely positioned with tools to build applications for
3D generative de novo molecule design.

In addition to the ability to simultaneously replace multiple query fragments,
tools have been added to obtain scores of multiple replacements from their single
replacement counterparts, building a single hit list of **Brood** overlay scores obtained
from multiple query replacements, building hit lists combining hits from different
queries and multiple queries, and building clusters from the combined hit lists.
All of the API designs are compatible for use with an arbitrary number of queries
on a molecule, without any limitations. With the addition of each query, the searchable
space can be expanded combinatorially, enabling exploration of increasingly larger chemical
design spaces.

As shown in Figure 4, users can select specific fragments in a molecule of
interest and generate targeted replacement suggestions.

.. figure:: /_images/Brood-multiquery.png
   :width: 600pt
   :align: center

   **Figure 4.** De novo molecule design of an EZH2 inhibitor. The compound on the
   left highlights the input molecule being divided into three fragments to build three
   separate **Brood** queries. The compound on the right is a new molecule designed
   using **Bioisostere TK** to replace all three queries from the left.


..  _supported-app-platforms-2026-Sum:

Supported Platforms
--------------------

  ===========  =======================
  OS           Versions
  -----------  -----------------------
  Linux        RHEL8/9/10, Ubuntu22/24
  Windows      Win11
  macOS        14, 15, 26
  ===========  =======================

Related Application Versions
-----------------------------

  ==============  ===========
  Application     Version
  --------------  -----------
  AFITT           3.0.4
  BROOD           5.0.0
  EON             3.1.3
  OEDocking       4.3.5
  OMEGA           7.0.0
  PICTO           5.1.5
  pKa-Prospector  1.2.7
  QUACPAC         2.3.0
  ROCS            3.10.0
  SiteHopper      2.1.4
  SPRUCE          1.9.0
  SZMAP           1.7.4
  SZYBKI          2.9.2
  VIDA            5.0.7
  ==============  ===========

General Notices
==================

* Linux Support:
  
  * Support for Red Hat 10 has been added in this release. However, support for 
    the GUI applications, including VIDA, is not available.
  * Support for Ubuntu 26 will be added in the winter of 2027.
  * Support for Ubuntu 22 will be dropped in the winter of 2027.

* macOS Support:

  * Support for macOS 26 has been added in this release.
  * Support for macOS 13 has been dropped.
  * Support for all Intel-based Macs will be dropped in the winter of 2027.

* Support for Windows 10 has been dropped in this release.



Detailed Release Notes 2026.1
================================

..  toctree::

    AFITT <../afitt/releasenotes/version3_0_4>
    BROOD <../brood/releasenotes/version5_0_0>
    EON  <../eon/releasenotes/version3_1_3>
    OEDOCKING <../oedocking/releasenotes/version4_3_5>
    OMEGA <../omega/releasenotes/version7_0_0>
    PICTO   <../picto/releasenotes/version5_1_5>
    PKA-PROSPECTOR <../pka-prospector/releasenotes/version1_2_7>
    QUACPAC <../quacpac/releasenotes/version2_3_0>
    ROCS <../rocs/releasenotes/version3_10_0>
    SITEHOPPER <../sitehopper/releasenotes/version2_1_4>
    SPRUCE <../spruce/releasenotes/version1_9_0>
    SZMAP   <../szmap/releasenotes/version1_7_4>
    SZYBKI <../szybki/releasenotes/version2_9_2>




FLYNN 3.0.4
================================================================================

Minor internal improvements have been made.



.. _afitt_releasenotes:

Release History
*********************************

.. toctree::

   version3_0_4
   version3_0_3
   version3_0_2
   version3_0_1
   version3_0_0
   version2_6_5
   version2_6_4
   version2_6_3
   version2_6_2
   version2_6_1
   version2_6_0
   version2_5_3.rst
   version2_5_2.rst
   version2_5_1.rst
   version2_5_0.rst
   version2_4_1.rst
   version2_4_0.rst
   version2_3_0.rst
   version2_2_0.rst
   version2_1_1.rst
   version2_1_0.rst
   version2_0_1.rst
   version2_0_0.rst



#################
FLYNN 3.0.3
#################

Minor internal improvements have been made.



FLYNN 2.0.0
================================================================================

*February 2010*

* Internal Release used with collaborators.  Used for testing new dictionary formats.


AFITT-CL 2.0.1
================================================================================

*September 2010*

Package renamed from FLYNN to AFITT-CL.  None of the internal programs
have been renamed.  AFITT and AFITT-CL will be released simultaneously
with the same version numbers from this point forward.

WRITEDICT
---------

* Added correct dictionary creation including connection table.  This
  is required for newer versions of *coot*  

* CIF dictionaries properly encode all LINK records.

* CIF dictionaries now encode proper planarity for guanine and no 
  longer have duplicate planar atoms when using MMFF94s.

* CIF Dictionaries now look up known non-peptide residues.  If the
  residue is not consistent with the known dictionary, the residue
  name is changed and a new MMFF94 derived dictionary is generated.

* Updated COOT integration to 0.6+

FLYNN
-----

* Enhanced automatic density location.  Blobs are now slightly larger
  than before making better targets for fitting.

* Added experimental fragment fitting.  See the documentation for more
  information about this command line option.  For version 2.0.1 this
  requires the fragment feature of the FLYNN license.  This
  requirement will be removed when this feature is considered
  non-experimental.  If you are interested in helping us test this
  feature, please contact business@eyesopen.com for more
  details.

* Refinement dictionaries are always written out for the ligand.
  Please note that these are written as if the -split flag is set to
  true.  Refer to the documentation or type "flynn --help" at the
  command line for more details.

* Updated COOT integration to 0.6+


AFITT-CL 2.1.0
================================================================================

*July 2011*

WRITEDICT
---------

* Updated internal REFMAC and RCSB to current versions.

* When remapping dictionaries, WRITEDICT now indicates where the
  matching monomer was sourced. 

* Moved "lookup" out of the -strict settings to a new flag "-lookup"
  adding this switch will search for a matching monomer from the 
  internal libraries using the current -strict settings.

* -force options added.  WRITEDICT will output the residue name
  even if it doesn't match the internal list of known monomers.

* Various corrections to aniline nitrogen dictionaries.

FLYNN
-----

* FLYNN now sorts the output fits based on real space correlation
  coefficient if applicable (RSCC)

* FLYNN now can automatically fit fragment cocktails. (use -fragment
  flag)

* FLYNN adds additional scores to all ligands besides the default MMFF
  Tanimoto/Shape, these are RSCC (Real space correlation coefficient),
  PLP (Piecewise-linear potential, requires protein) and Chemscore
  (requires protein).

* -resname now forces the ligand to use the given residue name even if
  it conflicts with the internal monomer library.

* -chainid Output the ligands with the given chain id.


AFITT-CL 2.1.1
================================================================================

*December 2011*

WRITEDICT
---------

* Added PHENIX suppoert

* Monomers in CIF files are given IUPAC names when possible

* Updated dictionaries to support REFMAC5 in CCP4 6.2.0

FLYNN
-----

* Added PHENIX suppoert

* Fixed issues where ligands fit in poor density could be overstrained.


AFITT-CL 2.2.0
================================================================================

*August 2012*

WRITEDICT
---------

* Updated to support REFMAC 5.6 and 5.7 (CCP4 6.3.0)

* Monomers updated to current RCSB and CCP4 releases.

* PDB LINK records are validated to be in the correct order.  This
  validation is required for REFMAC 5.6 and up.

FLYNN
-----

* Bugfixes and general speedups applied to internal optimizer.

* A memory leak in the optimzer was fixed.


AFITT-CL 2.3.0
================================================================================

*July 2013*

Other
-----

*Note:* Last release for SUSE Linux Enterprise 10.

WRITEDICT
---------

* Hydrogen naming is now consistent with RSCB standards.

* added -prefix flag for controlling report and logging generation

FLYNN
-----

* Optimization fixes for molecules with high strain.

* Better default ligand density location.

* Optional PM3 and AM1 ligand minimization (see the -ff flag).

* Fixed symmetry operations on cubic lattices.

* added -prefix flag for controlling report and logging generation.

COOT Integration
----------------

* Better error message when the ligand and protein are set to the
  same coordinates

* Added ability to choose both chain id and residue name for
  the fit ligand.


AFITT-CL 2.4.0
================================================================================

*November 2014*

* Add helper programs to allow ligand forcefields during refinement for
  PHENIX and BUSTER

* Updated PHENIX support, including covalent bond support

* Alter the protein masking to not remove density that may be created by 
  hydrogen or covalent bonds.  This was causing density very close to the 
  protein to be truncated and hard to find automatically.

Platform Support
----------------

 * Added support for RedHat 7, Ubuntu 14 and OSX 10.9

 * Dropped support for RedHat 5 32 bit, Ubuntu 10 and OSX 10.6

 * This will be the last release for SuSe 11

FLYNN
-----

* Alter the protein masking to not remove density that may be created by 
  hydrogen or covalent bonds.  This was causing density very close to the 
  protein to be truncated and hard to find automatically.

* -box is now called -manualSearch (-box still works)

* -blobsThenBox is now called -autoThenManualSearch for clarity 
  (-blobsThenBox still works)

* -ciftype now follows the new writedict convention 
  (accepts both numeric and more readable names such as "refmac", "xplor")

* -ciftype parameter is now in the correct parameter section 
  (Advanced not Fragment)

* FLYNN always fixes serial numbers when writing CIF output to better
  enable use in workflow situations.  These can be caused when
  hydrogens are added to ligands outside the context of the protein for
  instance.

WRITEDICT
---------

* AFITT now Post-processes equilibrium angles to see if they are compatible with 
  geometric forcefields.  If they are not, replace them with fully MMFF
  optimized angles.  This mostly affects 6-5 aromatic systems, but 
  is a general fix ensuring the geometric force-field will work properly 
  given the constraints in the CIF dictionary. 

* Writedict now properly fail if the input protein has duplicate serial numbers.  Most 
  refinement programs cannot handle this state.

* Prevent duplication of CRYST1 records in the writedict output.

* Always output disulfide bridges if input

* Never rename standard residues hydrogens, this was causing Markly naming 
  violations.

* Fix phenix covalent link output when covalently linking two residues of 
  the same residue type.

* WRITEDICT no longers fails if input standard residues have alternate conformations 
  with different graphs.

* WRITEDICT now defaults to MMFF94s

* WRITEDICT now understands human readable names for the dictionary type, 
  i.e. -type refmac as opposed to -type 0

* WRITEDICT now has a -fix_serial_numbers flag that corrects duplicate
  serial numbers in the resulting pdb output

ROTFIT
------

* Added rotfit rotamer driving command line program.  This used to live
  entirely in the GUI.


AFITT-CL 2.4.1
================================================================================

*March 2017*

Platform Support
----------------

 * Support has been added for Ubuntu 16, OSX 10.10, OSX 10.11, and OSX 10.12.

 * OSX 10.7, OSX 10.8, OSX 10.9, SuSe 11, and Redhat 5 x86 are no longer supported.

Coot Support
------------

 * Support has been added for Coot 0.8.

 * Coot versions 0.6 and earlier are no longer supported.

Bug Fixes
---------

 * A bug in WRITEDICT that caused inappropriate bond lengths to be written for
   some cyclic systems has been fixed. Originally, WRITEDICT outputted the MMFF
   bond potential minimum as the bond length. However, for aromatic rings this
   value is inappropriately large since MMFFs angle and torsion potentials also
   affect the bond length significantly. In these cases, the equilibrium bond
   lengths are used by WRITEDICT.

 * A bug that caused PDB remark data that was more than 72 characters long to
   be clipped from the refined output has been fixed. Practically, this only
   occurred when the input and output file formats were both PDB.

 * On Windows, the default "save" location has been changed from 
   C:\Program Files (x86)\AFITT 2.4.0 to the Users Home directory.

 * Previously, if an older version of AFITT was installed on Windows, users
   could not overwrite the old preferences. This issue has been fixed.

 * A crash that occurred on Windows 10 after selecting the Refmac option
   without a locally installed copy of Refmac has been fixed.

 * The AFITT suite ships with a simple Python-based do_gold.py test script,
   to make sure  AFITT-CL (FLYNN) is functioning as intended.  This script
   analyzes the Gold dataset (protein+ligand complexes) available from the
   Electron Density Server  (EDS) and included with the distribution.  The
   do_gold.py test script has been modified to run correctly with either Python
   2 or Python 3.


AFITT 2.5.0
================================================================================

*Nov 2019*

* This is the first inclusion of **AFITT** applications in the **OpenEye Applications** bundle.
  They have been built using **OEToolkits 2019.Oct**.

* The **AFITT** GUI is not available as part of the **2019.Nov** release.


AFITT 2.5.1
================================================================================

*Spring 2020*

* This version of **AFITT** has been built using **OEToolkits 2020.0**.

* The **AFITT** GUI is not available as part of the 2020.0 release.


AFITT  2.5.2.0
================================================================================

*Fall 2020*

* Minor internal improvements have been made.


AFITT  2.5.3
================================================================================

*July 2021*

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

* Minor deprecation warnings have been removed.

Documentation Changes
-------------------------------------------------------------------------------

* Updated documentation to support newer WinCoot version (0.9.4.1 and beyond)
 

AFITT  2.6.0
================================================================================

*Fall 2021*

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

* The REFMAC dictionary writer now inlcudes molecule coordinates in the CIF keys _chem_comp_atom.{x,y,z}.  



AFITT  2.6.1
================================================================================

*Spring 2022*

* Multiple typos were fixed in **Flynn** command line help.

* Multiple typos were fixed in **WriteDict** command line help.



AFITT  2.6.2
================================================================================

*Fall 2022*

Minor internal improvements have been made.



AFITT  2.6.3
================================================================================

Minor internal improvements have been made.



AFITT  2.6.4
================================================================================

Minor internal improvements have been made.



AFITT  2.6.5
================================================================================

* An issue was fix that caused a ligand to sometimes have a set of incorrect protein residue names assigned.


AFITT  3.0.0
================================================================================

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

* **FLYNN** can now handle maps from cryo-electron microscopy (cryo-EM) natively. Maps from cryo-EM in the `.mrc`, `.ccp4`, or `.map`
  file formats can be input using the `-map` map command-line parameter, alongside the protein structure file (`-prot`)
  docked/refined into the map and the 2D or 3D ligand information for the molecule to be modeled (`-in`).



AFITT  3.0.1
================================================================================

Minor internal improvements have been made.



FLYNN 3.0.2
================================================================================

Minor internal improvements have been made.



BROOD 5.0.0
================================================================================

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

* **vBROOD** now respects the user defined color atoms and color
  constraints in the generated ``Brood Query``.

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

* The ``-quickLook`` option in **BROOD** now properly enforces a valid range, reducing
  the possibility of getting an empty hit list as output.

* An issue has been fixed where occasional high memory usage of **BROOD** occurred while running
  the application in the ``ET`` mode.

****************************************
Related Toolkit Information
****************************************


Bioisostere TK 5.0.0
================================================================================

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

* The following new classes have been added as preliminary API:
  
  * :ref:`OEBroodBuildResult <OEBioisostere_OEBroodBuildResult>`
  * :ref:`OEBroodCluster <OEBioisostere_OEBroodCluster>`
  * :ref:`OEBroodClusterBuilder <OEBioisostere_OEBroodClusterBuilder>`
  * :ref:`OEBroodComboBuilder <OEBioisostere_OEBroodComboBuilder>`
  * :ref:`OEHitlistBuilderOptions <OEBioisostere_OEHitlistBuilderOptions>`
  * :ref:`OEHitlistBase <OEBioisostere_OEHitlistBase>`
  * :ref:`OEScoreHitlist <OEBioisostere_OEScoreHitlist>`
  * :ref:`OEBroodHitlist <OEBioisostere_OEBroodHitlist>`
  * :ref:`OEMolCTBuilder <OEBioisostere_OEMolCTBuilder>`
  * :ref:`OESimilarity <OEBioisostere_OESimilarity>`

* The following new methods have been added to :ref:`OEBroodQuery <OEBioisostere_OEBroodQuery>`:

  * :ref:`GetQueryID <OEBioisostere_OEBroodQuery_GetQueryID>`
  * :ref:`SetQueryID <OEBioisostere_OEBroodQuery_SetQueryID>`

* A new constructor overload has been added to :ref:`OEHitlistBuilder <OEBioisostere_OEHitlistBuilder>`
  that takes a :ref:`OEHitlistBuilderOptions <OEBioisostere_OEHitlistBuilderOptions>` as an argument.

* A new overload of :ref:`Setup <OEBioisostere_OEBroodDBFilter_Setup>` has been added to
  :ref:`OEBroodDBFilter <OEBioisostere_OEBroodDBFilter>` that takes a molecule as argument.

* The following new methods have been added to :ref:`OEBroodQuery <OEBioisostere_OEBroodQuery>`:

  * :ref:`GetBuildRes <OEBioisostere_OEBroodHit_GetBuildRes>`
  * :ref:`GetScores <OEBioisostere_OEBroodHit_GetScores>`

* The following new methods have been added to :ref:`OEBroodScore <OEBioisostere_OEBroodScore>`:

  * :ref:`Add <OEBioisostere_OEBroodScore_Add>`
  * :ref:`GetQueryIDs <OEBioisostere_OEBroodScore_GetQueryIDs>`

* The following new functions have been added:

  * :ref:`OECreateFlipperOptions <OEBioisostere_OECreateFlipperOptions>`
  * :ref:`OECreateFragFilter <OEBioisostere_OECreateFragFilter>`
  * :ref:`OEIsFragment <OEBioisostere_OEIsFragment>`

* The following methods have been removed from the :ref:`OEHitlistBuilder <OEBioisostere_OEHitlistBuilder>`,
  as they are no longer relevant:

  * GetTrimmedCount
  * TrimHitlist
  * An overload of GetHits that took a vector of :ref:`OEBroodHit <OEBioisostere_OEBroodHit>` as an argument.
  * GetRemovedHits


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

* The :ref:`OECreateBroodQuery <OEBioisostere_OECreateBroodQuery>` method now
  keeps any incoming color atoms associated with the query selection, when available, and
  does not add any additional color atoms to the query.  The behavior is unchanged
  when no color atoms are present with the incoming selection.

* A bug in fragment property filtering has been resolved. Now by setting the
  :ref:`SetUseProperty <OEBioisostere_OEBroodScoreOptions_SetUseProperty>` option in
  :ref:`OEBroodScoreOptions <OEBioisostere_OEBroodScoreOptions>` to true, you can activate
  the fragment filtering based on the properties defined by
  :ref:`OEExtrinsicPropOptions <OEBioisostere_OEExtrinsicPropOptions>` and
  :ref:`OEIntrinsicPropOptions <OEBioisostere_OEIntrinsicPropOptions>`.
  Previously, the filter was not being applied correctly, which could lead to unexpected
  fragments being included in the results.

* An issue has been fixed related to proper usage of 
  :ref:`SetRangeSize<OEBioisostere_OEBroodGeneralOptions_SetRangeSize>` and
  :ref:`SetRangeOffset<OEBioisostere_OEBroodGeneralOptions_SetRangeOffset>` so that
  fragment retrieval from the database during the overlay step now properly respects
  the specified range boundaries.

* A bug has been fixed where the color score reported by
  :ref:`GetColorScore <OEBioisostere_OEBroodScore_GetColorScore>` could exceed its valid
  range in ROCS mode, causing the combined score to exceed its range as well. The color
  Tanimoto is now computed consistently from the scored conformer.




#######################
EON 3.1.3
#######################

Minor internal improvements have been made.

*************************************
Related Toolkit Information
*************************************


EON TK 3.1.3
================================================================================

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

* Two new methods, :ref:`GetJoinRef<OEEon_OEEonPBOptions_GetJoinRef>` and
  :ref:`SetJoinRef<OEEon_OEEonPBOptions_SetJoinRef>`, have been added to
  :ref:`OEEonPBOptions<OEEon_OEEonPBOptions>` to enable ``PB`` calculation
  on complexes in :ref:`OEEonPBFunc<OEEon_OEEonPBFunc>`.


Zap TK 2.5.3
================================================================================

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

* Salt concentration implementation in **Zap TK** has been corrected and made robust
  at higher salt concentrations.

* As a result of the salt concentration improvement, the rotational
  variation of Zap solvation energy at high salt concentrations has been
  substantially reduced.




OEDocking 4.3.5
================================================================================

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


OEDocking TK 4.3.5
================================================================================

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

* An issue has been fixed that was causing :ref:`OEPosit <OEDocking_OEPosit>`
  to pick the wrong :ref:`method <OEDocking_OEPositMethod>` in posing some
  ligands.



*******************************
OMEGA 7.0.0
*******************************

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


Omega TK 7.0.0
================================================================================

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

* The following changes have been made to extend Thompson sampling usage for torsion driving
  in :ref:`OEOmega<OEConfGen_OEOmega>`:

  * The :ref:`Thompson sampling<OEConfGen_OETorDriveOptions_SetUseThompson>` algorithm
    for torsion driving has been improved for robustness and speed.
  * The default value for :ref:`SetUseThompson<OEConfGen_OETorDriveOptions_SetUseThompson>`
    in :ref:`OETorDriveOptions<OEConfGen_OETorDriveOptions>` has been changed to ``True``.
  * The :ref:`SetUseThompson<OEConfGen_OETorDriveOptions_SetUseThompson>` is honored even when
    :ref:`SetUseGPU<OEConfGen_OETorDriveOptions_SetUseGPU>` is set to ``True``.
  * The preliminary API class ``OEThompsonOptions`` has been removed, as it is no longer relevant.

* The default energy window for torsion driving in :ref:`Classic <OEConfGen_OEOmegaSampling_Classic>`
  mode has been changed to a range-based value to better suit **OMEGA** with Thompson sampling.
  Similarly, the energy range for the :ref:`Pose <OEConfGen_OEOmegaSampling_Pose>` mode has also been
  adjusted.


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

* :ref:`OEMolBuilder <OEConfGen_OEMolBuilder>` now respects the
  :ref:`MaxEnumConfs <OEConfGen_OEMolBuilderOptions_SetMaxEnumConfs>` provided in 
  the :ref:`OEMolBuilderOptions <OEConfGen_OEMolBuilderOptions>`
  even when an input molecule has more conformers than specified.
  
* Certain edge cases where the torsion driving algorithm would fail with a
  FailedTorDrive error message have been addressed. 


MolProp TK 2.7.0
================================================================================

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

* The SMARTS pattern of the :ref:`functional_group_rules_halo_amine` functional group has been fixed.



**************************
PICTO 5.1.5
**************************

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


OEDepict TK 2.7.0
================================================================================

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

* Two new methods, :ref:`GetOptimizeMacrocycles<OEDepict_OEPrepareDepictionOptions_GetOptimizeMacrocycles>` and
  :ref:`SetOptimizeMacrocycles<OEDepict_OEPrepareDepictionOptions_SetOptimizeMacrocycles>`, have been
  added to :ref:`OEPrepareDepictionOptions<OEDepict_OEPrepareDepictionOptions>` to enable enhanced
  algorithmic depiction of macrocycle rings.




pKa-Prospector 1.2.7
================================================================================

Minor internal improvements have been made.



.. _pka_releasenotes:

Release History
===============

.. toctree::

   version1_2_7
   version1_2_6
   version1_2_5
   version1_2_4
   version1_2_3
   version1_2_2
   version1_2_1
   version1_2_0
   version1_1_7
   version1_1_6
   version1_1_5
   version1_1_4
   version1_1_3
   version1_1_2
   version1_1_1
   version1_1_0
   version1_0_0


######################
pKa-Prospector 1.2.6
######################

Minor internal improvements have been made.



.. _pka_releasenotes_100:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


pKa-Prospector 1.0.0
================================================================================

*2013*

First release of pKa-Prospector.

These pKa databases represent the extremely careful conversion of IUPAC's extensive compilations of experimental pKa values of organic acids and bases (in aqueous solution) from book form into fully curated computer-readable data.
The pKa-Prospector application provides a tool for users primarily interested in their own compound to find what the primary data may say about their compound or model compounds closely analogous to their molecule of interest.

Features
--------

* Auto-identify ionizable centers.
* Auto-search to identify model compounds.
* Additional search types include property, substructure, exact and fingerprint similarity.
* Export PDF to share results.
* Extensible to operate over user supplied data.


pKa-Prospector 1.1.0 
================================================================================

*November 2018*

* This version of **pKa-Prospector** has been built using **OEToolkits 2018.Oct**. 
  The previous version was built using **OEToolkits 2013.Jun**.

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

* Fixed the application so that the Visual C++ 2008 redistributable package (x86)
  is no longer required to run **pKa-Prospector** in Windows 10.


pKa-Prospector 1.1.1
================================================================================

*May 2019*

* This version of **pKa-Prospector** has been built using **OEToolkits 2019.Apr**. The previous
  version was built using **OEToolkits 2018.Oct**.


pKa-Prospector 1.1.2
================================================================================

*Nov 2019*

* This version of **pKa-Prospector** has been built using **OEToolkits 2019.Oct**. The previous
  version was built using **OEToolkits 2019.Apr**.


pKa-Prospector 1.1.3
================================================================================

*Spring 2020*

* This version of **pKa-Prospector** has been built using **OEToolkits 2020.0**.



pKa-Prospector  1.1.4.0
================================================================================

*Fall 2020*

* Minor internal improvements have been made.



pKa-Prospector  1.1.5
================================================================================

July 2021
---------

* Minor internal improvements have been made.



pKa-Prospector  1.1.6
================================================================================

Fall 2021
---------

* Minor internal improvements have been made.



pKa-Prospector  1.1.7
================================================================================

*Spring 2022*

* Minor internal improvements have been made.



pKa-Prospector  1.2.0
========================

*Fall 2022*

Minor internal improvements have been made.



pKa-Prospector  1.2.1
========================

Minor bug fixes
--------------------------------------------------------------------------------
* The ``status bar`` message now properly updates in cases when no results are found 
  from a ``Search``.


pKa-Prospector  1.2.2
========================

Minor internal improvements have been made.



pKa-Prospector  1.2.3
========================

Minor internal improvements have been made.



pKa-Prospector  1.2.4
========================

Minor internal improvements have been made.



#################################
pKa-Prospector 1.2.5
#################################

Minor internal improvements have been made.



Quacpac 2.3.0
================================================================================

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


Quacpac TK 2.3.0
================================================================================

Minor internal improvements have been made.




#################
ROCS 3.10.0
#################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


Shape TK 3.10.0
================================================================================

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

* When using the :ref:`Overlay<OEShape_OEOverlay_Overlay>`
  method in :ref:`OEOverlay<OEShape_OEOverlay>` for overlay optimization, any of the inertial start
  methods now automatically trigger an additional :ref:`as-is<OEShape_OEAsIsStarts>` start
  if the optimization results in similarity measures less than the original similarity.
  This improves the default behavior of :ref:`Overlay<OEShape_OEOverlay_Overlay>` for
  some calculations.

* The following modifications have been made to :ref:`OEOverlapPrepOptions<OEShape_OEOverlapPrepOptions>`
  to provide more flexibility in assigning color atoms during the :ref:`Prep<OEShape_OEOverlapPrep_Prep>` process
  in :ref:`OEOverlapPrep<OEShape_OEOverlapPrep>`:

    * Two new methods, :ref:`SetRemoveColor<OEShape_OEOverlapPrepOptions_SetRemoveColor>`
      and :ref:`GetRemoveColor<OEShape_OEOverlapPrepOptions_GetRemoveColor>`, have been added
      to enable removal or reassignment of color atoms.
    * The new methods :ref:`AddDuplicateSmarts<OEShape_OEOverlapPrepOptions_AddDuplicateSmarts>`,
      :ref:`GetDuplicateSmarts<OEShape_OEOverlapPrepOptions_GetDuplicateSmarts>`, and
      :ref:`ClearDuplicateSmarts<OEShape_OEOverlapPrepOptions_ClearDuplicateSmarts>` have been added
      to enable duplicate color atom removal based on provided SMARTS patterns.
    * Duplicate color atom removal is now more robust in keeping the central atoms instead 
      of the first atom that it encounters and in placing the remaining atoms appropriately 
      (at the center of corresponding clusters).
    * Defaults for :ref:`SetRemoveDuplicate<OEShape_OEOverlapPrepOptions_SetRemoveDuplicate>`
      and :ref:`SetDuplicateDistance<OEShape_OEOverlapPrepOptions_SetDuplicateDistance>`
      have been changed from ``False`` and `0.001` to ``True`` and `0.0`, respectively. This improves
      robustness but keeps the default behavior unchanged.

* A new method, :ref:`SetupFrame<OEShape_OEStarts_SetupFrame>`, has been added to :ref:`OEStarts<OEShape_OEStarts>`
  that simplifies setting up a reference frame for calculating the starts.


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

* The overlay optimization in :ref:`OEHermiteOverlay<OEShape_OEHermiteOverlay>`
  with the :ref:`OEAsIsStarts<OEShape_OEAsIsStarts>` start option has been updated to use Hermite
  expansions around the center of mass to prevent inconsistent overlaps when objects are
  far from the origin.

* Overlay optimization with the :ref:`Overlay<OEShape_OEOverlay_Overlay>`
  method in :ref:`OEOverlay<OEShape_OEOverlay>` now captures the fit conformer
  self-overlap and color scores more accurately during the optimization.




SiteHopper 2.1.4
================================================================================

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


SiteHopper TK 2.1.4
================================================================================

Minor internal improvements have been made.





#####################
SPRUCE 1.9.0
#####################

****************************************
Related Toolkit Information
****************************************


Spruce TK 1.9.0
================================================================================

New Features
--------------------------------------------------------------------------------
* The maximum cluster size for partial residues built using :ref:`OEBuildSidechains <OESpruce_OEBuildSidechains>` can 
  now be set in :ref:`OESidechainBuilderOptions <OESpruce_OESidechainBuilderOptions>`
  using :ref:`SetMaxClusterSize <OESpruce_OESidechainBuilderOptions_SetMaxClusterSize>`.

* The chemical component dictionary has been updated. However, if using mmCIF, the metadata will
  be used as primary information and the dictionary only engages if metadata is unavailable.

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

* An issue has been fixed in the routine to reassign ambiguous water and metals
  from packing residues to the protein chain of interest. The issue caused HEME analogs and connected amino acids
  to be soaked into a given chain ID.

* An issue has been fixed to allow :oe:cls:`OESpruce::OEHeterogenMetadata` to inform
  the component splitter during design unit generation and preparation. This also fixes an
  issue where the splitter would not allow reclassification of a metal ion to an excipient.

* An issue has been fixed that caused the option to collapse redundant alternate locations
  to improperly engage if there were multiple binding sites in a protein.

* An issue has been fixed that caused the option to collapse redundant alternate locations
  to improperly engage for different ligands in the same binding site.

* An issue has been fixed that caused :oe:func:`OESpruce::OEMutateResidues` to incorrectly
  leave the backbone nitrogen of a residue in a bad valence state when mutating from Proline.

* An issue has been fixed in :oe:func:`OESpruce::OEBuildSidechains` with the shell mutation option turned
  on that would leave side chains clashing with water molecules. The water molecules are now removed
  if the option to allow for removal of clashing waters is set to ``True``.




SZMAP 1.7.4
================================================================================

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


Szmap TK 1.7.4
================================================================================

Minor internal improvements have been made.





SZYBKI 2.9.2
================================================================================

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


Szybki TK 2.9.2
================================================================================

Minor internal improvements have been made.






Previous Release Highlights
==============================

.. toctree::
  :maxdepth: 1

  releasenotes2025_Fall
  releasenotes2025_Spr
  releasenotes2024_Fall
  releasenotes2024_Spr
  releasenotes2023_Fall
  releasenotes2023_Spr
  releasenotes2022_Fall
  releasenotes2022_Spr
  releasenotes2021_Fall
  releasenotes2021_Spr
  releasenotes2020_Fall
  releasenotes2020_Spr
  releasenotes2019_Nov
  releasenotes2019_May
  releasenotes2018_Nov


Highlights of Applications Release 2025.2
=============================================

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |PRELIMINARY-API| replace:: This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

.. |PRELIMINARY-CONSTANTS| replace:: These constants are preliminary and may be improved based on user feedback.

.. |TWOLANGUAGE| replace:: This API is currently available in C++ and Python.

.. |CPPONLY| replace:: This functionality is only available in the C++ toolkits. For other languages, we recommend using language-specific functionality instead.

.. |PYTHONONLY| replace:: This functionality is only available in the Python toolkits.

.. |NOPDFIMAGE| replace:: *There is no image available for the PDF version of this book.*

.. |DEPRECATED-API| replace:: This is a deprecated API.

.. |SUBWORKING| replace:: Substitutions are working!



Shape: Features Extension
-----------------------------------------------------------------------------

New functionalities have been added to improve **Shape TK** and **ROCS** handling 
of queries beyond those derived from molecules. Major new features include using 
queries consisting only of color atoms or Gaussians (Figure 1), and the ability 
to search a database of grids as well as molecules. The ability to work with non-molecular 
queries has also been enhanced by introducing a new algorithm to generate Gaussians 
from a grid that can better capture sparse grids (Figure 2).

.. figure:: /_images/color_only_overlay.png
   :width: 800pt
   :align: center

   **Figure 1.** A color-only query consisting only of color Gaussians (left). The overlay
   of a molecule on that color-only query (right).

.. figure:: /_images/grid_grid_overlay.png
   :width: 500pt
   :align: center

   **Figure 2.** The overlay of a grid on another grid as query.

Saiph TK: New Toolkit for ETL
-----------------------------------------------------------------------------

This release introduces **Saiph TK**, a toolkit for extracting, transforming, and 
loading (ETL) files, bringing the existing Orion ETL functionality for file conversion 
into the toolkits, providing greater accessibility and improved performance.

Major functionality in the **Saiph TK** includes conversion of various molecule 
file formats, including SMILES and CXSMILES, SD, Spruce TK design unit files, and Shape TK 
query files, into a set of records. **Saiph TK** also provides functionality to 
interconvert CSV files and records, and to create a Pandas dataframe directly from any 
supported format, enabling smooth integration of molecule objects into machine learning 
in Python.

OEChem TK and Spruce TK: Improvements to CIF File Format Support
-----------------------------------------------------------------------------

The Worldwide Protein Data Bank (wwPDB) has officially deprecated the legacy PDB file 
format in favor of mmCIF. The format has recently been expanded to include residue 
topology information and the RCSB has worked to ensure all deposited structures include 
these new mmCIF-specific categories. In alignment with wwPDB and RCSB recommendations, 
we now advise using the mmCIF format for all macromolecular structures.
 
To support the transition, the CIF file reader in **OEChem** has been improved particularly 
in regard to reading the mmCIF file format variant. New APIs have been added that 
allow parsing and modification of the mmCIF metadata. Improvements to CIF file writing 
has also been made to be more correct when header data is missing or has been manually 
altered.
 
The **Spruce** filter now leverages mmCIF header data to refine structure perception during 
standardization prior to preparation. Additionally, support has been added for reading 
structure factor CIF files into grids, replacing MTZ files for electron density maps.

..  _supported-app-platforms-fall-2025:

Supported Platforms
--------------------

  ===========  =======================
  OS           Versions
  -----------  -----------------------
  Linux        RHEL8/9, Ubuntu22/24
  Windows      Win10, Win11
  macOS        13, 14, 15
  ===========  =======================

Related Application Versions
-----------------------------

  ==============  ===========
  Application     Version
  --------------  -----------
  AFITT           3.0.3
  BROOD           4.2.1
  EON             3.1.2
  OEDocking       4.3.4
  OMEGA           6.1.1
  PICTO           5.1.4
  pKa-Prospector  1.2.6
  QUACPAC         2.2.7
  ROCS            3.9.0
  SiteHopper      2.1.3
  SPRUCE          1.8.0
  SZMAP           1.7.3
  SZYBKI          2.9.1
  VIDA            5.0.7
  ==============  ===========



Highlights of Applications Release 2025.1
=============================================

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |PRELIMINARY-API| replace:: This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

.. |PRELIMINARY-CONSTANTS| replace:: These constants are preliminary and may be improved based on user feedback.

.. |TWOLANGUAGE| replace:: This API is currently available in C++ and Python.

.. |CPPONLY| replace:: This functionality is only available in the C++ toolkits. For other languages, we recommend using language-specific functionality instead.

.. |PYTHONONLY| replace:: This functionality is only available in the Python toolkits.

.. |NOPDFIMAGE| replace:: *There is no image available for the PDF version of this book.*

.. |DEPRECATED-API| replace:: This is a deprecated API.

.. |SUBWORKING| replace:: Substitutions are working!



FastROCS: Grid Query Support
-----------------------------------------------------------------------------

The 2025.1 release adds support for grid shape queries in **FastROCS TK**, as is already 
available in the **Shape TK** and **ROCS**. The ability to use shape grids substantially 
expands the application of **FastROCS TK** to queries beyond those derived from molecules.

To assess the efficacy of grid-derived versus molecule-derived queries **ROCS** was run with 
a series of thirteen molecule-derived queries, as well as the corresponding grid-derived queries, 
against a database of 1M molecules and the top-ranked 10K hitlist for each of the 13 was retained. 
**FastROCS** was then run with the same molecule-derived and grid-derived queries, and the 
fraction of the top-ranked 10K hits in common with the reference ROCS hitlist was calculated 
(see Figure 1). The fraction of molecules in common is almost completely constant (compare 
the black and pink bars in Figure 1), whether FastROCS was used with a molecule-derived query 
or the corresponding grid-derived query.

.. figure:: /_images/ROCS_vs_FastROCS_shapeonly.png
   :width: 750pt
   :align: center

   **Figure 1.** Thirteen query molecules and their shape grids (left). A graph of **ROCS** 
   versus **FastROCS** overlap in finding the same molecules in the hit list (right).

Bioisostere TK: Feature Extensions
-----------------------------------------------------------------------------

New functionality has been added to **Bioisostere TK**, bringing all features of the 
**BROOD** application into the toolkit. Some of the major new features in the toolkit 
include the ability to build queries in the presence of the target protein binding site 
and/or a selectivity protein, as well as creating bridging queries that connect two 
molecules. New APIs have also been added to enable checking whether compounds similar 
to the analogs generated by **BROOD** exist in commercial or internal databases, allowing 
a chemist to consider molecules available for purchase before undertaking the synthesis 
of a given analog.

With all of the **BROOD** functionality now available in Bioisostere TK, **BROOD** has been 
reengineered with **Bioisostere TK** to simplify and streamline coordination with the toolkit, 
ensuring that consistent results are provided between **BROOD** and **Bioisostere TK**. The 
graphical application **vBROOD** has been also been rewired to the newly engineered **BROOD**.

Representation of both active site and selectivity proteins in **Bioisostere TK**, **BROOD**, 
and **vBROOD** has been modified to work with the **OEDesignUnit**.

.. figure:: /_images/brood_query_in_active_site.png
   :width: 350pt
   :align: center

   **Figure 2.** Building a **BROOD** query in a protein active site.

SZYBKI: Robust Protein–Ligand Optimization
-----------------------------------------------------------------------------

The robustness of ligand optimization in a protein active site has been improved in both 
**Szybki TK** and **SZYBKI**.

Optimization failures due to non-planarity in aromatic rings of optimized structures are now 
separated from those due to excess atomic overlap in the starting structures, allowing better handling 
of failed optimizations. Failures due to a low level of aromatic ring bending, which is a common 
artifact of force-field-based optimization, can now be ignored, producing a substantial increase 
in successful ligand optimizations. The criterion for flagging an optimized structure as having 
bent aromatic rings has also been modified. Overall, the revised algorithm allows more structures 
to pass through the minimization process, while still giving the user the ability to flag results 
with deformed aromatic rings.

Besides these algorithmic modifications, there are improvements in integrating optimization of 
**POSIT** generated pose and in assigning **AM1BCCELF10** charges to ligands, with **SZYBKI**.

..  _supported-app-platforms-spring-2025:

Supported Platforms
--------------------

  ===========  =======================
  OS           Versions
  -----------  -----------------------
  Linux        RHEL8/9, Ubuntu22/24
  Windows      Win10, Win11
  macOS        13, 14, 15
  ===========  =======================

Related Application Versions
-----------------------------

  ==============  ===========
  Application     Version
  --------------  -----------
  AFITT           3.0.2
  BROOD           4.2.0
  EON             3.1.1
  OEDocking       4.3.3
  OMEGA           6.1.0
  PICTO           5.1.3
  pKa-Prospector  1.2.5
  QUACPAC         2.2.6
  ROCS            3.8.0
  SiteHopper      2.1.2
  SPRUCE          1.7.0
  SZMAP           1.7.2
  SZYBKI          2.9.0
  VIDA            5.0.7
  ==============  ===========



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |PRELIMINARY-API| replace:: This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

.. |PRELIMINARY-CONSTANTS| replace:: These constants are preliminary and may be improved based on user feedback.

.. |TWOLANGUAGE| replace:: This API is currently available in C++ and Python.

.. |CPPONLY| replace:: This functionality is only available in the C++ toolkits. For other languages, we recommend using language-specific functionality instead.

.. |PYTHONONLY| replace:: This functionality is only available in the Python toolkits.

.. |NOPDFIMAGE| replace:: *There is no image available for the PDF version of this book.*

.. |DEPRECATED-API| replace:: This is a deprecated API.

.. |SUBWORKING| replace:: Substitutions are working!



Release Highlights 2024.2.1
=============================

The **OEApplications 2024.2.0** is a bug-fix of the **OEApplications 2024.2.0** release,
and depends on **OEToolkits 2024.2.1**.

  * :ref:`section_oechemtk_releasenotes_4111`
  * :ref:`section_sprucetk_releasenotes_1611`

Release Highlights 2024.2.0
=============================

..  raw:: html

    <!-- The script tag should live in the head of your page if at all possible -->
    <script type="text/javascript" async src="https://play.vidyard.com/embed/v4.js"></script>

    <!-- Put this wherever you would like your player to appear -->
    <img
      style="width: 100%; margin: auto; display: block; max-width: 600px;"
      class="vidyard-player-embed"
      src="https://play.vidyard.com/aJobbXVTJT1aZFdsr1WUEr.jpg"
      data-uuid="aJobbXVTJT1aZFdsr1WUEr"
      data-v="4"
      data-type="inline"
      data-width="600"
    />
    <p>

OMEGA: Thompson Sampling for Torsion Driving
-----------------------------------------------------------------------------

A Bayesian approach to explore conformer space with torsion driving has been added as an alternative
to the exhaustive searching of the space in **OMEGA**. This uses the framework of Thompson sampling  
to quickly direct the conformer search towards the low energy structures, reducing the time required
to find the lowest energy conformer. As such, Thompson sampling is particularly suitable for generating
small to moderately sized ensembles, such as used in the ``FastROCS`` or ``ROCS`` mode.
Thompson sampling provides significant speedup for such ensemble generation, particularly for molecules 
with a large number of rotors.

Conformer ensembles for ``FastROCS`` usage are generated with **OMEGA** using both the standard
exhaustive sampling and the newly implemented Thompson sampling, for ~5500 Iridium HT protein bound
small molecule crystal structures. Performance between the two sampling methods is compared
in terms of RMSD between the generated ensemble and the crystal pose, and in the time required to
generate the ensembles.  The results of the comparison, as shown in Figure 1 below, show that
the accuracy of the generated ensembles, measured in RMSD, remains unaffected when using
exhaustive versus Thompson sampling, whereas there is significant reduction in time usage to
generate those ensembles when using Thompson sampling, especially as the size of the molecules grows.

.. figure:: /_images/omega_thompson_mmds.png
   :width: 550pt
   :align: center

   **Figure 1.** Comparison of **OMEGA** performance between exhaustive and Thompson sampling.

Ligand-based virtual screening performance, using both the exhaustive and Thompson sampling
generated ensembles, was also compared and displayed in Figure 2. The comparisons were performed
using directory of useful decoys (DUD-Z) datasets containing 38 targets. The results ensure that
there is no meaningful change in accuracy when using Thompson sampling for ensemble generation
for usage in ligand-based virtual screening.

.. figure:: /_images/omega_thompson_vs.png
   :width: 350pt
   :align: center

   **Figure 2.** Comparison of performance of ligand-based virtual screening success rate
   with conformer ensembles generated using exhaustive versus Thompson sampling.

BROOD: Bioisosteric Fragment Replacement in Macrocyclic Peptides
-----------------------------------------------------------------------------

A new pose generation algorithm has been introduced in **Bioisostere TK**, as well as in **BROOD**, 
based on flexible overlay of shape, color, and force fields, as used in pose generation with **ShapeFit**.
The new algorithm generates high quality poses of molecules that are obtained from fragment replacement
in **Bioisostere TK** and **BROOD**. The robust pose generation algorithm enables usage of **Bioisostere TK** 
and **BROOD** for molecules with complex geometry, including macrocyclic peptides. Figure 3 shows an
example of a residue fragment replacement in a macrocyclic peptide.

.. figure:: /_images/brood_macro_peptide.png
   :width: 350pt
   :align: center

   **Figure 3.** Bioisosteric replacement of a residue fragment in a macrocyclic peptide using **BROOD**.

Eon TK: New Toolkit for Overlay Optimization with Shape and Charge Density
-----------------------------------------------------------------------------

The 2024.2 release introduces **Eon TK**, a new toolkit for molecular similarity
based on shape and electrostatics. This provides toolkit-level access to the existing
**EON** application functionality. Following **EON**, the new toolkit has both
molecular charge density and electrostatic potential as options to use as
descriptors of electrostatic properties. Figure 4 shows an example of **EON** overlay
with charge density visualization.

.. figure:: /_images/eon_electrostatic_overlay.png
   :width: 550pt
   :align: center

   **Figure 4.** **EON** shape charge density overlay between two molecules.

**Eon TK** provides tools for molecular overlay optimization with shape and charge density,
similarity estimation based on shape and charge density or electrostatic potential, and
corresponding hit list building.

..  _supported-platforms-fall-2024:

Supported Platforms
========================

  ===========  =======================
  OS           Versions
  -----------  -----------------------
  Linux        RHEL8/9, Ubuntu20/22
  Windows      Win10, Win11
  macOS        12, 13, 14
  ===========  =======================

Related Application Versions
===============================

  ==============  ===========
  Application     Version
  --------------  -----------
  AFITT           3.0.1
  BROOD           4.1.0
  EON             3.1.0
  OEDocking       4.3.2
  OMEGA           6.0.0
  PICTO           5.1.2
  pKa-Prospector  1.2.4
  QUACPAC         2.2.5
  ROCS            3.7.0
  SiteHopper      2.1.1
  SPRUCE          1.6.1
  SZMAP           1.7.1
  SZYBKI          2.8.0
  VIDA            5.0.7
  ==============  ===========



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |PRELIMINARY-API| replace:: This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

.. |PRELIMINARY-CONSTANTS| replace:: These constants are preliminary and may be improved based on user feedback.

.. |TWOLANGUAGE| replace:: This API is currently available in C++ and Python.

.. |CPPONLY| replace:: This functionality is only available in the C++ toolkits. For other languages, we recommend using language-specific functionality instead.

.. |PYTHONONLY| replace:: This functionality is only available in the Python toolkits.

.. |NOPDFIMAGE| replace:: *There is no image available for the PDF version of this book.*

.. |DEPRECATED-API| replace:: This is a deprecated API.

.. |SUBWORKING| replace:: Substitutions are working!



Release Highlights 2024.1.3
=============================

The **OEApplications 2024.1.3** is a bug-fix of the **OEApplications 2024.1.0** release,
and depends on **OEToolkits 2024.1.3**.

  * :ref:`section_eon_releasenotes_3003`
  * :ref:`section_oefftk_releasenotes_2713`
  * :ref:`section_szybkitk_releasenotes_2713`
  * :ref:`section_oedockingtk_releasenotes_4313`
  * :ref:`section_graphemetk_releasenotes_1513`

Release Highlights 2024.1.0
=============================

..  raw:: html

    <script type="text/javascript" async src="https://play.vidyard.com/embed/v4.js"></script>

    <!-- Put this wherever you would like your player to appear -->
    <img
      style="width: 100%; margin: auto; display: block; max-width: 600px;"
      class="vidyard-player-embed"
      src="https://play.vidyard.com/CMZ6j9fLPERatLydBgqfCb.jpg"
      data-uuid="CMZ6j9fLPERatLydBgqfCb"
      data-v="4"
      data-type="inline"
      data-width="600"
    />
    <p>

EON: Overlay Optimization with Shape and Charge Density
-----------------------------------------------------------------------------

**EON**, the tool for molecular similarity based on shape and electrostatics, has been
reimagined with the addition of charge density as a descriptor for electrostatic properties.
By replacing electrostatic potential with molecular charge density as the primary 
descriptor of electrostatic properties, **EON** no longer requires the input molecules to
be pre-aligned with the query molecule. Instead, **EON** now aligns the input molecules 
using shape- and electrostatics-based overlay optimization, where electrostatics are modeled via
molecular charge density. **EON** still has the option to use electrostatic potential as
a measure of similarity, if desired. Figure 1 shows an example of **EON** overlay with charge 
density visualization.

.. figure:: /_images/eon_v3_shape_charge_overlay.png
   :width: 350pt
   :align: center

   **Figure 1.** **EON** shape charge density overlay between two molecules.

Even with the addition of overlay optimization within the workflow, the new **EON** is
now significantly faster compared to the previous version; and yet, as a
tool for virtual screening with shape and charge similarity, the behavior of **EON** remains the same. When compared to
**ROCS**, **EON** lags slightly when measured in terms of virtual screening success
rates but excels in finding hits that are more chemically diverse.

.. program:: eon

Performance of the previous and current versions of **EON**, as compared to **ROCS**,
are displayed in Figure 2. The comparisons were performed using multi-query directory of
useful decoys (MDUD) datasets containing 38 targets. The current version of **EON**
overlays and scores with shape and charge similarity. A command line flag :option:`-potential` supports the rescoring
of shape- and charge-aligned conformers with shape and electrostatic potential similarity. The current default version
of **EON** is now almost as fast as **ROCS**, as can be seen in the right-hand plot below.

.. figure:: /_images/eon_v3_vs_mdud_comparison_of_methods.png
   :width: 550pt
   :align: center

   **Figure 2.** Comparison of performance of **EON** and **ROCS** for virtual screening 
   success rate (left); for chemical diversity of actives found (middle); and for the speed of
   calculations (right).  “Current” refers to the default version using shape and charge density for similarity, and “current
   (potential)” refers to **EON** using shape and electrostatics.

FLYNN: Ligand fitting for Cryo-EM
-----------------------------------------------------------------------------

**FLYNN**, the tool for fitting small molecules to electron density, has been extended to 
support density maps generated through **cryo-electron microscopy (cryo-EM)**.

**FLYNN** is a powerful tool for ligand fitting that uses adiabatic fitting to generate 
the best-fitting, lowest strain conformers consistent with experimental electron densities 
and structural models. This tool was one of the first to enable high-quality, physics-informed 
pockets and poses from X-ray crystallographic models. **FLYNN** has now been updated
to enable researchers to access the same powerful insights from maps and models generated 
through cryo-electron microscopy (cryo-EM).

.. figure:: /_images/FLYNN_for_CryoEM.png
   :width: 500 pt
   :align: center

   **Figure 3.** Ligand fitting with **FLYNN** to predict binding pockets and poses consistent
   with electron density from cryo-electron microscopy (cryo-EM).

Hydrogen Placement Updates in **SPRUCE**
-----------------------------------------------------------------------------

In the 2024.1 release of **SPRUCE**, several improvements have been made to :ref:`OEPlaceHydrogens <OEBio_OEPlaceHydrogens>` to handle metal cation chelation effects
on the nearby protonation states, specifically for ligands.
The changes shown in Figure 5 below highlight new state and optimized geometries for sulfonamide, hydroxamate, phosphate, and borate groups.
In addition, changes have been made around geometries for  sp\ :sup:`3`  secondary amines.
Lastly, improvements have been added in :ref:`OEProtonateDesignUnit <OESpruce_OEProtonateDesignUnit>` to allow for protonation state changes
related to the detection of unfavorable acceptor–acceptor clashes, resulting in a more favorable hydrogen bond network.

.. figure:: /_images/Hplacement.png
   :width: 500pt
   :align: center

   **Figure 4.** Examples of improved chelator interactions and deprotonation rules for different moieties: hydroxamate, sulfonamide, and phosphates/borates.
   Also, on the bottom right, an example of improved interaction networks with acceptor–acceptor heuristic fixes.

Bioisostere TK: New Toolkit for Bioisosteric Fragment Replacement
-----------------------------------------------------------------------------

The 2024.1 release introduces **Bioisostere TK**, a new toolkit for bioisosteric
analog generation. It involves replacing a portion of a lead compound with fragments
that have similar shape and electrostatics but with potentially novel connectivity
and chemistry. This provides toolkit level access to the existing
**BROOD**  application functionality.

**Bioisostere TK** also brings several additional functionalities. At its core are tools
for fragment-based modeling, such as fragment creation, fragment conformer generation, and
fragment alignment and similarity in 3-dimensional space. **Bioisostere TK** brings OpenEye's
shape-, color-, and electrostatics-based molecular similarity tools into fragment-based similarity.
It also exposes tools for the generation of 3D molecule conformers with fragment
replacement.

An example of fragment alignment with **Bioisostere TK** based on shape and color
is shown in Fopeigure 3. The attachment points in both the reference and fit fragments are
marked in purple. The fragment overlay highlights how special attention is paid to the
overlay of the attachment points.

.. figure:: /_images/fragment_overlay.png
   :width: 500pt
   :align: center

   **Figure 5.** Fragment overlay between a reference and a fit fragment.

..  _supported-platforms-spring-2024:

Supported Platforms
========================

  ===========  =======================
  OS           Versions
  -----------  -----------------------
  Linux        RHEL8/9, Ubuntu20/22
  Windows      Win10, Win11
  macOS        12, 13, 14
  ===========  =======================

Related Application Versions
===============================

  ==============  ===========
  Application     Version
  --------------  -----------
  AFITT           3.0.0
  BROOD           4.0.0
  EON             3.0.0
  OEDocking       4.3.1
  OMEGA           5.1.0
  PICTO           5.1.1
  pKa-Prospector  1.2.3
  QUACPAC         2.2.4
  ROCS            3.6.2
  SiteHopper      2.1.0
  SPRUCE          1.6.0
  SZMAP           1.7.0
  SZYBKI          2.7.1
  VIDA            5.0.6
  ==============  ===========



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |PRELIMINARY-API| replace:: This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

.. |PRELIMINARY-CONSTANTS| replace:: These constants are preliminary and may be improved based on user feedback.

.. |TWOLANGUAGE| replace:: This API is currently available in C++ and Python.

.. |CPPONLY| replace:: This functionality is only available in the C++ toolkits. For other languages, we recommend using language-specific functionality instead.

.. |PYTHONONLY| replace:: This functionality is only available in the Python toolkits.

.. |NOPDFIMAGE| replace:: *There is no image available for the PDF version of this book.*

.. |DEPRECATED-API| replace:: This is a deprecated API.

.. |SUBWORKING| replace:: Substitutions are working!



******************************
Release Highlights 2023.2.3
******************************

  * Sage force field (Sage 2.1.0), from the Open Force Field Consortium, is now
    available in **OMEGA** as a complement to MMFF94.
  * The defaults for Sage force field from the Open Force Field Consortium have been updated
    to the latest 2.1.0 version, everywhere Sage is supported.
  * The built-in fragment library in **OMEGA** has been updated; expanding on 80 K fragments
    in the previous library, the new fragment library contains approximately 540 K fragments.
  * Stereo-enumeration options in **Flipper** have been improved to allow fine-grained
    control over enumerating different types of atom and bond stereocenters in an uncoupled manner.
  * The torsion scanning algorithm in **SZYBKI** has been improved by adding the ability to optimize
    in internal coordinate space.
  * Protein–ligand optimization with FF14SB-OpenFF in **SZYBKI** has been improved for performance
    and robustness.
  * Support for PDBx/mmCIF in **OEChem TK** has been improved, following the format updates to
    PDB entries by `wwPDB <https://www.wwpdb.org/>`_. The MMCIF reader now runs on Gemmi version 0.6.2.
  * A preliminary API has been added to provide reaction automapping ability, based on the
    maximum common substructure, enhancing reaction support in **OEChem TK**.
  * Python toolkit packaging has been improved to use `pyproject.toml <https://packaging.python.org/en/latest/guides/writing-pyproject-toml/>`_ to declare metadata
    and dependencies.

..  raw:: html

    <!-- The script tag should live in the head of your page if at all possible -->
    <script type="text/javascript" async src="https://play.vidyard.com/embed/v4.js"></script>
    <!-- Put this wherever you would like your player to appear -->
    <img
      style="width: 100%; margin: auto; display: block; max-width: 600px;"
      class="vidyard-player-embed"
      src="https://play.vidyard.com/U4RJuy7C54uCfLsFDMsBhU.jpg"
      data-uuid="U4RJuy7C54uCfLsFDMsBhU"
      data-v="4"
      data-type="inline"
      data-width="600"
    />
    <p>

Supported Platforms
=================================================================================

  ===========  =======================
  OS           Versions
  -----------  -----------------------
  Linux        RHEL8/9, Ubuntu20/22
  Windows      Win10, Win11
  macOS        12, 13
  ===========  =======================

Related Application Versions
=================================================================================

  ==============  ===========
  Application     Version
  --------------  -----------
  AFITT           2.6.4
  BROOD           3.2.2
  EON             2.4.2
  OEDOCKING       4.3.0
  OMEGA           5.0.0
  PICTO           5.1.0
  pKa-Prospector  1.2.2
  QUACPAC         2.2.3
  ROCS            3.6.1
  SiteHopper      2.0.4
  SPRUCE          1.5.3
  SZMAP           1.6.7
  SZYBKI          2.7.0
  VIDA            5.0.5
  ==============  ===========



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |PRELIMINARY-API| replace:: This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

.. |PRELIMINARY-CONSTANTS| replace:: These constants are preliminary and may be improved based on user feedback.

.. |TWOLANGUAGE| replace:: This API is currently available in C++ and Python.

.. |CPPONLY| replace:: This functionality is only available in the C++ toolkits. For other languages, we recommend using language-specific functionality instead.

.. |PYTHONONLY| replace:: This functionality is only available in the Python toolkits.

.. |NOPDFIMAGE| replace:: *There is no image available for the PDF version of this book.*

.. |DEPRECATED-API| replace:: This is a deprecated API.

.. |SUBWORKING| replace:: Substitutions are working!



******************************
Release Highlights 2023.1.1
******************************

The **OEApplications 2023.1.1** is a bug-fix of the **OEApplications 2023.1.0** release.

  * :ref:`section_oedocking_releasenotes_4211`
  * :ref:`section_spruce_releasenotes_1521`

******************************
Release Highlights 2023.1.0
******************************

..  raw:: html

    <!-- The script tag should live in the head of your page if at all possible -->
    <script type="text/javascript" async src="https://play.vidyard.com/embed/v4.js"></script>
    <!-- Put this wherever you would like your player to appear -->
    <img
      style="width: 100%; margin: auto; display: block; max-width: 600px;"
      class="vidyard-player-embed"
      src="https://play.vidyard.com/haNztpX3JmqF3A35LkYyVZ.jpg"
      data-uuid="haNztpX3JmqF3A35LkYyVZ"
      data-v="4"
      data-type="inline"
      data-width="600"
    />

Supported Platforms
=================================================================================

  ===========  =======================
  OS           Versions
  -----------  -----------------------
  Linux        RHEL8/9, Ubuntu20/22
  Windows      Win10, Win11
  macOS        11,12, 13
  ===========  =======================

Related Application Versions
=================================================================================

  ==============  ===========
  Application     Version
  --------------  -----------
  AFITT           2.6.3
  BROOD           3.2.1
  EON             2.4.1
  OEDOCKING       4.2.1
  OMEGA           4.2.2
  PICTO           5.0.0
  pKa-Prospector  1.2.1
  QUACPAC         2.2.1
  ROCS            3.6.0
  SiteHopper      2.0.3
  SPRUCE          1.5.2
  SZMAP           1.6.6
  SZYBKI          2.6.0
  VIDA            5.0.4
  ==============  ===========



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |PRELIMINARY-API| replace:: This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

.. |PRELIMINARY-CONSTANTS| replace:: These constants are preliminary and may be improved based on user feedback.

.. |TWOLANGUAGE| replace:: This API is currently available in C++ and Python.

.. |CPPONLY| replace:: This functionality is only available in the C++ toolkits. For other languages, we recommend using language-specific functionality instead.

.. |PYTHONONLY| replace:: This functionality is only available in the Python toolkits.

.. |NOPDFIMAGE| replace:: *There is no image available for the PDF version of this book.*

.. |DEPRECATED-API| replace:: This is a deprecated API.

.. |SUBWORKING| replace:: Substitutions are working!



******************************
Release Highlights 2022.2.2
******************************

The **OEApplications 2022.2.2** is a bug-fix of the **OEApplications 2022.2.1** release,
and depends on **OEToolkits 2022.2.2**.

******************************
Release Highlights 2022.2.1
******************************

MCS based fix during OMEGA Conformer Generation
================================================

The ability to constrain a fragment of the molecules during conformer generation with torsion
driving in :ref:`OMEGA <omega_introduction>` and  the :ref:`OMEGA <omega_part_theory>` toolkit
has been extended to include fixing based on maximum common 
subgraph (MCS) match. In this mode of fixing, the MCS between the template ``fixmol`` and the generated 
molecule is determined, and subsequently that common subgraph portion of the generated molecule is 
fixed to the proved conformer of the ``fixmol``.

The MCS based fixing during conformer generation can be turned on by setting
:ref:`SetFixMCS <OEConfGen_OEConfFixOptions_SetFixMCS>` to ``true`` for use in the
:ref:`OMEGA <omega_part_theory>` toolkit.  Additional
API points have also been added to allow control during MCS search. A new flag ``-fixMCS`` is
available in the :ref:`OMEGA <omega_introduction>` application to facilitate this.

+------------------------------------------------------+---------------------------------------------------------+
| .. image:: images/2022-Fall/mcs_omega_3vv8.png       | .. image:: images/2022-Fall/mcs_omega_4bfd.png          |
|   :width: 90%                                        |    :width: 90%                                          |
|   :align: Center                                     |    :align: Center                                       |
|   :alt: Conformers for 3VV8_8838                     |    :alt: Conformers for 4BFD_4239                       |
+------------------------------------------------------+---------------------------------------------------------+

  **OMEGA generated conformers for two different molecules, with MCS based fix against a single bound 
  ligand pose. Figure shows that with MCS based fix, two different fragments 
  are fixed during conformer generation of the two different molecules.**

New ShapeFit Algorithm for Pose Prediction
============================================

The algorithm for pose prediction with the :ref:`SHAPEFIT <OEDocking_OEPositMethod_SHAPEFIT>`
method has been modified. The new algorithm simultaneously optimizes the shape and 
chemical similarity between the fit molecule and bound ligand, and intra-molecular 
force-field energies of the fit molecule. The new simultaneous optimization algorithm 
replaces the previous adiabatic optimization algorithm and is more robust. The new 
algorithm also offers flexibility to use different forcefields and uses the 
:ref:`SAGE <OEFF_OELigandFFType_SAGE>` force field by default. Another advantage of the new
algorithm is that it is capable of producing multiple distinct poses when desired. 
The new algorithm is automatically reflected in both the :ref:`OEPosit <OEDocking_OEPosit>` toolkit
and the :ref:`POSIT <chapter_posit>` application. ``ShapeFit`` is also now available in the
**OEDocking TK** as an independent API :ref:`OEShapeFit <OEDocking_OEShapeFit>`.

Cross docking experiments based on the 22 diverse kinase types presented in 
[Tuccinardi-2010]_ shows that ``ShapeFit`` accuracy is unaffected between the
previous and the new algorithm (when accuracy is measured as RMSD <=2.0). 
A balanced cross-docking set of 20,000 points, where points are equally distributed
over the various similarity regions and kinase types, was used. However, we see
clear indication that generating multiple poses helps increase the pose prediction accuracy.
A separate self-docking study based on the highly trustworthy iridium dataset ([Warren-2012]_) 
with 280 ligand-protein structures shows that new algorithm predicts poses that are 
closer to the x-ray crystallographic poses.

+------------------------------------------------------+-----------------------------------------------------------+
| .. image:: images/2022-Fall/RMSD_Cross_Docking.png   | .. image:: images/2022-Fall/RMSD_Self_Docking_Inset.png   |
|   :width: 90%                                        |    :width: 90%                                            |
|   :align: Center                                     |    :align: Center                                         |
|                                                      |                                                           |
+------------------------------------------------------+-----------------------------------------------------------+

**Left: Comparison of ShapeFit accuracy in a cross-docking experiment between the existing and the new algorithm. 
The x-axis shows the tanimotocombo similarity between the ligand and the bound ligand present in protein complex. 
The Y-axis shows the fraction of accurately predicted poses based on being within 2 angstroms of the 
experimental pose. Right: Comparison of ShapeFit accuracy in a self-docking experiment, between the existing and 
the new algorithm. Axes show the RMSD of generated poses with respect to the experimental pose.**

Protein-ligand Optimization with ff14SB forcefield and PB solvent model 
=========================================================================
Protein-ligand Optimization with ``ff14SB-OpenFF`` force field and Poisson-Boltzmann (PB) solvent model 
is now available both in :ref:`SZYBKI <szybki_overview>` and the :ref:`SZYBKI <szybki_part_theory>` toolkit.

In the **SZYBKI TK**, the functionality is available through the :ref:`OEFixedProteinLigandOptimizer <OESz_OEFixedProteinLigandOptimizer>`
and the :ref:`OEFlexProteinLigandOptimizer <OESz_OEFlexProteinLigandOptimizer>` APIs, and can be enabled by setting
:ref:`PB <OESz_OESolventModel_PB>` as the value in :ref:`SetSolventModel <OESz_OEProteinLigandOptOptions_SetSolventModel>`.
In **SZYBKI** both the :ref:`OptLigandInDU` and :ref:`OptimizeDU` applications now accept ``pb`` as value
for ``-solventModel``.

Optimization of 244 highly trustworthy x-ray structures of protein-ligand complexes from the 
iridium dataset ([Warren-2012]_) with and without PB solvation 
and with ``ff14SB-Sage`` forcefield shows better accuracy for the optimized ligand poses when PB solvation
is turned on. Accuracy is measured as the RMSD between the crystallographic ligand pose and the optimized
pose. On an average PB solvation optimized structures have an RMSD of 0.31 angstroms, compared to a value of
0.55 angstroms when explicit solvation is not turned on. A paired T-test suggests that the average improvement 
of 0.24 angstroms is statistically significant with a p value of 0.00001.  Turing on the solvation effects also
removes any significant deviations (RMSD > 2 angstroms) of pose, as was seen for a few cases when optimization was
performed in vacuum.

..  figure:: /_images/pb_opt_rmsd.png
    :width: 60%
    :align: center

    **Comparison of RMSD for Flexible protein-ligand optimization of x-ray structures with
    and without PB solvation and with ff14SB-Sage forcefield.**

New **BROOD** Fragment Databases
==================================

Two new :ref:`BROOD <brood_introduction>` fragment databases, ``brood-database-ChEMBL31`` and ``brood-database-ChEMBL31_lite``, 
built from the latest version of ChEMBL, have been generated and are made available. The 
``brood-database-ChEMBL31`` contains all possible fragments up to 3 attachment points, whereas
the ``brood-database-ChEMBL31_lite`` is curated to prioritize fragments with medicinal relevance.

Limited validation, with 29 different queries across 14 molecules, shows that the number of hits of
druglike molecules obtained from the new databases are within 1% of those generated from the existing 
database ``brood-database-chembl-3.0.0``.  Comparison of belief score, a measure of potential activity
of the generated hits, also shows that the hits generated from the new databases are at least as
good as those generated from the existing database.

+------------------------------------------------------+---------------------------------------------------------+
| .. image:: images/2022-Fall/filtered_molecules.png   | .. image:: images/2022-Fall/Belief_score_lineplot.png   |
|   :width: 90%                                        |    :width: 90%                                          |
|   :align: Center                                     |    :align: Center                                       |
|                                                      |                                                         |
+------------------------------------------------------+---------------------------------------------------------+

**Left: Comparison of the number of hits of druglike molecules using the brood-database-chembl-3.0.0 (ChEMBL20),
brood-database-ChEMBL31 (ChEMBL31) and brood-database-ChEMBL31_lite (ChEMBL31_lite) fragment databases. Right: 
Comparison of the belief score distribution of all the hits generated using the ChEMBL20, ChEMBL31 and 
ChEMBL31_lite fragment databases.** 

Supported Platforms
=================================================================================

  ===========  =======================
  OS           Versions
  -----------  -----------------------
  Linux        RHEL7/8, Ubuntu20/22
  Windows      Win10, Win11
  macOS        11, 12
  ===========  =======================

Related Application Versions
=================================================================================

  ==============  ===========
  Application     Version
  --------------  -----------
  AFITT           2.6.2
  BROOD           3.2.0
  EON             2.4.0
  OEDOCKING       4.2.0
  OMEGA           4.2.1
  PICTO           4.6.0
  pKa-Prospector  1.2.0
  QUACPAC         2.2.1
  ROCS            3.5.1
  SiteHopper      2.0.2
  SPRUCE          1.5.1
  SZMAP           1.6.5
  SZYBKI          2.5.1
  VIDA            5.0.3
  ==============  ===========

General Notices
=================================================================================

* Support for Ubuntu22 has been added.  Support for Ubuntu18 has been dropped.

* This is the last release to support macOS 11.  Support for macOS 13 will be added in the next release.

* This is the last release to support RHEL7.  Support for RHEL9 will be added in the next release.



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |PRELIMINARY-API| replace:: This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

.. |PRELIMINARY-CONSTANTS| replace:: These constants are preliminary and may be improved based on user feedback.

.. |TWOLANGUAGE| replace:: This API is currently available in C++ and Python.

.. |CPPONLY| replace:: This functionality is only available in the C++ toolkits. For other languages, we recommend using language-specific functionality instead.

.. |PYTHONONLY| replace:: This functionality is only available in the Python toolkits.

.. |NOPDFIMAGE| replace:: *There is no image available for the PDF version of this book.*

.. |DEPRECATED-API| replace:: This is a deprecated API.

.. |SUBWORKING| replace:: Substitutions are working!



******************************
Release Highlights 2022.1
******************************

Enhanced Stereo Information Support
====================================

The 2022.1 release adds support for enhanced stereochemistry designations in molecules,
defining relationships between stereocenters. Enhanced stereochemistry
information on any molecule is honored by :ref:`OEFlipper <oeconfgen_OEFlipper>`
during stereo enumeration when asked to do so by setting appropriate options. Enhanced
stereochemistry support has also been extended to both the :ref:`OMEGA <chapter_omega>` and
the :ref:`chapter_flipper` applications.

Support for :term:`CXSMILES` as a valid molecular input format via :ref:`OEFormat <oechem_OEFormat>`
has been added.  :term:`CXSMILES` is specifically
intended to support the import of `Enamine <https://enamine.net>`_ download structure files
containing enhanced stereochemistry designations. While many other features are possibly
provided in the :term:`CXSMILES` appendix information, only the enhanced stereochemistry group
information is supported at this time.   Please contact support@eyesopen.com with specific needs
for additional :term:`CXSMILES` features to allow prioritization in future releases.

**OMEGA** and **Flipper** applications can now accept molecule files in :term:`CXSMILES` format.

.. figure:: /_images/enhanced_stereo.png
   :width: 200pt
   :align: center

   **Molecule with enhanced stereo designation. Molecule has 16 stereoisomers when
   stereocenters are treated independently, and only 4 stereoisomers when the
   enhanced stereo is enabled**

Sheffield Solvation Model for Proteins
=======================================

The simple two parameter Sheffield Solvation Model (as introduced by Grant et al (\ [Grant-2007]_ \)
for calculating the electrostatic component of molecular solvation energy, is a semi-empirical model
that performs well for small molecules and requires little computational resource. This model does
not work well for macromolecules like proteins and complexes, where many of the atoms are hidden or
only partially exposed to the solvent.

A modified three parameter Sheffield Solvation Model is parameterized and implemented in this release,
where solvent exposure is treated by correcting the effective atomic radii with the introduction of
a third additional parameter. The new model is available as part of the
:ref:`OESheffield <OESheff_OESheffield>` API in the **OEFF toolkit**. The model is also available for use
through the :ref:`OEFixedProteinLigandOptimizer <OESz_OEFixedProteinLigandOptimizer>` and the
:ref:`OEFlexProteinLigandOptimizer <OESz_OEFlexProteinLigandOptimizer>` APIs in the **SZYBKI toolkit**, and the :ref:`OptLigandInDU`
and :ref:`OptimizeDU` applications in **SZYBKI**.

Electrostatic solvation energies for protein conformers are calculated using both the new Sheffield
Solvation Model and the Poisson–Boltzmann (PB) model, and the difference in solvation energies between
conformers of the same protein is compared between the two models. A set of 232 NMR proteins and peptide
structures were used for this study that produced 41491 solvation energy differences between pairs of
conformations. The results are compared in the image below.

.. figure:: /_images/protein_confs_sheffield_pb.png
   :width: 600pt
   :align: center

   **Comparison between Sheffield and PB of differential Electrostatic solvation energies between protein conformers**

Spruce Filter and Design Unit Validation
=========================================

New functionality for pre-processing inputs and validation of the
output ``Design Units`` has been added to **Spruce TK** in the form of two preliminary API classes, :ref:`OESpruceFilter <chapter_sprucetk_sprucefilter>` and
:ref:`OEValidateDesignUnit <chapter-sprucetk-validate-design-unit>`.
These classes are also used by the **SPRUCE** application to check and fix, if possible, inputs and to validate the resulting outputs.

OESpruceFilter performs a standardization and a filter check on input structures to use before prepping
this structure in **SPRUCE**. It automatically checks and fixes invalid component names, invalid residue
states,and  invalid metal bonds. It also checks for invalid CRYST1 from the header file, low overlap between
the electron density map and the structure, invalid sequence alignment, blank Chain IDs, and invalid
alternate locations. If the structure does not pass these tests, Spruce Filter will fail the structure.

The OEValidateDesignUnit function performs a check on the design units generated by
**SPRUCE**. It will report if the provided DU contains partial side chains, missing loops, implicit
hydrogens, incorrect partial charges, termini that are not capped properly, heavy atoms overlapping
with each other, and broken chains.

Multistate Heuristic pKa Model
===============================

The multistate heuristic pKa model is an extension of the existing pKa model in **OpenEye** software.
The existing model generates only one probable ionization state based on pKa estimated from
about 80 rules. With the development of this multistate pKa model, we are enhancing the
implementation with many more unique functional patterns in the form of pKa rules, identified
from OpenEye's internal pKa database, allowing generation of all ionization states possible
at physiological pH.

The model described herein uses SMARTS-based heuristics to assess the pKa of acidic or basic
functional groups of molecules. For all atoms of a query molecule, pKa is assessed as it belongs
to one of three classes: Acidic (pKa < 6.4), Basic (pKa > 8.4), and Neutral (6.4 < pKa < 8.4).
According to the assessed pKa class for each atom, it is either ionized and/or un-ionized at
pH 7.4. Any group with Acidic or Basic pKa range will result in one state, ionized or un-ionized
and a group with Neutral pKa range will result in both states, ionized and un-ionized. Based
on how many such functional groups there are in the molecule, and how many states are generated
for them, multiple molecules can be generated for all possible combinations of all possible
ionization states of acid/base groups.

The multistate heuristic pKa model is currently only available in the **Quacpac TK** as preliminary
API classes :ref:`OEMultistatepKaModel <OEProton_OEMultistatepKaModel>` and :ref:`OEMultistatepKaModelOptions <OEProton_OEMultistatepKaModelOptions>`.

Supported Platforms
=================================================================================

  ===========  =======================
  OS           Versions
  -----------  -----------------------
  Linux        RHEL7/8, Ubuntu18/20
  Windows      Win10, Win11
  macOS        10.15, 11, 12
  ===========  =======================

Related Application Versions
=================================================================================

  ==============  ===========
  Application     Version
  --------------  -----------
  AFITT           2.6.1
  BROOD           3.1.7
  EON             2.3.7
  OEDOCKING       4.1.2
  OMEGA           4.1.3
  PICTO           4.5.4
  pKa-Prospector  1.1.7
  QUACPAC         2.2.0
  ROCS            3.4.4
  SiteHopper      1.2.1
  SPRUCE          1.5.0
  SZMAP           1.6.4
  SZYBKI          2.5.0
  VIDA            5.0.2
  ==============  ===========

General Notices
=================================================================================

* Support for macOS 12 has been added.  Support for macOS 10.14 has been dropped.

* This is the last release to support macOS 10.15.

* Support for Windows 11 has been added for this release.

* This is the last release to support Ubuntu 18.04. Support for Ubuntu 22.04 will be added in the next release.



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |PRELIMINARY-API| replace:: This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

.. |PRELIMINARY-CONSTANTS| replace:: These constants are preliminary and may be improved based on user feedback.

.. |TWOLANGUAGE| replace:: This API is currently available in C++ and Python.

.. |CPPONLY| replace:: This functionality is only available in the C++ toolkits. For other languages, we recommend using language-specific functionality instead.

.. |PYTHONONLY| replace:: This functionality is only available in the Python toolkits.

.. |NOPDFIMAGE| replace:: *There is no image available for the PDF version of this book.*

.. |DEPRECATED-API| replace:: This is a deprecated API.

.. |SUBWORKING| replace:: Substitutions are working!



******************************
Release Highlights 2021.2
******************************

SiteHopper: New Toolkit for Protein Binding Site Comparison
================================================================================

The 2021.2 release introduces **SiteHopper TK**, a new toolkit for searching a database
containing design units for proteins with similar binding sites to a query design unit. 
The new **SiteHopper TK** provides toolkit level access to the
**SiteHopper**  application
functionality released in 2021.1.

Besides providing toolkit level access, the 2021.2 release also brings several other
improvements to **SiteHopper**. Efficiency of database building in **SiteHopper** is
enhanced with the use of a multi-threaded approach. Furthermore, search is now possible on the 
CPU, enabling cross platform support of the toolkit and application. On Linux machines with 
an NVIDIA graphics card, the GPU is used as a pre-screening method, speeding up the 
search dramatically. A feature to exclude results based on a similarity threshold has been 
added that allows for more diversity in the protein targets with similar binding sites.
The database storage format has also been revised.

An example of a **SiteHopper** produced hit is shown in the figure below. 1UYG is a structure
of human heat shock protein 90-alpha, bound to 8-(2,5-dimethoxy-benzyl)-2-fluoro-9H-purin-6-ylamine. 
5IUN is a structure of the DesK-DesR complex, bound to AMP-PCP. The image on the left shows the overlay 
of 1UYG (green) and 5UIN (light yellow), zoomed out to show the major structural differences between 
the two proteins. The image on the right zooms in on the binding sites, with a surface showing 
the type of residues present in each binding site. Blue represents acidic, red represents basic, 
yellow represents polar, and white represents non polar. Despite a sequence similarity of only 46%, 
1UYG and 5IUN may be targetable by similar ligands, as they have very similar steric and electrostatic 
properties in their binding sites.

+------------------------------------------------------+----------------------------------------------------------+
| .. image:: images/2021-Fall/1UYG_5IUN_whole.png      |    .. image:: images/2021-Fall/1UYG_5IUN_BSite_Focus.png |
|   :width: 75%                                        |    :width: 95%                                           |
|   :align: Center                                     |    :align: Center                                        |
|   :alt: View of the entire structures                |    :alt: Zoomed in view on the binding sites             |
+------------------------------------------------------+----------------------------------------------------------+

 .. rst-class:: center

**1UYG human hsp 90 (green) overlaid with 5UIN N-formyltransferase (yellow), full struture view (left), binding site view (right).**

SZYBKI: OpenFF-Sage force field support
================================================================================

The latest force field, **Sage**, from the `Open Force Field Initiative <https://openforcefield.org/>`_
has been added to **OEFF TK**, **Szybki TK**, and **SZYBKI**. The major features of the
**Sage** force field are outlined `here <https://openforcefield.org/community/news/general/sage2.0.0-release/.>`_.

New force field parameter classes :ref:`OESageParams <OEMolSmirnoff_OESageParams>` and
:ref:`OEFF14SBSageParams <OEFF_OEFF14SBSageParams>` have been added to the toolkit to support
the **Sage** parameters.  Three new force field classes,
:ref:`OESage <OEMolSmirnoff_OESage>`, :ref:`OEFF14SBSage <OEFF_OEFF14SBSage>`, and
:ref:`OESage <OEFF_OEFF14SBSageComplex>`, have also been introduced.
The **Sage** force field is now the default for free energy analysis of conformation
ensembles with :ref:`OEFreeFormConf <OESz_OEFreeFormConf>`, and the corresponding application **Freeform**.
The protein-ligand forcefield, **FF14SBSage**, is now the default
for protein-ligand optimization in :ref:`OEFixedProteinLigandOptimizer <OESz_OEFixedProteinLigandOptimizer>`
and :ref:`OEFlexProteinLigandOptimizer <OESz_OEFlexProteinLigandOptimizer>`,
:ref:`OptimizeDU`, and :ref:`OptLigandInDU`.

The **Sage** force field can be used in **SZYBKI** for ligand calculations, with
the ``-ff sage_openff2.0.0`` command line option, and for calculations involving proteins using
``-ff ff14sb_sage``.

OEChem: MMCIF and CIF writers
================================================================================

Functionality to write Crystallographic Information Files (CIF and MMCIF) has been added
to the **OEChem TK** in the 2021.2 release. Similar to writing other molecule file
formats in **OEChem TK**, CIF and MMCIF files can be written using the high level
:ref:`WriteMolecule <oechem_oewritemolecule>` function. Low level functionality for advanced
users is also provided through a new :ref:`OEWriteCIFFile <OEChem_OEWriteCIFFile>` function.

If the molecule does not contain residue information, it is written as a small molecule CIF file
if the data is available to do so (i.e. space group information). If residue information
is available, the writer checks the number of residues and the
molecule is either written as a chemical component dictionary entry
(in the event there is a single residue) or as a macromolecular
CIF file (MMCIF).

The small molecule CIF reader has also been improved for performance and robustness, and
round-tripping these files has been tested and validated using the
`checkCIF <http://checkcif.iucr.org/>`_  facility from
the `International Union of Crystallography (IUCR) <https://www.iucr.org/>`_.
The MMCIF parser based on
`Gemmi <https://gemmi.readthedocs.io/en/latest/>`_ has also been updated, and items parsed from  PDB metadata have been expanded for proper processing of the biomolecules with
**Spruce**.

Supported Platforms
=================================================================================

  ===========  =======================
  OS           Versions
  -----------  -----------------------
  Linux        RHEL7/8, Ubuntu18/20
  Windows      Win10
  macOS        10.14, 10.15, 11
  ===========  =======================

Related Application Versions
=================================================================================

  ==============  ===========
  Application     Version
  --------------  -----------
  AFITT           2.6.0
  BROOD           3.1.6
  EON             2.3.6
  OEDOCKING       4.1.1
  OMEGA           4.1.2
  PICTO           4.5.3
  pKa-Prospector  1.1.6
  QUACPAC         2.1.3
  ROCS            3.4.3
  SiteHopper      1.1.0
  SPRUCE          1.4.0
  SZMAP           1.6.3
  SZYBKI          2.4.0
  VIDA            5.0.1
  ==============  ===========

General Notices
=================================================================================

* This is the last release to support  macOS 10.14.
  Support for macOS 12 will be added in the next release.

* Support for Windows 11 will be added in the next release.



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |PRELIMINARY-API| replace:: This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

.. |PRELIMINARY-CONSTANTS| replace:: These constants are preliminary and may be improved based on user feedback.

.. |TWOLANGUAGE| replace:: This API is currently available in C++ and Python.

.. |CPPONLY| replace:: This functionality is only available in the C++ toolkits. For other languages, we recommend using language-specific functionality instead.

.. |PYTHONONLY| replace:: This functionality is only available in the Python toolkits.

.. |NOPDFIMAGE| replace:: *There is no image available for the PDF version of this book.*

.. |DEPRECATED-API| replace:: This is a deprecated API.

.. |SUBWORKING| replace:: Substitutions are working!



******************************
Release Highlights 2021.1
******************************

OESiteHopper: Application Suite for Rapid Protein Binding Site Comparison
================================================================================

The 2021.1 release introduces **SiteHopper**, which can search a database
containing hundreds of thousands of design units in a few minutes for
proteins with similar binding sites to a query design unit. **SiteHopper** will
output the most similar biomolecules, overlaid by binding site, for visualization
and analysis. A visual representation of the binding site is also output.
**SiteHopper** can also create databases for searching from a series of biomolecular
structures in ``OEDU`` format.

**SiteHopper** finds proteins with similar binding sites which searching by
sequence similarity would overlook. An example is shown in the figure below. 1UYG
is a structure of human heat shock protein 90-alpha, bound to
8-(2,5-dimethoxy-benzyl)-2-fluoro-9H-purin-6-ylamine. 5IUN is a structure of the
DesK-DesR complex, bound to AMP-PCP.

The image on the left shows the overlay of 1UYG (green) and 5UIN (light yellow),
zoomed out to show the major structural differences between the two proteins. The image on the right zooms
in on the binding sites, with a surface showing the type of residues present in each binding site. Blue represents
acidic, red represents basic, yellow represents polar, and white represents non polar.
Despite a sequence similarity of only 46%, 1UYG and 5IUN may be targetable by similar
ligands, as they have very similar steric and electrostatic properties in their
binding sites.

+------------------------------------------------------+---------------------------------------------------------+
| .. image:: images/2021-Spr/1UYG_5IUN_whole.png       |    .. image:: images/2021-Spr/1UYG_5IUN_BSite_Focus.png |
|   :width: 75%                                        |    :width: 95%                                          |
|   :align: Center                                     |    :align: Center                                       |
|   :alt: View of the entire structures                |    :alt: Zoomed in view on the binding sites            |
+------------------------------------------------------+---------------------------------------------------------+

  **1UYG human hsp 90 (green) overlaid with 5UIN N-formyltransferase (yellow), full struture view (left) and binding site view (right).**

OEDocking: Make Receptor (Receptors in Design Unit)
================================================================================

:ref:`OEReceptor <OEBio_OEReceptor>` as an integral part of an :ref:`OEDesignUnit <OEBio_OEDesignUnit>`,
with properly prepped structures and contained in an ``OEDU`` file, is fully integrated 
in all workflows. Receptors in a design unit can now be created using the 
:ref:`Make Receptor <chapter_makereceptor>` GUI application, as well as the
:ref:`SPRUCE <chapter_spruce>` and :ref:`ReceptorInDU` command-line utilities.

The :ref:`Make Receptor <chapter_makereceptor>` GUI application has been extended
to be a fully functional DesignUnit builder in addition to building receptors. A new
DesignUnit can be created from a ``PDB/MMCIF`` file (with or without an associated
``MTZ`` file), or by combining molecules from various molecule files of any format.
:ref:`SPRUCE <chapter_spruce>` options are exposed through a graphical interface giving
users control over the level of preparation the structure should go through.
Existing receptors, both in ``OEDU`` or ``OEB`` format, can also be opened and edited 
as desired in :ref:`Make Receptor <chapter_makereceptor>`.

:ref:`OEMakeReceptor <OEDocking_OEMakeReceptor>` now automatically detects protein constraints,
a functionality that was previously only available in :ref:`Make Receptor <chapter_makereceptor>`.
The detected protein constraints are kept disabled by default, and can be
completely turned off if desired. These constraints, along with any custom constraints,
can be enabled or otherwise edited both via the :ref:`OEMakeReceptor <OEDocking_OEMakeReceptor>`
interface, or using commands from :ref:`OEReceptorProteinConstraint <OEBio_OEReceptorProteinConstraint>` and
:ref:`OEReceptorCustomConstraints <OEBio_OEReceptorCustomConstraints>` classes in the toolkit.

.. figure:: /_images/Make_receptor_3TPP.png
   :width: 400pt
   :align: center

   **OEDocking receptor for the 3TPP BACE1 Complexed with Inhibitor with target structure, bound ligand, and a protein constraint. Displayed in Make Receptor viewer.**

Having the receptors as part of the design unit with properly prepped structures makes 
it easier for the docked and posed structures to be used in further downstream modeling, 
which is especially necessary when working with protein force fields like ``FF14SB``. 
The new receptors with properly prepped protein also enabled use of modern
force fields like ``FF14SB`` and ``Parsley`` for structure optimization
in flexible :ref:`POSIT <chapter_posit>`.

VIDA 5: Major Update and OEDesignUnit support
================================================================================

**VIDA** has undergone major changes including:

    * Upgrade to Python3.

    * Upgrade to Qt5 with PySide2 providing for user-interface improvements.

    * Updated to run on the same platforms as OpenEye Toolkits and Applications.

  This allows us to release **VIDA** along side the toolkits and applications in our twice-yearly releases.

  In addition, **VIDA** now has support for MMCIF files and improvements to I/O from other file format types.
  **VIDA** can also read prepared protein structures in :ref:`OEDesignUnit <OEBio_OEDesignUnit>` format produced
  with **SPRUCE** and **Make Receptor** along with the receptor objects that are now stored on these design units.

 .. figure:: /_images/DUReceptorSupport.png
   :align: center

   **VIDA DesignUnit Support with receptors showing the prepared beta-secretase structure 3TPP.**

Supported Platforms
=================================================================================

  ===========  =======================
  OS           Versions
  -----------  -----------------------
  Linux        RHEL7/8, Ubuntu18/20
  Windows      Win10
  macOS        10.14, 10.15, 11
  ===========  =======================

Related Application Versions
=================================================================================

  ==============  ===========
  Application     Version
  --------------  -----------
  AFITT           2.5.3
  BROOD           3.1.5
  EON             2.3.5
  OEDOCKING       4.1.0
  OMEGA           4.1.1
  PICTO           4.5.2
  pKa-Prospector  1.1.5
  QUACPAC         2.1.2
  ROCS            3.4.2
  SiteHopper      1.0.0
  SPRUCE          1.3.0
  SZMAP           1.6.2
  SZYBKI          2.3.1
  VIDA            5.0.0
  ==============  ===========

General Notices
=================================================================================

* **VIDA 5.0.0** is available as a separate download as part of this release.

* New application **SiteHopper** has been added to the application bundle and can run on any NVIDA GPU-enabled Linux platform.

* OpenEye applications and toolkits have not been optimized for the M1 Mac but run under Rosetta 2.

* Ubuntu 16.04 is no longer supported

* MacOS 10.13 is no longer supported.



.. _appshighlights_2020_2:

******************************
Release Highlights 2020.2.2
******************************

The **OEApplications 2020.2.2** is a bug-fix of the **OEApplications 2020.1** release,
and depends on **OEToolkits 2020.2.2**. Click on the below links for more information about
the bug fixes in this release:

  * :ref:`section_oedocking_app_releasenotes_4002`
  * :ref:`section_szybki_app_releasenotes_2302`
  * :ref:`section_spruce_app_releasenotes_1202`

******************************
Release Highlights 2020.2
******************************

.. _omegaApp_highlight_Fall2020:

OMEGA: New fragment library
================================================================================

A new enhanced fragment library has been created for use in **OMEGA**.
The new fragment library consists of more than 500,000 fragments that have been generated using the
MMFF force field.

This library is designed to reduce the run time of large-scale conformer
generation,
and therefore is not built into **OMEGA** but is available as a separate `download <http://www.eyesopen.com/database-downloads>`_.
To run **OMEGA** with the enhanced library, simply use the command line flag ``-addfraglib enhanced_fraglib.oeb.gz``.

The fragments have been collated from commonly used electronic
databases, such as Enamine Building Blocks. Consequently, dramatic
runtime performance improvements can be seen for the Enamine Real dataset, among
others, since less time is spent building fragments on the fly. Runtime performance improvements
can be seen for all datasets; the Platinum and Enamine Real sets show particular improvement
and run ~50% faster (benchmarks run on Ubuntu 16 with Intel(R) Xeon(R) Gold 6128 CPU 3.40GHz and NVIDIA Tesla V100 GPU).

.. figure:: /_images/Omega_FragLib_Runtime_Perf.png
   :width: 500pt
   :align: center

   **GPU-OMEGA runtime performance using the built-in fragment library compared to
   the new enhanced fragment library. Benchmark datasets are a filtered set of 2359 molecules of
   the Platinum dataset and 10,000 randomly chosen molecules of the Enamine Real,
   Mcule, and WuXi databases.**

The enhanced fragment library generates the same high-quality conformers as the built-in library,
as shown by the minimum RMSDs of the filtered Platinum dataset.

.. figure:: /_images/Omega_FragLib_Plat_Div_Perf.png
 :width: 400pt
 :align: center

 **Box plots showing minimum RMSDs of a filtered set of 2359 molecules of
 the Platinum dataset with the built-in fragment library and
 the new enhanced fragment library.**

Datasets can be downloaded from:
  * `Mcule <https://mcule.com/database/>`_
  * `Enamine Real <https://enamine.net/library-synthesis/real-compounds/real-database>`_
  * `Platinum Dataset <https://comp3d.univie.ac.at/servers-datasets/#c523270>`_
  * `WuXi <https://www.labnetwork.com/frontend-app/>`_

We are eager to get your feedback on the new enhanced fragment library. Please share
your experience with us at support@eyesopen.com.

.. _dockingApp_highlight_Fall2020:

OEDOCKING: Improved receptors
================================================================================

Receptors used in the **OEDocking TK** and the **OEDOCKING** applications,
including **FRED**, **HYBRID** and **POSIT**, have been improved
to take advantage of properly prepared structures from **SPRUCE**.  A new
``OEReceptor`` object has been introduced and is created and contained within an
``OEDesignUnit``.  Since an ``OEReceptor`` is now an integral part of an
``OEDesignUnit``, it is saved into an ``OEDU`` file along with a design unit.
There is no separate I/O for the receptors.

.. figure:: /_images/2IKO_receptor.png
   :width: 400pt
   :align: center

   **OEDocking receptor, along with the target structure and the bound ligand,
   for the 2IKO Human Renin Complexed with Inhibitor.**

Having the receptors as part of the design unit with properly prepped structures
makes it easier for the docked and posed structures to be used in further downstream
modeling, which is especially necessary with protein force fields like ``FF14SB``.  The
new receptor also assists with more flexible use of modern force fields like ``FF14SB``
and ``Parsley`` in **POSIT**.

.. _szybkiApp_highlight_Fall2020:

SZYBKI: A new protein force field
================================================================================

The ``AMBER FF14SB`` protein force field has been implemented in **OEFF TK**. This
new force field has also been made available in **SZYBKI** for optimizing both
protein and protein-ligand complexes.

``FF14SB`` is the most widely used protein force field for molecular dynamics or
any other force field-based calculations. It is also used in Orion molecular dynamics
package, and is the community gold standard for such calculations.

Supported Platforms
=================================================================================

  ===========  =======================
  OS           Versions
  -----------  -----------------------
  Linux        RHEL7/8, Ubuntu18/20
  Windows      Win10
  macOS        10.13, 10.14, 10.15
  ===========  =======================

Related Application Versions
=================================================================================

  ==============  ===========
  Application     Version
  --------------  -----------
  AFITT           2.5.2
  BROOD           3.1.4
  EON             2.3.4
  OEDOCKING       4.0.0
  OMEGA           4.1.0
  PICTO           4.5.1
  pKa-Prospector  1.1.4
  QUACPAC         2.1.1
  ROCS            3.4.1
  SPRUCE          1.2.0
  SZMAP           1.6.1
  SZYBKI          2.3.0
  ==============  ===========

General Notices
=================================================================================

* Support for Ubuntu16 has been dropped.  Support for Ubuntu20 has been added.



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |PRELIMINARY-API| replace:: This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

.. |PRELIMINARY-CONSTANTS| replace:: These constants are preliminary and may be improved based on user feedback.

.. |TWOLANGUAGE| replace:: This API is currently available in C++ and Python.

.. |CPPONLY| replace:: This functionality is only available in the C++ toolkits. For other languages, we recommend using language-specific functionality instead.

.. |PYTHONONLY| replace:: This functionality is only available in the Python toolkits.

.. |NOPDFIMAGE| replace:: *There is no image available for the PDF version of this book.*

.. |DEPRECATED-API| replace:: This is a deprecated API.

.. |SUBWORKING| replace:: Substitutions are working!



******************************
Release Highlights 2020.1.1
******************************

The **OEApplications 2020.1.1** is a bug-fix of the **OEApplications 2020.1** release,
and depends on **OEToolkits 2020.1.1**.

  * :ref:`section_omega_releasenotes_4006`

******************************
Release Highlights 2020.1
******************************

The **OEApplications 2020.1** is a bug-fix of the **OEApplications 2020.0** release,
and depends on **OEToolkits 2020.1**.

******************************
Release Highlights 2020.0
******************************

**OpenEye Toolkits** and **Applications** have been
integrated into a single release cycle. This will provide more consistency among our
products and enable a more robust and efficient development cycle. This integration reduces
release process management overehead, freeing developer time for new features and bug-fix
releases for critical issues.

OMEGA: GPU-OMEGA - GPU-accelerated torsion driving
================================================================================

The 2020.0 release introduces **GPU-OMEGA** to the **OMEGA** application suite to
provide accelerated torsion driving. It is
integrated into the existing **OMEGA** application; no additional
user actions are required to make use of this new feature. **GPU-OMEGA** detects any
supported Nvidia GPU on Linux platforms and accelerates performance
unless explicitly suppressed by using the option ``-useGPU false``. **GPU-OMEGA** is available with
all sampling modes except ``macrocycle``, which does not use the torsion driving
method for conformer generation. For more details on **GPU-OMEGA**, including prerequisites
and additional requirements for using ``dense`` mode, please see
:ref:`GPU-OMEGA<omega_gpuomega>`.

**GPU-OMEGA** performs at the same high level of accuracy as **Omega TK**, as shown
below using a filtered subset of the Platinum dataset [Friedrich-2017]_ [Hawkins-2020]_:

.. figure:: /_images/CPU_v_GPU_scatter_rmsd.png
   :width: 400pt
   :align: center

   **Comparison of the minimum RMSDs of CPU- and GPU-generated conformers against
   the experimental coordinates of a filtered subset of the Platinum dataset**

**GPU-OMEGA** was benchmarked against the CPU on AWS to demonstrate the achievable
performance on a `P3 instance <https://aws.amazon.com/ec2/instance-types/p3/>`_,
which houses a single `Nvidia Tesla V100 <https://www.nvidia.com/en-gb/data-center/tesla-v100/>`_
GPU. **GPU-OMEGA** was benchmarked with all supported sampling modes (``classic``, ``dense``,
``pose``, ``rocs``, and ``fastrocs``) using a subset of ~6000 molecules from the GSK TCAMs dataset
[Gamo-2010]_. The most impressive speed-up is seen with the ``dense`` sampling mode, with
a reduction in time from 120 hours to less than 4 hours.

.. figure:: /_images/GPUOmega_Modes_V100_perf_apps.png
   :width: 600pt
   :align: center

   **Elapsed time comparison between Omega and GPU-OMEGA on an AWS P3 instance
   when sampling a subset of the GSK-TCAMS dataset with classic, rocs, fastrocs, pose,
   and dense modes**

SPRUCE: Protein Loop Modeling
================================================================================

The 2020.0 release adds protein loop modeling to the **SPRUCE** application.
This approach relies on a template database derived from structures in the public
`RCSB Protein Data Bank <https://www.rcsb.org/>`_.
The database, which has been built for modeling loops that are 4-20 residues long by default,
is available for `download <http://www.eyesopen.com/db-downloads>`_
in a platform-independent format. A separate application,
:ref:`LoopDB_Builder <chapter_loopdb_builder>`, allows
appending additional structures to the existing database. For example, proprietary in-house
structures can be added, or the database can be completely rebuilt with
different options.

This approach has been validated on a public dataset from Rossi et al. [Rossi-2007]_.
The results shown below were generated by building the excised loops back into the dataset, where the
specific structures themselves were not part of the template database, and used the same success
criterion as in the paper (<2.5A backbone RMSD). The results are generally good and the median RMSD
is 0.6-0.7A (blue dots), irrespective of the length of the modeled loop.
The mean RMSD (green dots) may be higher as unsuccessful cases (gray bar) can deviate significantly
from the expected result. Only in a one case (out of ~200 loops), was a result not produced (red bar),
i.e. did not survive the search and filtering steps.

.. figure:: /_images/RossiLoops.png
   :width: 400pt
   :align: center

   **Performance assessment building loops ranging from 4-12 residues in length**

SZYBKI: Custom SMIRNOFF
================================================================================

The abilities of **SZYBKI** and **FreeForm** to use force fields based on SMIRNOFF
(SMIRks Native Open Force Field) specifications has been extended to use custom
versions of such force fields. The ``-ff`` parameter in both **SZYBKI** and **FreeForm**
now accepts XML files with SMIRNOFF specifications in addition to the predefined names
for built-in force fields.

The coverage of built-in force fields has also been extended by incorporating
``Parsley_OpenFF1.1.1``  from the
`Open Force Field Initiative <https://openforcefield.org/>`_.

General Notices
=================================================================================

* All applications, including GUI applications, are now available in the
  RHEL8 application bundle except for GPU-OMEGA, the CUDA-enabled feature of OMEGA.
  GPU-OMEGA will be supported in the next release when the toolkits have been upgraded to
  support CUDA 10.

* The application bundle for macOS is now notarized and can be run on macOS Catalina 10.15. Apple notarization
  gives users of our software more confidence that the Developer ID-signed software has been checked by Apple
  for malicious components.

* This is the last release to support Ubuntu16.04. Support for Ubuntu20.04 will be added in the next release.

* MacOS 10.12 is no longer supported.


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |PRELIMINARY-API| replace:: This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

.. |PRELIMINARY-CONSTANTS| replace:: These constants are preliminary and may be improved based on user feedback.

.. |TWOLANGUAGE| replace:: This API is currently available in C++ and Python.

.. |CPPONLY| replace:: This functionality is only available in the C++ toolkits. For other languages, we recommend using language-specific functionality instead.

.. |PYTHONONLY| replace:: This functionality is only available in the Python toolkits.

.. |NOPDFIMAGE| replace:: *There is no image available for the PDF version of this book.*

.. |DEPRECATED-API| replace:: This is a deprecated API.

.. |SUBWORKING| replace:: Substitutions are working!



******************************
Release Highlights 2019.Nov
******************************

SPRUCE: Application Suite for Biomolecular Structure Preparation
=================================================================================

The 2019.Nov release introduces **SPRUCE** which takes experimental
biomolecular structure data in either ``PDB`` or ``mmCIF`` formats, and prepares the structures
for use with downstream modeling applications.

With **SPRUCE**, the output for the prepared proteins is the recently
developed :ref:`OEDesignUnit <OEBio_OEDesignUnit>` object serialized to a new ``OEDU`` (OpenEye Design Unit) file format.
The prepared system is componentized into molecular categories including `protein`, `ligand`,
`nucleic`, `solvent`, and many other molecular types common to biomolecular experiments.
By default, hydrogens are added to systems using a tautomer search for any ligand, cofactor or other nonstandard residue molecules.
In addition, the system is split into distinct biological units and all final design unit structures
are superposed into a common frame of reference.

**SPRUCE** has been tested across a broad range of industry-relevant targets.  It
is built using the recently released **Spruce TK**, which has been used for virtual screening
and molecular dynamics simulations in **Orion**, as well as to prepare structures for
MacroMolecular Data Service (MMDS).

The figures below show one of the prepared OEDesignUnits for the PDB code 1TGV. 1TGV is a structure of E. coli Uridine Phosphorylase
complexed with 5-Fluorouridine and sulfate. In the figure on the left the entire homo-pentamer is shown. The binding site residues and
ligand atoms are shown explicitly with a wireframe representation to highlight the site of interest. Five OEDesignUnits are generated
for this PDB code, one focusing on each of the 5 binding sites in the pentamer. The binding site view shows the ligand bound pose with
OEInteractionHints highlighting various protein-ligand interactions.

+------------------------------------------------------+---------------------------------------------------------+
| .. image:: images/2019-Nov/1TGV_Prep_TertView.png    |    .. image:: images/2019-Nov/1TGV_Prep_BSite_Focus.png |
|   :width: 75%                                        |    :width: 95%                                          |
|   :align: Center                                     |    :align: Center                                       |
|   :alt: View of the entire structure                 |    :alt: Zoomed in view on the binding site             |
+------------------------------------------------------+---------------------------------------------------------+
|   Structure view                                     |     Binding site view                                   |
+------------------------------------------------------+---------------------------------------------------------+

SZMAP: Simplified Workflow
================================================================================

**SZMAP** now provides a simpler but enhanced workflow, using the newly released
**SPRUCE** technology for structure preparation.

Structures prepared in the ``OEDU`` file format from **SPRUCE** can be used as direct input
to **SZMAP** or **GamePlan** without the need for any further preparation steps.

The single utility application **Spruce4Szmap** replaces the three previous utility applications ``Pch``,
``MKHetDict``, and ``FixDupAtomNames``.  **Spruce4Szmap** also eliminates the need to use
the external program ``reduce`` as part of structure preparation workflow.

SZYBKI: SMIRNOFF
================================================================================

The 2019.Nov release incorporates the ability to use force fields based on SMIRNOFF
(SMIRks Native Open Force Field) specifications into **SZYBKI** and **FreeForm**.
Two such small molecule force fields, ``smirnoff99Frosst`` and ``OpenFF1.0.0``,
from the `Open Force Field Initiative <https://openforcefield.org/>`_ have been
incorporated in this release. Both the ``smirnoff99Frosst`` and ``OpenFF1.0.0`` force
fields can handle almost all pharmaceutically relevant chemical space.

The SMIRNOFF specification differs from traditional force field specifications principally
in the data representation of the chemistry. It uses extended SMARTS strings for parameters
instead of atom types, greatly reducing the number of interdependent parameters.

The Open Force Field Initiative is actively working on improvements to ``OpenFF1.0.0``, and
promises to bring newer force fields in the future. **OpenEye** plans to keep up to date with the latest
versions of these force fields as they become available.  A future release will  incorporate
the ability to allow using custom versions of SMIRNOFF force fields in **SZYBKI**.

General Notices
=================================================================================

* Windows installation behavior has changed.  Installation of **OpenEye-applications** bundle will now replace the previous version. See :ref:`Installation<installation_information>` for more information.

* All applications were ported to build using **OEToolkits 2019.Oct**.  The previous versions were built using **OEToolkits 2019.Apr**.

Platform Support
=================================================================================

* RHEL6 is no longer supported.

* Windows 7 is no longer supported.

* RHEL8 is now partially supported (command line applications only). Qt applications will be included in future releases once Qt is supported on RHEL8.


******************************
Release Highlights 2019.May
******************************

Windows Installer
=================================================================================

The installer for Windows has been upgraded to a standard Windows MSI installer.    This allows
administrators to perform silent installation by executing the installer with the ``/quiet`` argument.

OEZ Compressed File Format
================================================================================

A new compressed file format, ``OEZ``, has been introduced in **OEChem TK**. This format uses the `zstd <https://facebook.github.io/zstd/>`_ algorithm to efficiently compress individual multi-conformer molecules, making it well-suited to work with `OEMolDatabase <https://docs.eyesopen.com/toolkits/python/oechemtk/OEChemClasses/OEMolDatabase.html#OEChem::OEMolDatabase>`_ for fast read-only random access to molecules. Users can now use ``OEZ`` as the output format for **OMEGA** and as the input format for **ROCS**. For more details, see the `Compressed Input and Output <https://docs.eyesopen.com/toolkits/python/oechemtk/molreadwrite.html#section-molreadwrite-compressed>`_ section of the **OEChem TK** documentation.

.. note::

  This new file format is not backwards compatible. OpenEye applications and toolkits released before April 2019 will not be able to read or write this file format.

General Notices
=================================================================================

* MPI support for the applications on Linux and macOS is now based on Open MPI version 4.0.0.

* GUI applications in the **OpenEye** applications bundle — **vROCS**, **vBROOD**, **Make Receptor**, and **pKa-Prospector** — are not available on RHEL6. The RHEL6 package only includes command line tools.

* All applications were ported to build using **OEToolkits 2019.Apr**.  The previous versions were buiult using **OEToolkits 2018.Oct**.

* An issue that caused applications to hang when launched in multi-node openMPI  in some cluster configurations has been fixed.

Platform Support
=================================================================================

* This is the last release to support RHEL6

* This is the last release to support Windows 7

* Ubuntu 14 is no longer supported

* macOS 10.11 and 10.12 are no longer supported



******************************
OEApplications 2018.Nov
******************************

First release of all OpenEye Applications as a single package
================================================================================

This is the first release of **OpenEye Applications** as a single package.
It includes all the **OpenEye Applications**
suites except for **VIDA** and **AFITT**. The applications 
are built on top of the 2018.Oct release of the **OpenEye Toolkits**.

The application suites available as part of the package are:

	* **BROOD**
	* **EON**
	* **OEDocking**
	* **OMEGA**
	* **pKa-Prospector**
	* **QUACPAC**
	* **ROCS**
	* **SZMAP**
	* **SZYBKI**

ROCS: ROCS
================================================================================

**Shape TK** has gone through a major re-engineering in the 
`OpenEye Toolkits v2017.Oct <https://docs.eyesopen.com/toolkits/cpp/releasenotes/releasenotes2017_Oct.html>`_ 
release.  This release brings the new technology to **ROCS**. One consequence is that 
overlay optimization in **ROCS** is now approximately 10% faster than in its previous 
release. Feature improvements of future versions of **ROCS** will be derived from this 
new foundation.

QUACPAC: Tautomers
================================================================================

This release adds several improvements to the **Tautomers** application in
**QUACPAC**. Tautomer handling in molecular modeling and cheminformatics usually includes
three important functions:

* Generating a canonical protomer representation for duplicate-free storage

* Generating a single tautomer suitable for visualization by chemists and
  modelers

* Generating an ensemble of aqueous-phase tautomers suitable for molecular
  modeling

.. figure:: releasenotes/images/2018-Nov/tautomer-enumeration.*
   :width: 600pt
   :align: center

   **Example of generating an ensemble of biologically relevant tautomers**

Following the **Quacpac TK 2.0** release in 
`OpenEye Toolkits v2018.Oct <https://docs.eyesopen.com/toolkits/cpp/releasenotes/releasenotes2018_Oct.html>`_ , 
this release provides new APIs to cover each of these use-cases. Memory usage in 
cases where there are many possible tautomeric forms has been significantly improved.

General Notices
=================================================================================

* MPI support for the applications on Windows is now based on Microsoft's implementation 
  of MPI.  For Linux and macOS, MPI support is still based on Open MPI.

Platform Support
=================================================================================

* RHEL6 (x64), RHEL7 (x64)

* Ubuntu 14.04, Ubuntu16.04 (x64) LTS

* macOS 10.11, 10.12, 10.13, 10.14

* Windows 7/8.1/10 (64 bit)


Applications
===================

..  toctree::
    :maxdepth: 2

    gettingstarted
    afitt/index
    brood/index
    eon/index
    oedocking/index
    omega/index
    picto/index
    pka-prospector/index
    quacpac/index
    rocs/index
    sitehopper/index
    spruce/index
    szmap/index
    szybki/index
    vida/index
    include_doctheme_glossary
    bibliography


.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _applications-getting-started:

#############################
Getting Started
#############################

Welcome to the documentation for the |appspkgversion| release of OpenEye Applications.

.. toctree::
   :maxdepth: 2

   common/index
   intro
   include-from-theme



.. apps common documentation master file

.. _app-installation:

#################################
Installation and Platform Notes
#################################

.. toctree::
   :maxdepth: 2

   license
   install_std
   examples_data
   mpi
   uninstall_std


.. _oe_license:

*************************************************************************
Licenses for OpenEye Software
*************************************************************************

A license file from OpenEye, Cadence Molecular Sciences is required to run any OpenEye
application. A license file can be requested/obtained for any specific
applications by contacting OpenEye: https://www.eyesopen.com/contact.

At startup, the application looks for a valid license in the following default
locations:

* In a file specified by the environment variable :envvar:`OE_LICENSE`.  Example commands to set
  the environment variable:

  * Linux/UNIX and MacOS:

    ``export OE_LICENSE=/home/USERNAME/oe_license.txt``

    This can be executed in a shell prompt, or added to the user's ``~/.bash_profile``.
    If running `zsh`,  add to the user's ``.bash_profile`` and then include ``.bash_profile``
    in the user's ``.zshrc``.

  * Microsoft Windows:

    ``setx OE_LICENSE C:\Users\USERNAME\oe_license.txt`` to set the environment variable permanently using Command Prompt, or
    ``SET OE_LICENSE=C:\Users\USERNAME\oe_license.txt`` to set for the duration of the session using Command Prompt.
    ``$env:OE_LICENSE="C:\Users\USERNAME\oe_license.txt"`` to set the environment variable using PowerShell.

* In a file named ``oe_license.txt`` in the directory specified by the
  environment variable :envvar:`OE_DIR`.

* In a file named ``oe_license.txt`` in the user's platform-specific local
  OpenEye application data directory. The location of this directory is
  detailed below:

  * Linux/UNIX:

    ``~USERNAME/.OpenEye``

  * MacOS:

    ``/Users/USERNAME/Library/OpenEye`` or ``~USERNAME``

  * Microsoft Windows (User may need to create this directory the first time):

    ``C:\Users\USERNAME\AppData\Local\OpenEye``

* In a file named ``oe_license.txt`` in the current working directory



.. _examples_data_loc:

*************************************************************************
Example and Tutorial Data
*************************************************************************

Data files used in all the examples and tutorials in this documentation
are optionally provided as part of the Applications package installation.

Linux
------

Data files are located in the directory ``OPENEYE_DIR/data/APPLICATION/VERSION_NUM``
where ``OPENEYE_DIR`` refers to the top level OpenEye installation directory,
``APPLICATION`` refers to the application suite to which the program belongs and ``VERSION_NUM`` refers to the application suite version number.

Windows
--------

The Data folder under the versioned ``OpenEye-applications`` directory in ``C:\Program Files\``,
is the default location for data directory on Windows installation.  It contains sub-folders for each application suite.

macOS
---------

The versioned OpeneEye-applications data folder is easily accessible in the macOS distribution as a standalone folder and can be optionally installed by the user to any location.  It contains sub-directories for each application suite.


.. _installation_information:

*************************************************************************
Installation
*************************************************************************

Installers and Licenses
------------------------

Installers for our supported platforms can be found at the `Product Downloads page <https://www.eyesopen.com/customer-software-download>`_.

..  admonition:: VIDA Installer

    Note that there is a separate VIDA installer for your platform. To add VIDA
    to the applications on your machine, use the VIDA
    installer with a procedure similar to the procedure
    used to install
    the other applications.

The installers check for the presence of an OpenEye license on the target computer, so
:ref:`be sure you have the license in the right place <oe_license>`.

The following sections give more specific directions for your operating system.

The procedures documented in this chapter explain how to install the product code on your computer
and how to set up the computer (for example, the path) to execute product commands.  After following
the installation instructions, see the chapters
on the individual applications, for documentation of application commands and how to run them.
:ref:`For example, see the OMEGA introduction for information about OMEGA commands and arguments <omega_introduction>`.

Linux
------

.. note::

  Linux installation also requires libpciaccess to be available in order to open the desktop applications.

Linux distributions are provided as a gzipped tarball of the distribution
tree described below. Installation is performed by simply untarring the file
in the desired location. The top-level directory in the tarball is named
``openeye``. Distributions for different Linux variants can be installed
into the same location, allowing multiple Linux versions to be run from a
single shared directory.

..  admonition:: Add bin Directory to Path

    To ensure that the installed applications can be called from the command line,
    be sure to add the full path of the ``openeye/bin`` subdirectory to the
    :envvar:`PATH` environment variable. For instance, if the distribution was
    installed into ``/usr/local/openeye``, the :envvar:`PATH` environment variable
    should contain: ``/usr/local/openeye/bin``.

    If you are not used to manipulating the path, this is the time to learn. See the
    documentation available and online tips for your version of Linux.  The usual
    way to add ``/usr/local/openeye/bin``, for the current terminal session, would be::

        export PATH="/usr/local/openeye/bin:$PATH"

Under the top-level ``openeye`` directory are the following subdirectories:

:arch: This directory contains the collection of platform specific subdirectories. Each subdirectory contains the actual installed executables and support libraries for the associated platform. In the platform specific subdirectory there will be a subdirectory for each application. Within that will be another subdirectory for each version of that application.
:bin: This directory contains a startup script for each application that has been installed. This script determines, at run-time, what the current platform is and then calls the appropriate executable in the ``arch``. This script enables the easy co-existence of multiple platforms and versions of any OpenEye application in the same distribution tree.
:data: This directory contains all of the associated data and examples for the installed applications. There will be a subdirectory for each installed application and within that subdirectory there will be another subdirectory for each specific version of that application.

The startup script discussed in the section on the ``bin`` directory above will
have the same name as the installed executable with which it is associated.
When the script is called, it will attempt to determine the current platform
and run the appropriate executable if installed. If an appropriate executable
cannot be found, the script will report that information, as well as a list of
the currently installed platforms. The auto-detection can be overridden by
setting one of two environment variables:

* :envvar:`OE_ARCH` can be used to specify a colon separated list of compatible
  distributions for the current platform such as:

  ``redhat-RHEL8-x64:redhat-RHEL7-x64``

  or ``Ubuntu-18.04-x64:Ubuntu-16.04-x64``

  Specification of this environment variable overrides the auto-detection
  process, if it is present. If none of the compatible distributions listed are
  found, the script will fall back to the auto-detection process.

* :envvar:`APPNAME_OE_ARCH` can be used to specify a colon separated list of
  compatible distributions for a specific application (as specified by
  changing the **APPNAME** text in the environment variable name) just
  like :envvar:`OE_ARCH` as detailed above.

  Specification of this environment variable overrides the :envvar:`OE_ARCH`
  environment variable as well as the auto-detection process. If none of
  the compatible distributions listed are found, the script will fall back to
  the :envvar:`OE_ARCH` list first and then to the auto-detection process.

  Specifying this variable provides a simple way to customize the behavior for
  individual applications on nonstandard platforms.

The startup script also supports a few commandline arguments including:

-path
  Specifying this argument will output the full path of the executable to be
  run. The executable will not be started if this argument is present.

-print_arch
  Specifying this argument will output the details of the current platform as
  detected by the script as well as which platform-version of the executable is
  being run. The executable will be started if this argument is present.

-use_version
  Specifying this argument followed by a specific version number allows the
  user to control which released version of the executable to run.

Windows
--------

Windows distributions are provided as a standard MSI installer. Double click the installer and follow the instructions.  For the OpenEye installation a data directory which contains example data for all of the application suites is installed by default.  De-select it in the installer if you do not wish to install the data.
The OpenEye-applications folder will install into  ``C:\Program Files`` by default but can be overridden.

If Microsoft MPI is not installed on the system you must install this separately in order for the applications to run using multiple processes.  
See section :ref:`MPI<mpi_information>`  for more information.

Under the OpenEye-applications directory (``C:\Program Files\OpenEye-applications <version>``) there are subdirectories for:

:bin: This directory contains the application executables.
:data: This directory contains all of the associated data and examples for the installed applications.

An OpenEye-applications group will be added to the
*Start* menu. It will contain a link to an OpenEye command shell
with :envvar:`PATH` settings already defined to allow the user
to simply type the executable name at the prompt without concern for where the
executable is actually installed.  A shortcut to the OpenEye command shell will also be placed onto the Desktop.  Links to graphical apps and an OpenEye-applications Data folder
will also be installed to the *Start* menu and Desktop.

.. note::

    The Windows installer will automatically remove the last version of **OpenEye-applications** from the computer, if it exists, before installing the latest version of the software.  To install older released versions of  **OpenEye-applications**, you must first uninstall the latest version using ``system settings\add or remove programs``.

Enterprise Installation for Windows
-----------------------------------

It is possible to perform a "silent installation" of the applications by running the
installer with the ``/quiet`` flag from an administrator account.
It is also possible to run as a non-administrator, and to install to an alternate location from the default folder.

Example commands:

``msiexec.exe /quiet /i OpenEye-applications-2019.May.1-win64-setup.msi``   When run from an administrator account this installs without displaying any progress or other istallation windows.

``msiexec.exe /quiet /i OpenEye-applications-2019.May.1-win64-setup.msi ALLUSERS=2 MSIINSTALLPERUSER=1 INSTALL_ROOT=c:\mydir``.  Installs to ``c:\mydir`` instead of the default location and can be run from a non-administrator account.

No reboot is required after installation.

macOS
---------

macOS distributions are provided as *dmg* disk images. For installation,
double click the .dmg file in the Finder to open it.   The installer will show icons
for the applications and data, as shown in the figure below.

Drag each application to the
Applications folder. For convenience, multiple items to install can be selected
at once by drawing a box around them or by using ``command-click`` on each item.

.. only:: oehtml

   .. figure:: /_images/mac_installation.png
      :scale: 70%
      :align: center
      :alt: Task Screen

      macOS disk image

A folder named ``OpenEye-applications<version#> Data``, containing all the associated data for the applications, is included in the
disk image.  It can be dragged to the Applications folder or other convenient location for installation.

Once the applications have been installed to the Applications folder, the application ``Install Command Line Support`` can be
saved to any location and run.  This application adds the
command-line applications' locations to the user's :envvar:`PATH` environment variable so they can be run from any command line.

Command-line applications can also be run from the Applications folder, in
which case they will open a terminal window with a properly configured
environment.  The user may need to source their ``~/.profile`` file after executing "Install Command Line Support" to update the :envvar:`PATH` in existing terminals.

GPU-Enabled Applications
--------------------------------------------------------------------------------


GPU-Related Requirements
========================

The following features are required in order to use GPU-accelerated OpenEye toolkits and applications.


Supported Platforms
-------------------

CUDA-enabled OpenEye software is only available on supported Linux platforms.
For supported Linux platforms see the `Platform Support Page <https://www.eyesopen.com/supported-platforms>`_.


Supported GPUs
-------------------

An NVIDIA `Tesla <http://www.nvidia.com/object/tesla-supercomputing-solutions.html>`_,
`Quadro <http://www.nvidia.com/object/workstation-solutions.html>`_, or
`GeForce <http://www.nvidia.com/object/geforce_family.html>`_ GPU with a **compute capability of 3.5
or higher** is required on your system. For a comprehensive table of compute capability
categories for each GPU, please refer to the `CUDA <https://en.wikipedia.org/wiki/CUDA>`_ Wikipedia page.


NVIDIA Drivers
-------------------

* **Minimum NVIDIA Driver version: 450.x**.

* CUDA is **not** required to be installed.

We recommend driver `450.80.02 <https://www.nvidia.com/Download/driverResults.aspx/165294/en-us>`_, and
we strongly advise manually downloading and installing the appropriate NVIDIA driver
for your system as opposed to using a package manager.

To install, root privilege is required. Follow these steps:

  #. Download the driver to the machine you are installing it on.
  #. ``chmod +x`` the driver package to make it executable.
  #. Ensure you have disabled X-server by killing any running sessions.
     Reboot may be required if X-server is still running after this step.
     
     .. warning::

        Disabling X-server requires different processes to be killed depending on your Linux
        distribution.
        See the `NVIDIA installation guide
        <http://docs.nvidia.com/cuda/cuda-installation-guide-linux/#runfile>`_ for more details.

     .. warning::

        The NVIDIA kernel module can often conflict with the open source
        Nouveau display drivers, depending on your specific Linux
        distribution. The NVIDIA documentation is a much more complete
        and up-to-date source for information on how to work around this issue.
        See `Disabling Nouveau
        <http://docs.nvidia.com/cuda/cuda-installation-guide-linux/#runfile-nouveau>`_ on the NVIDIA website.

  #. Install the driver by ``sudo ./NVIDIA-Linux-x86_64-450.80.02.run`` and follow the step-by-step installation instructions.

  For more details on driver installations, see the `CUDA Installation Guide
  <https://docs.nvidia.com/cuda/cuda-installation-guide-linux/#runfile>`_

.. note::

  The output of the ``nvidia-smi`` command is extremely useful when
  debugging GPU issues. Please include the output from
  ``nvidia-smi`` in any request to support@eyesopen.com.


Performance Tuning
-------------------

To get the most performance out of an NVIDIA graphics card, use the persistence daemon to switch persistence mode
across all cards on the system (root privilege required)::

  sudo nvidia-persistenced --user foo

This will automatically enable persistence mode after reboot.

For full instructions on the persistence daemon, see the `Persistence daemon section
<https://docs.nvidia.com/deploy/driver-persistence/index.html#persistence-daemon>`_ of the NVIDIA docs.


.. _mpi_information:

*************************************************************************
MPI
*************************************************************************

Windows MPI
-----------
On Windows, **OpenEye applications** use the Microsoft implementation of MPI (MS-MPI).  
If it is not installed, you may see an error message::

  The code execution cannot proceed because msmpi.dll was not found. Reinstalling the program may fix this problem.

To fix this issue, MS-MPI can be installed from the setup file
provided in the bundle at
``C:\Program Files\OpenEye-applications<version>\mpi\MSMpiSetup.exe``.

MPI on Windows requires a valid network connection. If no connection exists MPI will
not run. A network connection can be created by installing a Microsoft loopback adapter.
Please contact support@eyesopen.com for more details.

.. note:: Multi-node MPI is not currently available in Windows as it is not supported in MS-MPI

MS-MPI License
----------------

::

  MIT License

  Copyright (c) Microsoft Corporation. All rights reserved.

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

Open MPI
-------------

On Linux and MacOS, **OpenEye applications** use the Open MPI implementation of MPI,
found at `Open MPI: Open Source High Performance Computing <http://www.open-mpi.org/>`_.  The applications package
includes a full Open MPI install,
so no additional software is needed.

There are two requirements to run under Open MPI.

  * Every machine in the cluster must have the same version of the application installed.

  * The path to the application's ``bin`` directory must be
    in the :envvar:`PATH` environment variable on all machines,
    and be positioned before any other locations that may contain MPI executables
    (orted, mpirun, etc.).

Using Open MPI
--------------

To run under Open MPI on a single machine:

.. code-block:: console

   > [application executable] -mpi_np [number of processes] [other application options]

To run Open MPI on multiple machines, begin by generating a text file that will include the MPI hosts you plan to use and the number of processes on each (for this example, we'll call this file ``hosts``).  The file should contain a line for each machine with the name of the machine, a space, then ``slots=N``, where N is the number of processors for your run.  For this example, the file looks like this:

.. code-block:: bash

  c1 slots=4
  c2 slots=4
  c3 slots=4
  c4 slots=4
  c5 slots=4

The following command-line will then start a job with one master and 19 slaves.

.. code-block:: console

   > [application executable] -mpi_hostfile hosts [other application options]

The master will be on c1, where the job is being started.  All the input/output for the run is controlled from the master machine, and all results and logging information are combined.

Open MPI License
----------------

::

  Most files in this release are marked with the copyrights of the
  organizations who have edited them.  The copyrights below are in no
  particular order and generally reflect members of the Open MPI core
  team who have contributed code to this release.  The copyrights for
  code used under license from other parties are included in the
  corresponding files.

  Copyright (c) 2004-2010 The Trustees of Indiana University and Indiana
                          University Research and Technology
                          Corporation.  All rights reserved.
  Copyright (c) 2004-2017 The University of Tennessee and The University
                          of Tennessee Research Foundation.  All rights
                          reserved.
  Copyright (c) 2004-2010 High Performance Computing Center Stuttgart,
                          University of Stuttgart.  All rights reserved.
  Copyright (c) 2004-2008 The Regents of the University of California.
                          All rights reserved.
  Copyright (c) 2006-2017 Los Alamos National Security, LLC.  All rights
                          reserved.
  Copyright (c) 2006-2017 Cisco Systems, Inc.  All rights reserved.
  Copyright (c) 2006-2010 Voltaire, Inc. All rights reserved.
  Copyright (c) 2006-2017 Sandia National Laboratories. All rights reserved.
  Copyright (c) 2006-2010 Sun Microsystems, Inc.  All rights reserved.
                          Use is subject to license terms.
  Copyright (c) 2006-2017 The University of Houston. All rights reserved.
  Copyright (c) 2006-2009 Myricom, Inc.  All rights reserved.
  Copyright (c) 2007-2017 UT-Battelle, LLC. All rights reserved.
  Copyright (c) 2007-2017 IBM Corporation.  All rights reserved.
  Copyright (c) 1998-2005 Forschungszentrum Juelich, Juelich Supercomputing
                          Centre, Federal Republic of Germany
  Copyright (c) 2005-2008 ZIH, TU Dresden, Federal Republic of Germany
  Copyright (c) 2007      Evergrid, Inc. All rights reserved.
  Copyright (c) 2008      Chelsio, Inc.  All rights reserved.
  Copyright (c) 2008-2009 Institut National de Recherche en
                          Informatique.  All rights reserved.
  Copyright (c) 2007      Lawrence Livermore National Security, LLC.
                          All rights reserved.
  Copyright (c) 2007-2017 Mellanox Technologies.  All rights reserved.
  Copyright (c) 2006-2010 QLogic Corporation.  All rights reserved.
  Copyright (c) 2008-2017 Oak Ridge National Labs.  All rights reserved.
  Copyright (c) 2006-2012 Oracle and/or its affiliates.  All rights reserved.
  Copyright (c) 2009-2015 Bull SAS.  All rights reserved.
  Copyright (c) 2010      ARM ltd.  All rights reserved.
  Copyright (c) 2016      ARM, Inc.  All rights reserved.
  Copyright (c) 2010-2011 Alex Brick .  All rights reserved.
  Copyright (c) 2012      The University of Wisconsin-La Crosse. All rights
                          reserved.
  Copyright (c) 2013-2016 Intel, Inc. All rights reserved.
  Copyright (c) 2011-2017 NVIDIA Corporation.  All rights reserved.
  Copyright (c) 2016      Broadcom Limited.  All rights reserved.
  Copyright (c) 2011-2017 Fujitsu Limited.  All rights reserved.
  Copyright (c) 2014-2015 Hewlett-Packard Development Company, LP.  All
                          rights reserved.
  Copyright (c) 2013-2017 Research Organization for Information Science (RIST).
                          All rights reserved.
  Copyright (c) 2017-2018 Amazon.com, Inc. or its affiliates.  All Rights
                          reserved.
  Copyright (c) 2018      DataDirect Networks. All rights reserved.
  Copyright (c) 2018-2019 Triad National Security, LLC. All rights reserved.

  $COPYRIGHT$

  Additional copyrights may follow

  $HEADER$

  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are
  met:

  - Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

  - Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer listed
    in this license in the documentation and/or other materials
    provided with the distribution.

  - Neither the name of the copyright holders nor the names of its
    contributors may be used to endorse or promote products derived from
    this software without specific prior written permission.

  The copyright holders provide no reassurances that the source code
  provided does not infringe any patent, copyright, or any other
  intellectual property rights of third parties.  The copyright holders
  disclaim any liability to any recipient for claims brought against
  recipient by any third party for infringement of that parties
  intellectual property rights.

  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.



*************************************************************************
Uninstallation
*************************************************************************

Linux
----------

To uninstall a single distribution of a product the relevant subdirectories for that
product and version simply need to be deleted from within the following directories:

:arch: In the ``openeye/arch`` directory is a platform specific subdirectory.  Within this are directories for each installed product and within those are subdirectories for each version of the product.  Delete the subdirectory for the version which is to be uninstalled.  For example, to delete or uninstall v1.0.0 of a product, delete the folder "<product_name>/1.0.0".
:data: In the ``openeye/data`` directory is a subdirectory for each installed product and within those are subdirectories for each version of the product.  Delete the subdirectory for the version which is to be uninstalled.

Windows
--------

**OpenEye applications** can be uninstalled through the Windows Control Panel.
Open the Control Panel and select **Programs and features**, then select the application and click **Uninstall**.

For graphical applications, uninstallation also removes the application's link
from the desktop and *Start* menu.

Uninstallation of the **OpenEye applications** does not automatically uninstallation the
MS-MPI, installated with the applications.  To uninstall MS-MPI, you must follow the procedure
through Windows Control Panel separately for MS-MPI.

macOS
---------

To uninstall a single distribution of an application simply drag the
application from the Application folder to the Trash.

Some applications may, at the user's request, install symbolic links in the
/usr/local/bin directory, and modify the PATH variable in the
.openeyerc.* file(s) in the user's home directory.  The symbolic links may be
safely deleted after uninstallation, and the .openeyerc.* file(s) can be
edited, if desired, to remove obsolete entries.


*************************************************************************
Release Cycle
*************************************************************************

**OpenEye Applications** are released two times per year in Summer
and Winter in conjunction with the corresponding toolkit releases.
Intermediate bug fix releases are done to fix critical
issues if necessary.

Packages are versioned as ``<year>.<release#>.<build#>``.
For example, ``2026.1.0`` represents the first  build of the first released
version in 2026.

.. figure:: /_images/ReleaseCycleImage.png
   :align:  center
   :width:  250pt

   **OpenEye release cycle**


########################
Legal Notices
########################

..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt




.. AFITT documentation master file

.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



#################################
AFITT |afitt_version|
#################################

.. toctree::
   :maxdepth: 3

   introduction
   flynn/flynn
   coot/coot
   utilities
   theory/flynn_theory
   releasenotes/index
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt





.. _afitt_introduction:

Overview
==============

**AFITT** is a crystallographic tool for correctly placing small molecules in real-space density.
**AFITT** combines our flagship Shape technology with generic forcefields into a new forcefield
that fits small molecules into crystallographic density while maintaining excellent chemistry.

**AFITT** also provides an interface to external refinement programs and tools to validate the
refinement including interactive Ramachandran plots and real-space correlation coefficient
calculation (RSCC).

Applications
==============

The **AFITT** distribution contains a single application:

  * :ref:`FLYNN <chapter_flynn>` for fitting ligands into real-space density.

Utility Programs
==================

The following utility programs are also included in this distribution:

* :ref:`AlignGrid <chapter_aligngrid>`: Utility to align proteins with electron-density maps on a single reference

* :ref:`RotFit <chapter_rotfit>`: Utility to carry out fast automated refitting of side-chains and peptide flips.

* :ref:`Rscc <chapter_rscc>`: Utility to perform real-space correlation coefficient and real-space R-factor calculations.

* :ref:`WriteDict <chapter_writedict>`: Refinement dictionary generator that properly handles covalent bond restraints between
  the ligand and the protein




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: aligngrid

.. _chapter_aligngrid:

***************
AlignGrid
***************

====================
Overview
====================

The **AlignGrid** utility aligns proteins with electron-density maps on a single reference.

=================
Example Commands
=================

.. code-block:: console

   > aligngrid -grid input.ccp4 -query protein1.pdb \
               -target protein2.pdb -out output.ccp4

Take the input grid in ccp4 format and protein.  Align protein1 to
protein2 and rotate and translate the input grid using the same
alignment outputting the result to *output.ccp4*.

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing **AlignGrid**
with the `--help` option.

.. code-block:: console

   > aligngrid --help

will generate the following output:

::

  Help functions:
    aligngrid --help simple      : Get a list of simple parameters
    aligngrid --help all         : Get a complete list of parameters
    aligngrid --help <parameter> : Get detailed help on a parameter
    aligngrid --help html        : Create an html help file for this program

====================
Required Parameters
====================

.. option:: -grid

   Input density grid.  This is the grid that is to
   be rotated and translated into the new reference frame.

   [Aliases=**-density**]

.. option:: -out

   The output grid in any writable format.  These
   include **.ccp4**, **.map** and **.grd**

.. option:: -protein

   The query protein that corresponds to the input grid.

   [Aliases=**-query**]

.. option:: -target

   The target protein that the grid and query
   protein will be aligned toward.

====================
Optional Parameters
====================

.. option:: -outprot

   An optional file to output the query protein
   after it is translated and rotated into the new reference frame.

.. option:: -padding

   When writing out a **.grd** file, this
   indicates the added extents (in |Angstroms| around the protein when outputting the density.
   [Default=4.0]

   [Aliases=**-pad**]

.. option:: -scale

   The final map spacing in |Angstroms|.  [Default=1.0]

.. option:: -verbose

   Triggers copious logging output. [Default=false]

The allowed MTZ map types and the corresponding column conventions are
documented in :ref:`OESystem_OEReadMTZ` in the **OEChem TK** manual.

.. option:: -autoMTZ

   Automatically try to open the mtz file using the DELWT and
   FDELWT columns from REFMAC5 mtz files.

   See :ref:`OESystem::OEMTZMapType::Fdelwt <OESystem_OEMTZMapType_Fdelwt>` for the corresponding
   difference-map type in **OEChem TK**.

   [Default=true]

.. option:: -Fc <columnname>

   Column to use for Fc.  *Note, to load arbitrary columns, you can use the **-Fc**
   and **-Phic** columns and the **Fc** maptype.*

   [Default=FC]

.. option:: -Fdelwt <columnname>

   Column to use for Fdelwt or difference map amplitudes

   See :ref:`OESystem::OEMTZMapType::Fdelwt <OESystem_OEMTZMapType_Fdelwt>` in **OEChem TK** for map
   type details.

   [Default=DELFWT]

.. option:: -Fobs <columnname>

   Column to use for FObs.

   [Default=F]

   [Aliases=**-Fo**]

.. option:: -Phi <columnname>

   Column to use for Phi.

   [Default=PHI]

.. option:: -Fwt <columnname>

   Column to use for Fwt or regular map amplitudes.

   See :ref:`OESystem::OEMTZMapType::Fwt <OESystem_OEMTZMapType_Fwt>` in **OEChem TK** for map
   type details.

   [Default=FWT]

.. option:: -Phic <columnname>

   Column to use for Phic.

   [Default=PHIC]

.. option:: -Phidelwt <columnname>

   Column to use for Phdelwt or difference map phases.

   [Default=PHDELWT]

.. option:: -Phiwt <columnname>

   Column to use for Phwt or regular map phases.

   [Default=PHWT]

.. option:: -mtype

   The map type to use for fitting. Fo-Fc, Fc, 2Fo-Fc, 3Fo-Fc, Fwt,
               Fdelwt...

   See :ref:`OESystem_OEReadMTZ` for the full list of map types and
   their MTZ-column interpretation.

   [Default=Fdelwt]



.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _afitt_citation:

*********************************
Citation
*********************************

.. note:: To cite AFITT or FLYNN please use the following:

    AFITT |afitt_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com/.

Wlodek, S., Skillman A.G., Nicholls A., **Automated ligand placement and refinement with a combined force field and
shape potential**, Acta Cryst., Vol. D62, pp. 741-749, 2006



.. _chapter_coot:

Coot Integration
================

.. toctree::
   :maxdepth: 2

   coot_overview
   coot_flynn
   coot_writedict
   coot_rotfit
   coot_installation


.. |product|        replace:: AFITT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _coot_overview:

.. program:: coot 

*********************
Overview
*********************

Due to its command line nature, AFITT-CL tools (such as FLYNN) can be integrated with other
crystallographic applications such as Coot (and WinCoot).  OpenEye supplies a simple
script that allows users of Coot to use FLYNN directly from the Coot GUI.

This script adds "Fit Ligand..." option, a "Make cif..." and a "Fit sidechains..."
options to the extensions menu.

.. _figure_cootintegration:

.. figure:: /_images/cootui001.png
   :align: center

   **Coot Integration**

.. note:

  In COOT 0.8+ installing flynn will cause it to appear in the Extensions/Modules
  menu.

.. figure:: /_images/cootui001-08.png
   :align: center

   **COOT 0.8 Integration**


.. |product|        replace:: AFITT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _coot_flynn:

.. program:: coot 

*********************
Using FLYNN
*********************

Activating the "Fit Ligand..." menu option from the Extensions menu opens up the FLYNN dialog:

.. _figure_flynndialog:

.. figure:: /_images/cootui002.png
   :align: center

   **FLYNN Dialog to fit a ligand**

To use the FLYNN dialog, select the Ligand to fit from the pull-down
menu.  Next select the Protein and then the desired map file.

If the map is a difference map, click on the "Difference Map" to
optimize the analysis. Then click on Fit.

The output of FLYNN will appear in the console window used to start
coot.  When FLYNN is complete, coot will automatically load the
resulting ligands.

FLYNN Advanced Options
======================

FLYNN's coot interface includes access to
some of the advanced options contained in the application.

.. option:: -Box

   Unlike the AFITT GUI interface, coot does not have a method to
   select density blobs to be used for fitting.  If the density is poor,
   flynn can use the input ligand as a bounding box to fit to the
   surrounding density.

.. option:: -Check

   Running check runs flynn without performing any fitting operation.
   When the check is completed, an html report is generated and opened in
   a webbrowser (if available).  Since coot only display's single bonds,
   the report includes a depiction of the ligand being fit in order to
   verify that the ligand being analyzed is actually correct.

   The report also indicates any problems or issues with the ligand or
   the map being fit against.

.. option:: -MMFF94s

   This option uses the MMFF94s variant of the MMFF94 forcefield to
   enforce planar aniline configurations.  See the FLYNN :ref:`flynnadvanced` command line
   flags for more details


.. |product|        replace:: AFITT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _coot_writedict:

.. program:: coot 

*********************
Using WriteDict
*********************

Activating the "Make Dictionary..." menu option opens up the
WriteDict dialog:

.. _figure_flynndialog2:

.. figure:: /_images/writedict.png
   :align: center

   **Writedict Dialog**

To use the WriteDict dialog, simply select the protein or
ligand from the pull-down menu and click "ok".  *Coot* will
automatically open up the resulting dictionary and pdb files generated
by WriteDict.

Note that new ".pdb" files are generated when using writedict, this
is because hydrogen
may have been relabeled and covalent *LINK* records may have
been inserted into the *pdb* file.

WriteDict Advanced Options
^^^^^^^^^^^^^^^^^^^^^^^^^^

FLYNN's coot interface includes access to
some of the advanced options contained in the application.

planarAniline option
^^^^^^^^^^^^^^^^^^^^

Similar to FLYNN's *MMFF94s* option, this enforces planar
aniline nitrogen configurations.  Note that since this is an
approximation of the *MMFF94s* forcefield using planar
constraints, it is not called *MMFF94s*.  See the
:ref:`WriteDict command line flags <chapter_writedict>` for more details.



.. |product|        replace:: AFITT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _coot_rotfit:

.. program:: coot 

*********************
Using RotFit
*********************

Activating the "Fit Sidechains..." menu option opens up the ROTFIT
dialog:

.. figure:: /_images/rotfit.png
   :align: center

   **Writedict Dialog**

To use the ROTFIT dialog, a protein and mtz map must be loaded into coot.
The ROTFIT interface deduces the appropriate regular and difference map
to use and currently cannot handle non standard or unique column names.

ROTFIT options
==============

ROTFIT is a program that fits protein side-chains into the surrounding
density.  It utilizes both regular and difference density to place
side-chains appropriately searching both rotamers and peptide
flips in addition to an optional full MMFF94-driven optimization
into density.

Fixup Rotamer
^^^^^^^^^^^^^

Rotamer fixups selects from the probable rotamer sets to find the 
rotamer that best matches the surrounding density.

Fixup Pep-flip
^^^^^^^^^^^^^^

Peptide flips are enumerated and the one that best matches
the surrounding density is selected.

Fixup MMFF/Shape
^^^^^^^^^^^^^^^^

Full MMFF/Shape minimization is performed on compatible
residues attempting to fit the residue into the locally
surrounding density.


.. |product|        replace:: AFITT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _coot_install:

.. program:: coot 

***************************
Installing Coot Interface
***************************

====
Coot
====

The coot script file "flynn.scm" is included in your FLYNN
distribution in the "etc" directory.  The following steps are
required to integrate FLYNN with coot.

The current default version of COOT is 0.9.5, to install another
version please look for the files with the appropriate extension.

1. Install coot (at least version 0.3.3)

2. Install flynn and writedict somewhere in your path.  
   If you can't run FLYNN from the command line, neither can Coot.

3. Place *flynn.scm* to the coot extensions directory.  This is
   the directory where the files *extensions.scm* and *coot.scm*
   are located.

   This directory may be one of the following:

    /usr/local/coot/scheme
    /usr/local/xtal/coot64/share/coot/scheme/
    /my_coot_installation/share/coot/scheme/
    /ccp4-7.0/share/coot/scheme/ for the cpp4 installation

   on OSX the install for Coot 0.7/0.8 is most likely
     /Library/Coot/share/coot/scheme/

   Typing **which coot** may help locate these directories.

4. Copy *flynn.scm* to the extension list in *coot.scm* which is
   in the same directory as *extensions.scm*.  Please use the
   appropriate file for your version of coot.

   To accomplish this, change the following code in *coot.scm* for coot 0.7

   .. code-block:: scheme

     (define load-all-scheme
       (lambda (use-gui?)
         (let ((pre-list (list "filter.scm" 
			  "coot-utils.scm"))
              (post-list (list "coot-lsq.scm"
                               "shelx.scm"

   to look like this:

   .. code-block:: scheme

     (define load-all-scheme
       (lambda (use-gui?)
         (let ((pre-list (list "filter.scm" 
                "coot-utils.scm"))
                (post-list (list "coot-lsq."
                                 "shelx.scm"
                                 "flynn.scm"

5. Finally, make the following changes to *extensions.scm*

   For coot 0.3.3 to 0.5 near the top of the file, change:

   .. code-block:: scheme

     (if (defined? 'coot-main-menubar)
        (let ((menu (coot-menubar-menu "Extensions")))

   to become:

   .. code-block:: scheme

    (if (defined? 'coot-main-menubar)
       (let ((menu (coot-menubar-menu "Extensions")))
         (add-simple-coot-menu-menuitem menu "Flynn..."           
           (lambda () (do-flynn-gui)))
         (add-simple-coot-menu-menuitem menu "Make Dictionary..." 
           (lambda () (do-flynn-gendict-gui)))
        (add-simple-coot-menu-menuitem menu "Fit Sidechains..." 
           (lambda () (do-flynn-fitsidechains-gui)))

   For coot 0.6.x, near the top of the file, change:

   .. code-block:: scheme

     (if (defined? 'coot-main-menubar)
         ;; ---------------------------------------------
         ;;           extensions
         ;; ---------------------------------------------
         ;; 
        (let ((menu (coot-menubar-menu "Extensions")))

   to become:

   .. code-block:: scheme

    (if (defined? 'coot-main-menubar)
         ;; ---------------------------------------------
         ;;           extensions
         ;; ---------------------------------------------
         ;; 
      (let ((menu (coot-menubar-menu "Extensions")))
         (add-simple-coot-menu-menuitem menu "Flynn..."           
           (lambda () (do-flynn-gui)))
         (add-simple-coot-menu-menuitem menu "Make Dictionary..." 
           (lambda () (do-flynn-gendict-gui)))
        (add-simple-coot-menu-menuitem menu "Fit Sidechains..." 
           (lambda () (do-flynn-fitsidechains-gui)))

   For coot 0.8 you should make the change to the "Modules"
   section as shown below:

   .. code-block:: scheme

	;; ---------------------------------------------------------------------
	;;     Modules
	;; ---------------------------------------------------------------------

        (add-simple-coot-menu-menuitem
         submenu-modules "Fit Ligand..."
         (lambda ()
           (do-flynn-gui)))

        (add-simple-coot-menu-menuitem
         submenu-modules "Make cif..."
         (lambda ()
           (do-flynn-gendict-gui)))

        (add-simple-coot-menu-menuitem
         submenu-modules "Fit sidechains..."
         (lambda ()
           (do-flynn-fitsidechains-gui)))

================
WinCoot 0.9.4.1+
================

WinCoot does not support writing extensions in GUILE.  Extensions may
be written in PYTHON, however.

The WinCoot scheme script file *flynn.py* is included in your FLYNN
distribution in the *Data/wincoot* directory.  The
following steps are required to integrate FLYNN with *WinCoot*.

1. Install *WinCoot* (at least version 0.9.4.1)

2. Install flynn and writedict somewhere in your path.  If you can't run FLYNN
   from the command line, neither can *WinCoot*.

3. Place this file *flynn.py* in the coot extensions directory where
   *extensions.py* is located.

   Typically, this directory is C:\\WinCoot\\lib\\python-2.7\\site-packages\\coot.

4. Add *flynn.py* to the extension list in *coot_load_modules.py*.
   (same directory as above) *before* *extensions.py*

   For example:

   .. code-block:: python

      ...
      "get_recent_pdbe.py",
      "flynn.py",
      "extensions.py",
      ...

5.	Modify the file named enhanced_ligand.py 

   To add Flynn and MakeDict, find the last menu item in enhanced_ligand.py and add the following menu items below it:

   .. code-block:: python

      add_simple_coot_menu_menuitem(menu, "Use Flynn to Fit Ligand...", lambda func: do_flynn_gui())
      add_simple_coot_menu_menuitem(menu, "Use WriteDict to generate CIF...", lambda func: do_writedict_gui())

   For example, if "Display Ligand Distortions" is the last menu time, it would look like this:

   .. code-block:: python

      add_simple_coot_menu_menuitem(menu, "Display Ligand Distortions", lambda func: display_ligand_distortions_func())
      add_simple_coot_menu_menuitem(menu, "Use Flynn to Fit Ligand...", lambda func: do_flynn_gui())
      add_simple_coot_menu_menuitem(menu, "Use WriteDict to generate CIF...", lambda func: do_writedict_gui())

   This results in the Ligand menu being updated to include Flynn's functionality

========================
WinCoot 0.3.3 to 0.8.9.2
========================

WinCoot does not support writing extensions in GUILE.  Extensions may
be written in PYTHON, however.

The WinCoot scheme script file *flynn.py* is included in your FLYNN
distribution in the *utilities/flynn/wincoot* directory.  The
following steps are required to integrate FLYNN with *WinCoot*.

1. Install *WinCoot* (at least version 0.3.3)

2. Install flynn and writedict somewhere in your path.  If you can't run FLYNN
   from the command line, neither can *WinCoot*.

3. Place this file *flynn.py* in the coot extensions directory where
   *extensions.py* is located.

   Typically, this directory is *C:\WinCoot\share\coot\scheme*.

4. Add *flynn.py* to the extension list in *coot\_load\_modules+gui.py*.
   (same directory as extensions.py) *before* *extensions.py*

   For example:

   .. code-block:: python

      "coot-gui.py",
      "flynn.py",
      "extensions.py",

5. Add the following lines to the file named extensions.scm (this
   will be in your coot distribution) 
  
   The easiest place to put this right after the line

   .. code-block:: python

       menu = coot_menubar_menu("Extensions")

   here are the lines to add:

   .. code-block:: python

       add_simple_coot_menu_menuitem(menu, "Fit Ligand...", do_flynn_gui)
       add_simple_coot_menu_menuitem(menu, "Make CIF...", do_writedict_gui)
       add_simple_coot_menu_menuitem(menu, "Fit Sidechains...", 
         do_fitsidechains_gui)


.. _chapter_flynn:

FLYNN
=====

.. toctree::
   :maxdepth: 2

   flynn_overview
   flynn_example
   flynn_help
   flynn_req_params
   flynn_opt_params
   flynn_usage


.. _flynn_overview:

.. program:: flynn 

======================
Overview
======================

Fitting small molecules to electron density is a challenging problem.
Small molecules with few rotatable bonds are amenable to hand
placement in density.  Add a few rotatable bonds, however, and
the problem becomes factorially more complicated.  Furthermore,
unlike protein modeling, many small molecules are relatively
unique entities whose conformation cannot be predicted from
previous homologies.

**FLYNN** uses a high-quality conformational
analysis and a fast rigid overlay to position ligands in density
in conjunction with a combined forcefield to further position
these conformations while, at the same time, minimizing ligand strain.
FLYNN can automatically locate ligand density and automatically fit fragment
cocktails, or, failing that, **FLYNN** can use a
supplied bounding box in which to place the ligands of interest.

Ligands are fit to density, however the placements are scored and ranked based
on the real space correlation coefficient (RSCC) and optionally protein based
docking scores: Piecewise-Linear-Potential (PLP) and Chemscore.

**FLYNN** reads common map formats such as CCP4, MRC, MAP, CNX/CNS (XPLOR) and MTZ as well as OpenEye's grid formats and a plethora of small molecule,
protein and connection table formats.


.. |product|        replace:: AFITT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _flynn_examples:

.. program:: flynn

======================
Example Commands
======================

The example commands in this section can be run with files found in
the :file:`data/1nhu` directory under the top-level
installation directory.

Basic Usage
^^^^^^^^^^^^

.. code-block:: console

   > flynn -in 1nhu.ism -map 1nhu_prot.mtz -prot 1nhu_prot.pdb \
              -out 1nhu-poses.pdb

Use the ligand specified by **1nhu.ism** and fit it against the
density in the mtz file **1nhu_prot.mtz**.  Since this is an mtz
file and **-autoMTZ** is defaulting to true, the Fdelwt map will
automatically be generated and used as the density target.  The
protein atoms specified in 1nhu_prot.pdb will be used to mask the
density before the map is searched for appropriately sized ligand
volumes.

Generating Reports
^^^^^^^^^^^^^^^^^^

.. code-block:: console

   > flynn -in 1nhu.ism -map 1nhu_prot.mtz -prot 1nhu_prot.pdb \
              -out 1nhu-poses.pdb -precheck -reporthtml 1nhu.html

Performs a preliminary check of the data, ensuring that the ligand can
be processed and that the mtz file can be opened.  An html file is
generated **1nhu.html** with a corresponding image file
**1nhu.html.gif**.  The html file can be opened with a web browser to
view the ligand being fit and any corresponding issues.

The output will be written to 1nhu-poses.pdb in pdb format.

Choosing box regions of density
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console

   > flynn -in 1nhu.ism -map 1nhu_sigma.mtz -prot 1nhu_prot.ent \
              -out 1nhu_poses.pdb -box 1nhu.pdb -boxpad 2.0

This is the same as above except that the density is pruned down to
the bounding box specified by **1nhu.pdb** padded by 2.0
|Angstroms|.  Furthermore, if a suitable blob is not found, then the
pruned density will be used as is.  This is quite effective for
regions of density with a high degrees of disorder.  It is also useful
to select this option when using the supplied interface to **coot**.

Choosing density close to residues
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use the *-residues* and *-distance* flags to indicate residues close
near the desired density.  Only blobs that are found within
*-distance* to the selected residues will be selected.  Residues are
specified by <residuenumber><chain> separated by commas.

.. code-block:: console

   > flynn -in 1nhu.ism -map 1nhu_prot.mtz -prot 1nhu_prot.pdb \
              -out 1nhu-poses.pdb -residues 528B,477B

Choosing MTZ columns
^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console

   > flynn -in 1nhu.ism -map 1nhu_sigma.mtz -prot 1nhu_prot.ent \
              -out 1nhu_poses.pdb -box 1nhu.pdb -boxpad 2.0 \
              -boxThenBlobs -autoMTZ false -Fobs Frefined1 -Fc FC \
              -Phic PHIC -mtype 2Fo-Fc -autoMTZ false

This example shows how to choose a nonstandard column from the MTZ
file.   the map is generated using
**Frefined1** as the observed amplitude column, **FC** as the
calculated amplitude column and **PHIC** as the calculated phase
column.   Furthermore, the regular  map **2Fo-Fc** is used.  Note that
**-autoMTZ** must be set to false for these settings to take effect.

Fragment usage
^^^^^^^^^^^^^^^

The **-fragment** flag may be included with any of the above commands.
There are three main differences when running in fragment mode:

  1. Multiple ligands are fit simultaneously.

  2. If the blobs detected for difference ligands overlap, the ligands
     are assigned to the same blob.  (This is for reporting purposes)

  3. Ligands are sorted according to the Real Space Correlated Coefficient.

.. code-block:: console

   > flynn -fragment -in 1nhu.ism -map 1nhu_prot.mtz -prot 1nhu_prot.pdb \
              -out 1nhu-poses.sdf

When in fragment mode, it is better to output to a format that
supports SD style data (.sdf, .oeb).  This makes it much easier to
analyze the results in a molecular viewer that supports a sortable
spreadsheet.  (**VIDA**, **MOE** and so on)

To sort the results using another scoring function, use the
**-sortBy** flag.

.. code-block:: console

   > flynn -sortBy chemscore -in 1nhu.smi ...


.. _flynn_help:

.. program:: flynn

============================
Command Line Help
============================

A description of the command line interface can be obtained by executing FLYNN
with the `--help` option.

.. code-block:: console

   > flynn --help

will generate the following output:

::

  Help functions:
    flynn --help simple      : Get a list of simple parameters
    flynn --help all         : Get a complete list of parameters
    flynn --help <parameter> : Get detailed help on a parameter
    flynn --help html        : Create an html help file for this program


.. |product|        replace:: AFITT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _flynn_opt_params:

.. program:: flynn

=======================
Optional Parameters
=======================

Input Options
^^^^^^^^^^^^^

.. option:: -prot <filename>

   Optional protein used to mask density.  This model is used to mask away density where
   the ligand should not be placed.  While the protein is not required,
   it is highly recommended.

   ============   ===========================
   File type      Extension
   ============   ===========================
   OEBinary       .oeb .oeb.gz
   ------------   ---------------------------
   SDF            .sdf .mol .sdf.gz .mol.gz
   ------------   ---------------------------
   MOL2           .mol2 .mol2.gz
   ------------   ---------------------------
   PDB            .pdb .ent .pdb.gz .ent.gz
   ------------   ---------------------------
   MacroModel     .mmod .mmod.gz
   ============   ===========================

.. option:: -fragment

Fragments are fit taking the input fragment cocktail and, one at a
time, fitting each fragment against each region of detected density.
Once a fragment has been placed, it is further analyzed to ensure that
all possible orientations of the fragment have been sampled.  In poor
density, several orientations may fit equally well.  To break ties,
FLYNN scores each pose with the following scores:

 o RSCC (real space correlation coefficient)  This is a measure of fit to electron density. [Jones-1991]_

 o PLP Piecewise-linear potential.  [Verkhivker-2000]_

 o Chemscore [Eldridge-1997]_

The docking scores are not used to fit the molecule, they are only
used to rank the output.  Unless highly symmetric molecules are being
input, the real space correlation coefficient (RSCC) is the preferred
method of ranking results to density.

All scores are annotated to the output ligands using SD data when
appropriate (.SD and .OEB output) or using the PDB remark field:

::

 Example PDB output

 REMARK OpenEye Flynn MMFF/Shape v 2.1.0
 REMARK Stereo Variant:      1
 REMARK Blob:                1
 REMARK Conformer:           1
 REMARK Tanimoto Shape:        0.2004
 REMARK Tanimoto MMFF/Shape:   0.2034
 REMARK Local Strain:          4.9316
 REMARK RSCC: 0.529438
 REMARK PLP: -51.395416
 REMARK Chemscore: -16.288113

::

 Example SDF output

 > <Tanimoto MMFF/SHAPE>
  0.2034

 > <Tanimoto Shape>
  0.2004

 > <Overlap>
 364.767659122018

 > <Fit Overlap>
 781.301114117834

 > <Local Strain>
  4.9316

 > <Lambda>
 1.600000023842

 > <Ref Overlap>
 1371.829467773438

 > <Stereo>
 1

 > <Blob>
 1

 > <Conformer>
 1

 > <RSCC>
 0.529438

 > <PLP>
 -51.395416

 > <Chemscore>
 -16.288113

To use fragment mode, please add the "-fragment" option to the command
line.  In future versions of FLYNN, this will most likely become the
default setting.

The output of the fragment fitting process is a file for each density
region that includes the fragments fit to the region sorted from
best-fit to worst fit.  For example:

.. code-block:: console

   > flynn -in fragments.smi -out 2IKO_cocktail.sdf ...

would result in the files:

.. code-block:: console

  2IKO_cocktail_blob001.sdf
  2IKO_cocktail_blob002.sdf
  2IKO_cocktail_blob003.sdf

one for each blob found.  The first molecule in the file is the best
fit to the density.

To sort using another measure, for instance, PLP, use the sort flag:

.. code-block:: console

   > flynn -sortBy plp -in fragments.smi -out 2IKO_cocktail.sdf ...

When oeb format is used, the blob is also stored in the OEB file.
When using VIDA, simply expand the molecule to investigate the
blobs density.

.. option:: -param <parameter filename>

   A parameter file is a text file that lists parameter settings to be used
   during a run.   If a parameter is specified both on the command line and in
   the parameter file, the value specified on the command line is used.

   The format of the parameter file is as follows:

   * One parameter per line

   * For non-list parameters one key-value pair per line.

   * For list parameters a key followed by all the values.

   * Boolean parameters must be listed as a key followed by true or false.

   * The parameter file may not contain the :option:`-param` parameter.

   * Lines beginning with # are considered comments

   [Aliases=**-com**]

.. option:: -prefix <file prefix>

   Define the default prefix to use for loggging and report file generation.

   This -prefix is overridden when using the *-reporthtml* or *-reportfile*
   command line options.

   [Default=flynn]

.. option:: -manualSearch <filename>

   Use the input molecule to generate a box volume.  All density inside this
   box will be used to place the ligand.

   [Aliases=**-box**]

.. option:: -boxpad <number>

   Pad the box created with the *-manualSearch* flag by an amount in
   |Angstroms|.

   [Default=1.0]

.. option:: -autoThenManualSearch

   Automatically search for blobs first, if now suitable blobs are found, use the
   supplied box to bound density.

   [Default=false]

   [Aliases=**-blobsThenBox**]

.. option:: -densityAsIs

   Use the supplied density as it is; do not try to find suitable
   blobs inside the density.  Note that
   the supplied density has to be pretty close to the actual ligand
   density for this to work

   [Default=false]

.. option:: -distance <value>

   Reject blobs whose average distance to the protein is greater than
   this value.

   [Default=4.0]

.. option:: -ligandAsIs

   Do not generate conformations for the ligand; use only the supplied
   conformations.

.. option:: -mmff94s

   Use the MMFF94s variant of the MMFF94 forcefield ( this uses
   planar aniline nitrogens ).

  [Default=true]

.. option:: -ff <forcefield>

   Select the forcefield to use for fitting the molecule into density.

   ===============================  ========
   Value                            Meaning
   ===============================  ========
   mmff94                           MMFF94
   mmff94s                          MMFF94s (default)
   am1                              AM1
   am1-sheffield                    AM1-Sheffield
   pm3                              PM3
   pm3-sheffield                    PM3-Sheffield
   mmff94-electrostatics            MMFF94 with electrostatics
   mmff94-electrostatics-sheffield  MMFF94 with Sheffield electrostatics
   ===============================  ========

   [Default=mmff94s]

.. option:: -reportfile <filename>

   File location for writing the report file.  This is a comma
   separated file containing specifics about the results.

  Smiles,Blob,Stereo Variant,Conformer,Tanimoto Shape,Tanimoto MMFF/SHAPE,Local Strain
  CC(=O)[C@H]1CC[C@@H]2[C@@]1(CC[C@H]3[C@H]2CCC4=CC(=O)CC[C@]34C)C,1,,,0.4110,0.4296,1.342
  CC(=O)[C@H]1CC[C@@H]2[C@@]1(CC[C@H]3[C@H]2CCC4=CC(=O)CC[C@]34C)C,1,,,0.313,0.3704,4.553
  CC(=O)[C@H]1CC[C@@H]2[C@@]1(CC[C@H]3[C@H]2CCC4=CC(=O)CC[C@]34C)C,1,,,0.3265,0.3628,5.223

.. option:: -resname <name>

   Set the output residue name to **<name>**.  **<name>** must be less
   than or equal to three characters in length.  This forces the
   output residue to be named <name> even if the residues structure
   does not match a known deposited residue.

.. option:: -chainid <chainid>

   Forces the ligand to be placed in the chain <chainid>

.. option:: -assignClosestChainId

   Assign the closest protein chain (within 7 Angstroms) to set the
   ligand's chain id.  Cannot be used with the explicit :option:`-chainid`
   setting.

   [Aliases=**-assignClosestChainID**,**-assignClosestChainid**]

.. option:: -sortAllChiral <true/false>

   If set to true, when multiple chiralities are enumerated, sort
   all chiralities from best to worst per blob, otherwise sort
   chiral structures independently.  For example, if two blobs are
   found, then the output will have all chiral structures sorted from
   best fit to worst fit for the first blob, and then all chiral
   structures sorted from best fit to worst fit for the second
   blobs, etc Note that the second blob may contain better fits than the
   first.   (Note: This
   may interleave chiral structures).

   [Default=true]

.. option:: -verbose

 This is a boolean flag that controls the level of
  detail written to the log file.  By default FLYNN will only write
  minimal information to the console.
  Verbose logging will cause more information to be written to the log
  file in order to follow behavior during program execution.

  [Default=false]

.. _mtzsettings:

MTZ File Options
^^^^^^^^^^^^^^^^

The allowed MTZ map types and the corresponding column conventions are
documented in :ref:`OESystem_OEReadMTZ` in the **OEChem TK** manual.

.. option:: -autoMTZ

   Automatically try to open the mtz file using the DELWT and
   FDELWT columns from REFMAC5 mtz files.

   See :ref:`OESystem::OEMTZMapType::Fdelwt <OESystem_OEMTZMapType_Fdelwt>` for the corresponding
   difference-map type in **OEChem TK**.

   [Default=true]

.. option:: -Fc <columnname>

   Column to use for Fc.  *Note, to load arbitrary columns, you can use the **-Fc**
   and **-Phic** columns and the **Fc** maptype.*

   [Default=FC]

.. option:: -Fdelwt <columnname>

   Column to use for Fdelwt or difference map amplitudes

   See :ref:`OESystem::OEMTZMapType::Fdelwt <OESystem_OEMTZMapType_Fdelwt>` in **OEChem TK** for map
   type details.

   [Default=DELFWT]

.. option:: -Fobs <columnname>

   Column to use for FObs.

   [Default=F]

   [Aliases=**-Fo**]

.. option:: -Phi <columnname>

   Column to use for Phi.

   [Default=PHI]

.. option:: -Fwt <columnname>

   Column to use for Fwt or regular map amplitudes.

   See :ref:`OESystem::OEMTZMapType::Fwt <OESystem_OEMTZMapType_Fwt>` in **OEChem TK** for map
   type details.

   [Default=FWT]

.. option:: -Phic <columnname>

   Column to use for Phic.

   [Default=PHIC]

.. option:: -Phidelwt <columnname>

   Column to use for Phdelwt or difference map phases.

   [Default=PHDELWT]

.. option:: -Phiwt <columnname>

   Column to use for Phwt or regular map phases.

   [Default=PHWT]

.. option:: -SigmaA <columnname>

   Column to use for SigmaA.

.. option:: -mtype

   The map type to use for fitting. Fo-Fc, Fc, 2Fo-Fc, 3Fo-Fc, Fwt,
               Fdelwt...

   See :ref:`OESystem_OEReadMTZ` for the full list of map types and
   their MTZ-column interpretation.

   [Default=Fdelwt]

.. _flynnadvanced:

Advanced Options
^^^^^^^^^^^^^^^^

.. option:: -ciftype

  Specify the format of the refinement dictionary.  Legal values for refinement dictionaries
  are 'refmac', 'phenix' and 'buster'.  Refinement dictionaries are always
  written out using the designation specified in the '-split' command.
  For best results, use -split when writing out cif files when using FLYNN.

.. option:: -flipper

  Force enumeration of all stereochemical
  centers.  Otherwise, only missing stereo chemistry will be
  enumerated.

  [Default=false]

.. option:: -overlays

  Set the number of initial rigidly fit overlays to optimize
  into density.

  [Default=10]

.. _precheck:

.. option:: -precheck

  Perform only a preliminary check of the data
  to see if fitting is possible.  (This flag is meaningless without
  the -reporthtml flag).

  [Default=false]

.. option:: -reporthtml

  Generate an html report of the fitting
  process.  This is a useful first step to verify the data.  It also
  includes a 2D image of the ligand that is being fit in order to
  verify bond orders.  All output of FLYNN will be captured in
  the specified html file.

.. option:: -residues

  Comma separated list of residues to use as
  distance constraints.  If residues are specified, the
  *-distance* flag will use the residues to reject blobs that are
  too far away.  Note that with a residue list, the distance computed
  is a minimum distance, not an average distance.  Residues must be
  specified as <residue number><chain id>.  For example: 120C,134C.
  On Windows, double quotes must be added to specify two or more
  residues, i.e. -residues "120C,134C".

.. option:: -rms

  If the input ligand has 3D coordinates, this
  calculates the RMS distance to the ligand and records it in the
  molecule.  If -split is on, it also records it in the
  file name.

  [Default=false]

.. option:: -split

  Split the result into different files.  Each
  filename is annotated with the resulting shape score so that when
  the output directory is listed alphabetically, the best scores will
  be displayed in order.  In the case where the output format is pdb
  the ligand fitting results are written in REMARK statements at the
  top of the file.

  The splits are labeled as follows outputname_n###_b###_s###_c###
  where n### is the number of the ordered results, b### is the blob
  for the result, s### is the stereovariant and c### is the number
  of the conformer fit as ordered by MMFF/Shape.

  [Default=false]

.. option:: -suppressH

  By default FLYNN outputs hydrogens of
  the resulting poses.  Setting this to true will not output
  hydrogens.  It is always recommended to output hydrogrens
  for ligands in order to keep their chemistry the same
  as flynn's internal optimizer.  Only suppress hydrogens
  if your refinement package doesn't handle hydrogen
  names correctly.

  [Default=false]

.. option:: -fix_serial_numbers

  Force serial numbers to be unique when writing out the resulting
  pdb file for use in the refinement package.  This is usually
  caused by adding hydrogens to the ligand outside of the context
  of the protein and then using it in conjunction with the original
  PDB structure.

  [Default=false]

Fragment Fitting Options
^^^^^^^^^^^^^^^^^^^^^^^^

.. _fragment:

.. option:: -blobTanimoto

      Density is searched for each input ligand.  This flag
      sets the minimum tanimoto overlap for which to consider two
      blobs the same.  When pruning similar blobs, the larger is
      taken.

      [Default=0.45]

      [Aliases=**-bt**]

.. option:: -sortBy

    Choose the fragment sorting function, tanimoto, rscc (real space
    correlation coefficient), plp (piecewise linear potential) or
    chemscore.

    The fragments are fit in the normal fashion (tanimoto), but then
    re-scored and sorted using the chosen metric.

    [Default=rscc]

3D Construction Options
^^^^^^^^^^^^^^^^^^^^^^^
These are advanced conformer generation parameters.  Normally, they do
not need to be adjusted.  Please consult the OMEGA_ manual for
assistance:

.. _OMEGA: http://www.eyesopen.com/docs/omega/current/html/index.html

.. option:: -ewindow

  Controls the MMFF energy window when generating initial conformations.
  Normally, this setting does not need to be adjusted, however in some
  cases large floppy molcules may require an adjustment.  This setting
  is in kcals/mol.

  [Default=15.0]


.. _flynn_req_params:

.. program:: flynn

.. _flynn-interface:

=======================
Required Parameters
=======================

.. option:: -in <filename>

   File containing a molecule to be fit to density.

   ============   ===========================
   File type      Extension
   ============   ===========================
   SMILES         .smi .ism .smi.gz .ism.gz
   ------------   ---------------------------
   OEBinary       .oeb .oeb.gz
   ------------   ---------------------------
   SDF            .sdf .mol .sdf.gz .mol.gz
   ------------   ---------------------------
   MOL2           .mol2 .mol2.gz
   ------------   ---------------------------
   PDB            .pdb .ent .pdb.gz .ent.gz
   ------------   ---------------------------
   MacroModel     .mmod .mmod.gz
   ============   ===========================

.. option:: -out <filename>

   File containing resulting conformations exported in the following formats:

   ============   ===========================
   File type      Extension
   ============   ===========================
   OEBinary       .oeb .oeb.gz
   ------------   ---------------------------
   SDF            .sdf .mol .sdf.gz .mol.gz
   ------------   ---------------------------
   MOL2           .mol2 .mol2.gz
   ------------   ---------------------------
   PDB            .pdb .ent .pdb.gz .ent.gz
   ------------   ---------------------------
   MacroModel     .mmod .mmod.gz
   ============   ===========================

.. note:
   CIF files are always written as output.  They are written as if the
   molecules were split.  See the split flag in :ref:`flynnadvanced`
   below for more details.

  CIF output consists of the following files:

    1. a CIF file
    2. a PDB file (in case atom names were remapped) or links were added.
    3. an OEB file that contains the original molecule with annotations

  All output ligands are annotated with both the fit and docking score results (if appropriate)
  see :ref:`-fragment` below for a full description.

.. option:: -map <filename>

   Input density grid used to fit ligand.  Note that **mtz** files
   have additional settings, see :ref:`mtzsettings`

   ==============   ===========================
   Grid File type   Extension
   ==============   ===========================
   MTZ              .mtz
   --------------   ---------------------------
   OpenEye          .grd
   --------------   ---------------------------
   Grasp            .phi
   --------------   ---------------------------
   CCP4             .map .ccp4 .mrc
   --------------   ---------------------------
   XPLOR            .xplor xplmap
   --------------   ---------------------------
   ASCII Grid       .agd
   ==============   ===========================

   [Aliases=**-grid**,**-density**]



.. _flynn_usage:

.. program:: flynn 

============================
Usage Notes
============================

Minimum Requirements
----------------------

At the minimum, FLYNN requires a density file and a the
connection table of the ligand - usually derived from a supplied
molecule file e.g. .pdb, .sdf, .mol2, .smi.
FLYNN automatically searches the density for volumes of
unmodeled density that are similar in size to the input ligand.
Because of this it is highly recommended that a protein is also input
to FLYNN.  This makes the job of locating the ligand density less
prone to false positives.

Based on analyzing several hundred protein/ligand combinations, the
best way to use FLYNN for ligand fitting is described as follows
(of course your mileage may vary):

* **Always use a protein:**

  The protein is used to identify modeled
  density where the ligand cannot be placed.  Without this, FLYNN
  will identify many candidate locations for placing the ligand that
  will need to be analyzed.

.. note::
  **Working with data from Cryo-electron Microscopy (cryoEM):** 
  FLYNN searches for "blobs" in the density after masking out 
  the protein -- it is in these "blobs" that FLYNN attemps to place 
  ligands. For users working with cryoEM data, this means that, 
  e.g., un-modeled density associated with the phospho-lipid membrane 
  in membrane-bound structures will be (mis-)identified as potential 
  binding site(s) for ligands. Our recommendation would be to either 
  use volume segmentation tools to construct a mask for the membrane 
  and mask out this portion of the map prior to feeding the map into 
  FLYNN; or, to simply ignore the ligands placed in to this region 
  (though, if there are many extraneous "blobs" identified in the 
  membrane region, this may cause the program to run for much longer 
  than otherwise necessary). The same general note can be made for 
  regions of the map associated with proteins or other cofactors in a 
  complex that are unmodelled: these regions should be masked out of 
  the map prior to analysis with FLYNN, if possible.  

* **Use difference maps for X-ray crystallographic data when appropriate:**

  X-ray reflection data should be refined without a previous ligand
  conformation or generated without the ligand present.
  While in many cases, for X-ray data, the same result will be generated,
  if the ligand is fit to data refined with a previous ligand
  conformation, FLYNN may be biased towards the density modified
  by the pre-existing ligand conformation.
  Similarly, for cryoEM maps, structures used as input to FLYNN
  should be docked or refined into the map without a ligand present.
  If the input structure to FLYNN has a ligand present, the 
  "blob" associated with that binding site/pose may be masked out of 
  the map, and new prospective ligand binding poses may not be 
  generated appropriately.

* **use fragment mode for fitting fragments**

  If you have an input cocktail, use the *-fragment* flag.  This
  option simultaneously fits all the cocktails against density and
  sorts them by best fit.

Types of input ligands
-----------------------

Not all ligands can be successfully fit by FLYNN.  Such types include
large polypeptides or proteins, very flexible molecules, or simply
molecules that contain atoms that are not present in the MMFF94s force-field.

Perhaps the most important property is rotatable bond count.
Although FLYNN may be able to generate conformers for molecules with
more than 20 rotatable bonds, the results of such an exercise would be
dubious at best and should be taken with a grain of salt.

FLYNN will automatically check for unhandled atom types, but will
gladly try and fit large molecules or proteins that contain many
rotatable bonds usually with disappointing results.

.. note::

 **Dangers of PDB format for ligand input**
 Many crystallography packages do not enforce writing out connection
 table or bond order information when outputting pdb files, or worse,
 strip them out.  If bond distances are not correct FLYNN's
 attempt to automatically assign bond orders and atom types can be suspect.
 To facilitate this, FLYNN includes a *-precheck* flag that
 can be used to verify that the input ligand is identified correctly
 and for validation of the automatic bond order assignments.

Stereochemistry Enumeration
----------------------------

Compounds that contain unspecified or ambiguous definitions of
stereochemistry will be preprocessed before conformational sampling to
explicitly enumerate stereochemistry.  Input molecules that have
three dimensional coordinates inherently have stereochemistry
specified, but SMILES or two dimensional SD files may have atoms (R/S)
or bonds (E/Z) for which the stereochemistry is unknown or
unspecified.  In the case where the stereochemistry supplied is
suspect, FLYNN provides an option that will completely enumerate all
stereochemical centers.

The resulting
ligands will be sorted based on their best fit to density regardless
of the stereochemistry.  That is, the best solutions will percolate
to the top of the output.  See :option:`-sortAllChiral` for more details.

Refinement Dictionaries
-------------------------

Both FLYNN and its companion program WRITEDICT can generate
refinement dictionaries.  A refinement dictionary is needed to
maintain proper ligand geometry when using external reciprocal space
refinement programs such as REFMAC5 or CNS X/PLOR.

Refinement dictionaries are a list of geometrical constraints encoding
used chemical bonding and molecular conformation information.
They are used by various refinement packages to describe standard
geometries and constraints that are used during the refinement
process.  The
quality of the post refinement ligand conformations are directly
related to the quality of the constraints [Vagin-2004]_\ .

FLYNN comes bundled with a refinement dictionary writer
named WRITEDICT.  WRITEDICT uses the
MMFF94 forcefield to derive geometrical constraints for the
input ligands or ligand-protein complexes.
The output dictionaries enforce, as closely as
possible, the input ligand's geometries while allowing the refinement
programs to modify the geometry as needed.

WRITEDICT also automatically detects covalent bonds in pdb
files and inserts the appropriate PDB LINK records and covalent
bond entries in the output refinement dictionary.

REFMAC5 refinement dictionaries
---------------------------------

When outputting REFMAC5 refinement dictionaries,
WRITEDICT writes out a **.cif** file and a **.pdb** file.  The
**.pdb** file is written out for two reasons:

* **Inconsistent Hydrogen Naming**

  Some applications write out
  hydrogen names incorrectly in ways that cause REFMAC5 or
  visualization programs like coot or WinCoot to be
  unable to associate the hydrogens in the refinement dictionary with
  hydrogens in the pdb file.  In the worst case, REFMAC5
  will crash entirely.

  When necessary, *WRITEDICT* renames and renumbers hydrogens, if they exist, so
  that REFMAC5 won't crash and so the **.cif** file is
  consistent with the **.pdb** file.

* **Covalent Bonds**

  WRITEDICT detects covalent bonds and
  outputs proper LINK records in the **.pdb** file and proper
  covalent constraints in the **.cif** file.  Without using both
  outputs, REFMAC5 will not detect covalent bonds during
  refinement.

* **Known residues**

  When WRITEDICT detects a known residue, it may remap the atom names
  to be canonical with the known residue (this prevents REFMAC5 from
  failing to refine).  These new atom names are saved in the **.pdb**
  file that WRITEDICT outputs.

* **Input Ligands with no residue information**

  When WRITEDICT analyzes a ligand with no residue information, it
  assigns the whole ligand to a single residue (by default UNL).
  If this is not the desired outcome, the ligand must be put into
  **PDB** or **MOL2** format and the residues must be manually
  assigned.

It is highly recommended to use WRITEDICT's generated **.pdb** file in
conjunction with the **.cif**.

Looking up known residues
-------------------------

WRITEDICT has an internal dictionary of known residues.
By default, known residues names are retained when the graph of the known residue
is exactly the same as the input residue.  When this occurs, writedict
can replace REFMAC5's dictionary with the MMFF94 generated dictionary.
If the graphs do not match then WRITEDICT relabels the residue with
a new residue name since a different dictionary needs to be created.

.. note:
 Note that when a residue is matched, the atom names of the input
 residue are changed to match the atom names of the known residue.

Options available for residue matching is as follows:

 =============   ==========================================================
 Option          Meaning
 =============   ==========================================================
 exact           Known residue and input residue graphs must match exactly.
 -------------   ----------------------------------------------------------
 substructure    Input residue may be a substructure of the known residue.

                 **Cannot be used with the exact flag.**
 -------------   ----------------------------------------------------------
 fuzzybonds      Bond orders do not need to match
 -------------   ----------------------------------------------------------
 atomname        Atom names must match
 =============   ==========================================================

Options are set using the *-strict* flag and joined with colons
(:).

The default is:

 -strict substructure:fuzzybonds

To reject dictionaries that do not match exactly, use:

 -strict exact

However, the more permissive default setting has been known to generate
invalid dictionaries on occasion.  It is always safe to force exact
matches.

To have WRITEDICT attempt to see if the ligand's residue has already been
deposited in RCSB simply add the *-lookup* switch.  This forces
WRITEDICT to compare (based on the current *-strict* settings) the
input residue to all known residues.  This is useful if the input is
from a 2D connection table, such as smiles or does not contain residue
information.

MMFF94 versus MMFF94s forcefields
----------------------------------

The MMFF94s forcefield is a variant of MMFF94 that emulates
time-averaged structures typically observed during crystallographic
structure determination, mainly planar geometries at unstrained
delocalized trigonal nitrogen centers.  However, there are many theoretical studies
that show nitrogen centers are puckered [Halgren-VI-1999]_.

That being said, due to the prevalence of crystallographic examples
where time averaging has occurred,
many chemists erroneously consider the time-averaged structure to be
correct, hence this variant is available for use.

WRITEDICT approximates the MMFF94s forcefield by enforcing
planar aniline nitrogen configurations using the out of plane atom
types and parameters from the MMFF94s.  See the
*-planarAniline* parameter to specify planar constraints.

FLYNN and writing CIF Files
----------------------------

When FLYNN is run, CIF dictionary files are always written as output.
Because the dictionary files are not conformation independent,
they are written as if the molecules were split into separate files
whether or not the user specifies FLYNN's *-split* flag. (See the split flag
in :ref:`flynnadvanced` below for more details).  These files are
numbered, however, so that the file with the lowest number corresponds
to the best scored fit ligand.

For example, consider using the *-sortBy plp* flag and getting the
following output:

 1nhu-poses_n001_b001_s01_c003.pdb
 1nhu-poses_n002_b001_s01_c000.pdb
 1nhu-poses_n003_b001_s01_c001.pdb
 1nhu-poses_n004_b001_s01_c002.pdb

This indicates that the best fit to density (c000) has the second
best PLP score (n001).  By default the files are sorted by RSCC.

FLYNN CIF output consists of the following files:

    1. a CIF file
    2. a PDB file (in case atom names were remapped) or links were added.
    3. an OEB file that contains the original molecule with annotations

It is safest, however, to run WRITEDICT on the output ligand and
protein complex.  The CIF files generated by FLYNN are primarily
useful for adjusting torsions and geometries in various ligand
building programs, such as coot.

Results on The Gold Test Set
-----------------------------

Included in the FLYNN distribution is a copy of the protein+ligand
complexes that have structures factors available from the
*Electron Density Server* [Kleywegt-2004]_\ .

Along with this data set is a simple python script that can be used to
fit ligands to the test data set.  OpenEye has prepared the input test
set as follows:

1. The Structure Factors and protein complexes were downloaded from **EDS**.
2. The ligands were separated from the proteins.
3. The protein was re-refined using the original mtz file to remove ligand bias.

A simple directory structure was created as follows:

* **pdbcode/protein.pdb** - the re-refined protein
* **pdbcode/ligand.pdb** - the original ligand
* **pdbcode/protein.mtz** - the re-refined difference map density.

The following python script was used to run FLYNN on all of the
proteins.  (This script is also included in the FLYNN distribution)::

 #########################################################################################
 ## Copyright (C) OpenEye Scientific 2007,2008,2009,2010,2011
 #########################################################################################
 ## This script analyzes the Gold dataset shipped with the flynn distribution
 import os,sys
 command = "../../../bin/flynn -in %(CODE)s/ligand.pdb -map %(CODE)s/protein.mtz " \
           "-prot %(CODE)s/protein.pdb -out %(CODE)s_results.sdf " \
           "-verbose -rms -reportfile %(CODE)s.log %(REDIRECT)s %(CODE)s.out"
 if sys.platform == "win32":
   REDIRECT = "2>"
 else:
   REDIRECT = "&>"
 RMS = []
 for file in os.listdir("."):
    print file
    if os.path.isdir(file) and len(file) == 4:
        code = file
        CMD = command % {"CODE":code, "REDIRECT": REDIRECT}
        print CMD
        os.system(CMD)
        index = None
        rmses = []
        for line in open("%s.log"%code):
           if index is None:
              index = line.strip().split(",").index("RMSD")
           else:
              rmses.append( float(line.strip().split(",")[index]) )
        if rmses:
            print "\t===>Lowest RMS", min(rmses)

The results of FLYNN are shown in Figure :ref:`figure_goldresults`.
The mean RMS to the crystal structure is 0.676 Angstroms.

.. _figure_goldresults:

.. figure:: /_images/goldresults.png
   :align: center

   **Gold Test Set Results**

.. note: FLYNN could not fit one of the ligands in the Gold test set,
 namely 1VGC as this molecule contained a boron atom and the MMFF94
 force field is not parameterized for this atom type.  Replacing the boron
 with a phosphorous gave an RMS of 0.54 Angstroms to the crystal structure but
 this type of atomic replacement, while possible in a pinch, is suspect.




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: rotfit

.. _chapter_rotfit:

***************
RotFit
***************

====================
Overview
====================

**RotFit** is a side-chain fitting tool that quickly fits sidechains to 
the surrounding density.  Currently only a MTZ file can be used for
density Side chains can be fit using several techniques:

  1. Using the most probably rotamers and ranking based on 
     real space correlation (RSCC) to the density.

  2. pep-flipping the rotamer and ranking on RSCC.

  3. Full MMFF/Shape fitting in to the density.

By default **RotFit** searches the rotamers and pep-flips.

For **RotFit** to apply a changed residue, their has to have an
increase in RSCC and be above a minium value (currently 0.4).
Additionally, the RSCC must be greater by a minimum amount (0.05).

=================
Example Commands
=================

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing ROTFIT
with the `--help` option.

.. code-block:: console
   
   > rotfit --help

will generate the following output:

::

  Help functions:
    rotfit --help simple      : Get a list of simple parameters
    rotfit --help all         : Get a complete list of parameters
    rotfit --help defaults    : List the defaults for all parameters
    rotfit --help <parameter> : Get detailed help on a parameter
    rotfit --help html        : Create an html help file for this program
    rotfit --help versions    : List the toolkits and versions used in the application

====================
Required Parameters
====================

.. option:: -in <proteinfile>

  Input protein structure.  The side chains of this protein will be optimized.

  [Aliases=**-prot**,**-protein**]

.. option:: -map <mtz file>

  The input MTZ file to fit side chains against.

  [Aliases=**-grid**,**-density**]

.. option:: -out <protein>

  The protein structure with optimized side chains will be outputted to this file.

.. option:: -param <parameter filename>

   A parameter file is a text file that lists parameter settings to be used
   during a run.   If a parameter is specified both on the command line and in
   the parameter file, the value specified on the command line is used.

   The format of the parameter file is as follows:

   * One parameter per line.

   * For non-list parameters one key-value pair per line.

   * For list parameters a key followed by all the values.

   * Boolean parameters must be listed as a key followed by true or false.

   * The parameter file may not contain the :option:`-param` parameter.

   * Lines beginning with # are considered comments.

   [Aliases=**-com**]

.. option:: -verbose <true or false>

   Ouptuts copious extra information.

   [Default=false]

====================
Optional Parameters
====================

.. option:: -fixup_rotamers <true or false>

   Search the most probable rotamers and choose the one that fits best to
   the surrounding density.

   [Default=true]

   [Aliases=**-fixup-rotamers**]

.. option:: -fixup_pepflips <true or false>

   Search the pep-flips and pick the one that fits best to the surrounding
   density.

   [Default=false]

   [Aliases=**-fixup-pepflips**] 

.. option:: -fixup_shapefit_residues <true or false>

   Use MMFF/Shape to fit the residue into the surrounding density.
   Normally it is best to use **-fixup_rotamers** in conjunction with
   this flag.

   [Default=false]

   [Aliases=**-fixup-shapefit-residues**]

.. option:: -minimum_rscc <number>

   For a give residue if the best tested RSCC of any conformation is below this
   value the residue will not be modified.  This prevents optimization from
   happenening when the is no density anywhere near the side chain.

   [Default=0.4]

.. option:: -minimum_rscc_increase <number>
   
   For a given residue if the best tested RSCC of any conformation is not this
   much better than the starting conformation, then the residue will not be
   modified.

   [Default=0.05]

   [Aliases=**-increase**]

.. option:: -autoMTZ <true or false>

   Automatically try to open the mtz file using the DELWT and
   FDELWT columns from REFMAC5 mtz files.

   See :ref:`OESystem_OEReadMTZ` and
   :ref:`OESystem::OEMTZMapType::Fdelwt <OESystem_OEMTZMapType_Fdelwt>` in **OEChem TK** for map and
   column conventions.

   [Default=true]

.. option:: -Fc <columnname>

   Column to use for Fc.  *Note, to load arbitrary columns, you can use the **-Fc**
   and **-Phic** columns and the **Fc** maptype.*

   [Default=FC]

.. option:: -Fdelwt <columnname>

   Column to use for Fdelwt or difference map amplitudes

   See :ref:`OESystem::OEMTZMapType::Fdelwt <OESystem_OEMTZMapType_Fdelwt>` in **OEChem TK** for map
   type details.

   [Default=DELFWT]

.. option:: -Fobs <columnname>

   Column to use for FObs.

   [Default=F]

   [Aliases=**-Fo**]

.. option:: -Phi <columnname>

   Column to use for Phi.

   [Default=PHI]

.. option:: -Fwt <columnname>

   Column to use for Fwt or regular map amplitudes.

   See :ref:`OESystem::OEMTZMapType::Fwt <OESystem_OEMTZMapType_Fwt>` in **OEChem TK** for map
   type details.

   [Default=FWT]

.. option:: -Phic <columnname>

   Column to use for Phic.

   [Default=PHIC]

.. option:: -Phidelwt <columnname>

   Column to use for Phdelwt or difference map phases.

   [Default=PHDELWT]

.. option:: -Phiwt <columnname>

   Column to use for Phwt or regular map phases.

   [Default=PHWT]

.. option:: -SigmaA <columnname>

   Column to use for SigmaA.



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: rscc

.. _chapter_rscc:

***************
Rscc
***************

====================
Overview
====================

RSCC is a real-space fit calculation tool both real-space correlation
coefficient (rscc) and real-space R-factor (rsr).  By default this tool
calculates rscc.  RSCC was designed to be a standalone tool using the same
code that is used for ligand fitting by AFITT.

=================
Example Commands
=================

====================
Command Line Help
====================

====================
Required Parameters
====================

.. option:: -in <molecule file>

   Input molecule(s) to be scored against the density

   [Aliases=**-prot**]

.. option:: -mtz <mtz file>

   Input MTZ file to be used for calculations.  Currently only MTZ format is supported.

   [Aliases=**-density**,**-map**]

====================
Optional Parameters
====================
 
.. option:: -clamp_at_level

   Set an electron density contour sigma level (positive) to be used for calculating rsr values.
   [Default=0.0]

   [Aliases=**-level**]

.. option:: -flatten

   Flatten B-factors (20.0) of the input molecule.  This flag is to be used with the –scatter flag.
   [Default=false]

.. option:: -rsr

   Use rsr instead of rscc. [Default=false]

.. option:: -scatter

   Calculate Fc (calculated) density from the input molecule. [Default=false]

.. option:: -verbose

   This triggers copious logging of output to the screen. [Default=false]


.. _flynn_theory:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


Theory
======

Current methods of ligand fitting that are based on either
topological analysis of electron density [Menéndez-Velázquez-2003]_
global optimization of position and
conformation of a ligand in a density blob [Diller-1999]_
interatomic distance matrix [Koch-1974]_ [Cascarano-1991]_
or on varying torsion dihedral angles of shape-matched ligand
conformations [Oldfield-2001]_ are unable to prevent creation
of high energy, sometimes even chemically unrealistic, ligand
models. As a result, there are a number of PDB ligands with
unlikely, very high-energy structures [Perola-2004]_. For example,
the PDB
structure of an inhibitor of RNA polymerase in *1nhu* has significant
repulsion between the two methylene groups.

FLYNN is composed of two main components, location of ligand density and
ligand fitting.  Location of density generally works well with
clean density but there are times when ligand density is unclear
or not well resolved.  In the latter cases, the user should supply
a bounding box or simply just input the ligand density by itself
and use the density as is.

By default, FLYNN samples bioactive
conformations [Boström-2001]_ [Boström-2003]_ of the input ligand, however,
there are times when it might be desirable to input the ligand and
use it as is (see section :ref:`flynn_req_params` for more details).

Once the location of the ligand in the map and the conformations
have been selected, FLYNN then adapts the initial conformations
to the ligand density using a modern force-field, MMFF94
[Halgren-I-1996]_
[Halgren-II-1996]_
[Halgren-III-1996]_
[Halgren-IV-1996]_
[Halgren-V-1996]_
[Halgren-VI-1999]_
[Halgren-VII-1999]_

The potential function being used to adapt the ligand is

 :math:`V = V_{ff} + \lambda V_{shape}`

where :math:`V_{ff}` represents the internal energy of the ligand and
:math:`V_{shape}`
is the overlap between the ligand and the electron density.  :math:`\lambda`
is a mixing parameter that represents the degree to which the shape of
the density dominates the combined potential during the current optimization step [Wlodek-2006]_.

The strain placed on the ligand is bounded while the function
is optimized producing high-quality fits with low-strain ligand
conformations.

Fragment Fitting
----------------

Fragments are fit taking the input fragment cocktail and, one at a
time, fitting each fragment against each region of detected density.
Once a fragment has been placed, it is further analyzed to ensure that
all possible orientations of the fragment have been sampled.  In poor
density, several orientations may fit equally well.  To break ties,
FLYNN scores each pose with the following scores:

 o RSCC (real space correlation coefficient)  This is a measure of fit to electron density (higher is better). [Jones-1991]_

 o PLP Piecewise-linear potential (lower is better).  [Verkhivker-2000]_

 o Chemscore (lower is better). [Eldridge-1997]_

The docking scores are not used to fit the molecule, they are only
used to rank the output.  Unless highly symmetric molecules are being
input, the real space correlation coefficient (RSCC) is the preferred
method of ranking results to density.

To use fragment mode, please add the "-fragment" option to the command
line.  In future versions of FLYNN, this will most likely become the
default setting.

The output of the fragment fitting process is a file for each density
region that includes the fragments fit to the region sorted from
best-fit to worst fit.  For example:

.. code-block:: bash

   prompt> flynn -in fragments.smi -out 2IKO_cocktail.sdf ...

would result in the files:

.. code-block:: bash

  2IKO_cocktail_blob001.sdf
  2IKO_cocktail_blob002.sdf
  2IKO_cocktail_blob003.sdf

one for each blob found.  By default, the first molecule in the file is the best
fit to the density (RSCC):

    :math:`RSCC = \frac{\Sigma |p_{obs} - <p_{obs}>| \Sigma |p_{calc} - <p_{calc}>|}{(\Sigma |p_{obs} - <p_{obs}>|^2 \Sigma |p_{calc} - <p_{calc}>|^2)^\frac{1}{2}}` [Jones-1991]_

where obs refers to the experimental electron density and calc refers
to the calculated electron density sampled from grid points around
the residue being scored.  The experimental density is usually the
sigma weighted difference map when loading an MTZ map.  The calculated
density is generated by simulating scattering of the ligand
conformation with bfactors set to 20.

To sort using another measure, for instance, PLP, use the sort flag:

.. code-block:: bash

   prompt> flynn -sortBy plp -in fragments.smi -out 2IKO_cocktail.sdf ...

.. note::

  The *-sortBy* flag can be used in non-fragment mode as well.


Utilities
=========

.. toctree::
   :maxdepth: 3

   aligngrid
   rotfit
   rscc
   writedict


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: writedict

.. _chapter_writedict:

******************
WriteDict
******************

====================
Overview
====================

**WriteDict** is a comprehensive refinement dictionary generator that properly handles covalent 
bond restraints between the ligand and the protein.

=================
Example Commands
=================

The basic usage of writedict is to take an input structure and
generate the corresponding .pdb and .cif files for input into COOT or
REFMAC5.

.. code-block:: console

   > writedict -in 1nhu.ism -out 1nhu_out

This creates the files *1nhu_out.cif* and *1nhu_out.pdb*.  The pdb is
always created since the atom names may be remapped from the input.
Since the input contains no residue information, the ligand is placed
in residue "UNL".

To add your own residue names for unmapped residues:

.. code-block:: console

   > writedict -in 1nhu.ism -out 1nhu_out -residues 153

Note that if the given residue name (153) does not map to the known
residue 153 the next residue name in the unmapped residue list will be
used.  Since none are specified it will go to the standard defaults:
"UNL,UN1,UN2..."

.. note::

 When doing whole complexes, renaming residues gets quite
 complicated since you may not know which residues will map before you
 run WRITEDICT.

.. code-block:: console

   > writedict -in 1nhu.ism -out 1nhu_out -residues LIG -nolookup

Force the residue to be named LIG.  (It will also indicate an invalid
dictionary)

.. code-block:: console

 Warning: LIG   1: Known Residue, but does not map to previous residue: LIG from: RCSB
 Warning: LIG   1: previous smiles c1ccc2c(c1)CC3=C(NN=C23)c4ccncc4
 Warning: LIG   1: current  smiles c1ccc(cc1)CC(C(=O)[O-])N(Cc2cccc(c2)C(F)(F)F)C(=O)c3ccc(cc3Cl)Cl
 Warning: LIG: Keeping residue name (dictionary may be invalid)
 Warning: LIG: Adding new residue dictionary
 Warning: LIG: already in dictionary from: RCSB but with different structure.
 Warning: LIG: c1ccc2c(c1)CC3=C(NN=C23)c4ccncc4
 Warning: LIG: c1ccc(cc1)CC(C(=O)[O-])N(Cc2cccc(c2)C(F)(F)F)C(=O)c3ccc(cc3Cl)Cl
 Warning: LIG: Overwriting existing residue (dictionary may be invalid)

To ensure planarAniline constraints consistent with the MMFF94s
forcefield, use the *-planarAniline* flag.

.. code-block:: console

   > writedict -in 1nhu.ism -out 1nhu_out -planarAniline

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing WRITEDICT
with the `--help` option.

.. code-block:: console

   > writedict --help

will generate the following output:

::

  Help functions:
    writedict --help simple      : Get a list of simple parameters
    writedict --help all         : Get a complete list of parameters
    writedict --help <parameter> : Get detailed help on a parameter
    writedict --help html        : Create an html help file for this program

====================
Required Parameters
====================

.. option:: -in <filename>

   File containing a molecule to be fit to density.

   [Aliases=**-prot**]

   ============   ===========================
   File type      Extension
   ============   ===========================
   SMILES         .smi .ism .smi.gz .ism.gz
   ------------   ---------------------------
   OEBinary       .oeb .oeb.gz
   ------------   ---------------------------
   SDF            .sdf .mol .sdf.gz .mol.gz
   ------------   ---------------------------
   MOL2           .mol2 .mol2.gz
   ------------   ---------------------------
   PDB            .pdb .ent .pdb.gz .ent.gz
   ------------   ---------------------------
   MacroModel     .mmod .mmod.gz
   ============   ===========================

.. option:: -out <filename prefix>

  This specifies a prefix for outputting the
  refinement dictionary **.cif** or **.xplor** and the **pdb** file.
  The pdb file ( and pdb.oeb) is always
  output and should be used for purposes of refinement since
  WRITEDICT sometimes corrects faulty hydrogen atom names and
  will include LINK records in the pdb if covalent bonds are detected.

  The log file will also be written using this prefix as *<filename prefix>.log*.

.. option:: -prefix <filename prefix>

  Alias for *-out*

====================
Optional Parameters
====================

.. option:: -assignCCP4

  If true then CCP4 atom types will be
  assigned to the output pdb file.

  [Default=true]

.. option:: -includeRotors

  Set to true if the output should include
  rotor torsion terms.  If this is set to false, refinement programs
  will not be able to modify any rotors.

  [Default=true]

.. option:: -suppressH

  If true, no hydrogens are output.

  [Default=false]

.. option:: -dictionary_type

   Selects the output refinement dictionary format:

   ==========   =====================================
   Value        Meaning
   ==========   =====================================
   0 / refmac   REFMAC5 dictionary (default)
   1 / xplor    CNS/CNX (XPLOR) dictionary
   2 / phenix   PHENIX dictionary
   3 / buster   BUSTER dictionary
   ==========   =====================================

   [Default=refmac]

   [Aliases=**-type**]

.. _planarAniline:

.. option:: -planarAniline

   Use the MMFF94s variant of the MMFF94
   forcefield.  This forcefield emulates time-averages structures
   observed in crystallographic and other structure determination
   methods.

   The MMFF94s forcefield is a variant of MMFF94 that emulates
   time-averages structures typically observed during crystallographic
   structure determination, mainly planar geometries at unstrained
   delocalized trigonal nitrogen centers.  However, there are many theoretical studies
   that show puckering at nitrogen centers. (see MMFF VI. in JCICS)

   That being said, due to the prevalence of crystallographic studies,
   many chemist erroneously consider the time-averaged structure to be
   correct, hence this variant is available for use.

   [Default=true]

   [Aliases=**-mmff94s**]

.. option:: -strict

   Change the known residue matching mode.

   Options available for residue matching is as follows:

    =============   ==========================================================
    Option          Meaning
    =============   ==========================================================
    exact           Known residue and input residue graphs must match exactly.
    -------------   ----------------------------------------------------------
    substructure    Input residue may be a substructure of the known residue.

                    **Cannot be used with the exact flag.**
    -------------   ----------------------------------------------------------
    fuzzybonds      Bond orders do not need to match
    -------------   ----------------------------------------------------------
    atomname        Atom names must match
    =============   ==========================================================

   Options are separated by colons.  The default settings are set to
   limit the number of REFMAC5 issues.  -strict exact:substructure
   will find more matches, but increases the risk of REFMAC5 rejecting
   the dictionary.

   [Default=substructure:fuzzybonds]

.. option:: -lookup

  Attempts to lookup residues from the internal dictionary store
  using the current -strict status.  This is useful to find out
  if a residue has already been deposited in the RCSB.

  If -lookup is not set, mismatching residues will be given new
  names. [Default=false]

.. option:: -forceExistingResidueNames

   Force WRITEDICT to use the given residues, even if they do not match
   the deposited residues from the RCSB.

   [Default=false]

   [Aliases=**-nolookup**,**-force**]

.. option:: -writeFullDict

  If true then all refinement dictionaries
  are created for all residues.  If false only residues that are
  unknown or are in the set of replaceable residues
  or covalently bound to a ligand are output.  Setting this to
  true can confuse REFMAC5.

  {default=false]

.. option:: -residues

   Comma-separated list of default residue names to assign to unknown
   components.

   [Aliases=**-resnames**,**-res**]

.. option:: -split

   Split separate molecules (and bonded covalent structures) into
   different dictionaries. [Default=false]

.. option:: -fix_serial_numbers

   Fix serial numbers if there are duplicates in the input files.
   [Default=false]

.. option:: -fixResidueHydrogens

   If a residue has more hydrogens than the known dictionary entry,
   remove them. [Default=false]

.. option:: -fixups

   Set fixups for known bugs in refinement packages. Accepts a
   comma-separated list. Supported value: ``REFMAC560117_MODRES``
   (fixes LINK issues in CCP4 6.2.0 REFMAC5.6.0117; should be used
   with ``MAKE CONNECTIVITY YES``).

.. option:: -verbose

  Output copious information of how writedict operates. [Default=false]



.. BROOD documentation master file
.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



#################################
BROOD |brood_version|
#################################

.. toctree::
   :maxdepth: 3

   introduction
   vbrood/vbrood
   brood/brood
   chomp/chomp
   Utilities <brooddbmerge>
   Tutorials <tutorials/tutorials>
   theory/theory
   brooddatabase
   releasenotes/index
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt






.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _brood_introduction:

**************
Introduction
**************

**BROOD** is a lead generation tool designed to generate new and diverse compounds that satisfy isosteric and chemical
feature constraints while also incorporating synthetic feasibility.  Starting with a hit or lead molecule, **BROOD**
generates bioisosteric analogs by replacing user-specified portions of the lead with fragments that have similar shape
and electrostatics but with potentially novel connectivity and chemistry.  Fragments and scaffold couplings are derived
within the scope of a known chemical space, either user-specified or broadly relevant to medicinal chemistry (default
**BROOD** database).

**BROOD** can also be used within the context of structure-based design if experimental or modeled cocrystal structures
are available.  Resulting **BROOD** analogs can be readily filtered and prioritized based on bioisosteric similarity, 2D
chemical diversity, and 1D molecular properties. **BROOD** has multiple applications, including lead hopping, side-chain
enumeration, library design, and expansion of composition of matter patents.

The **BROOD** distribution comprises two programs as well as a script that can be run in conjunction with OpenEye's
molecular visualizer, **VIDA**.

==============
Applications
==============

The **BROOD** distribution contains three applications:

  :ref:`BROOD <chapter_brood>`

  The **BROOD** application creates analog molecules from a lead molecule by changing
  fragments of the lead, where the new analogs have potentially different properties.

  :ref:`vBROOD <chapter_vbrood>`

  **vBROOD** is the graphical interface of the **BROOD** application.

  :ref:`CHOMP <chapter_chomp>`

  The **CHOMP** application creates a **BROOD** database by fragmenting molecules,
  filtering the fragments, generating 3D conformations, and organizing and indexing the
  fragments for rapid searching.

==================
Utility Programs
==================

The following utility program is also included in this distribution:

* :ref:`brooddbmerge`: This utility creates a single database by merging two **BROOD** databases.

.. _defaultDatabase:

===============================
Installing the BROOD Database
===============================

Included in the **BROOD** product is a large database of fragments generated by fragmenting the ChEMBL molecular database
[Bento-2014]_.  This database is available for download from `db-downloads <http://www.eyesopen.com/db-downloads>`_ in
a platform-independent format.  For user convenience, the database is available in either ZIP or tar.gz format, though
either file can be used on any platform.

The **BROOD** database is large (>5G) and takes 15–30 minutes to download with a good internet connection.  When the
download is complete, move the file to a convenient location and unpack (either unzip or untar/gzip) the database. The
default **BROOD** database is a directory full of prepared files that are optimized to make common **BROOD** searches
execute quickly.

After unpacking the default database, set it as the default database.

1. Launch **vBROOD** either by double-clicking the icon or by using the command line interface, depending on your platform.

2. To specify a database, select ``->Edit Preferences....`` under the *Edit* menu. A preferences pop-up window will open.

3. Under the first line of the dialog, either type the path to your newly unpacked database or use the icon to open a file
   dialog that will allow you to browse to the database.  In either case, specify the directory created in the unpacking
   process as the database rather than selecting one of the files contained in the database.


.. _chapter_vbrood:

======
vBROOD
======

.. toctree::
   :maxdepth: 2

   vbrood_overview
   vbrood_build_run
   vbrood_create_query
   vbrood_run_brood
   vbrood_view_results
   vida

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


.. _vbrood_overview:

===========================
Overview
===========================

**vBROOD** is the graphical interface that ships with **BROOD**. It gives access to all the command line
features as well as some GUI-only features, such as query editing,
and placing constraint and color atoms.  

Upon completion, **BROOD** clusters the resultant molecules.  **vBROOD** presents the cluster heads
for viewing; the full clusters can be explored in **VIDA** (see :ref:`vida-cluster`).

Most **BROOD** options can be changed from within **vBROOD**. **vBROOD** can easily run **BROOD** in multiprocessor mode; however, it cannot run **BROOD** across a cluster.

.. figure:: /_images/vbrood_home.png
   :scale: 40
   :align: center
   :alt: Task Screen

   **Figure 1.** The **vBROOD** task screen.
   
**vBROOD** offers five tasks to help run **BROOD**:

* :ref:`vbrood_build_run`: Creates a query and immediately starts a **BROOD** run.
* :ref:`vbrood_build_query`: Creates and edits a query to save and send to a **BROOD** run.
* :ref:`vbrood_run_brood`: Runs **BROOD** with a query.
* :ref:`vbrood_view_results`: Browses results and launches the **BROOD** interface in **VIDA**.



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _vbrood_build_run:

=========================
Build and Run
=========================

*Build and Run* is the most direct way to run **BROOD**.  This feature walks you through the entire process of constructing
a query, setting up a **BROOD** run, and browsing results.

The *Build and Run* wizard consolidates the :ref:`vbrood_build_query` and 
:ref:`vbrood_run_brood` steps. However, the *Query Selection* page in the *Run BROOD* 
wizard is bypassed, and queries will be saved only in the *Run Directory*.

Build a New Query
==================

See the :ref:`vbrood_build_query` section.

Setting up BROOD
================

.. figure:: /_images/vbrood_run_setup_bnr.png
   :scale: 40
   :align: center 
   :alt: Run options

   **Figure 2.** Options for running **BROOD**.
         
The next step in running **BROOD** is choosing the run parameters.  Most options correspond directly to a command line option.
Hovering over most elements in the interface provides a brief description of the option as well as
the command line flag it represents.

The multiprocessor options, found in the *Quick Options* section, are particularly useful.  These options allow you to
run multiple **BROOD** instances using OpenMPI on the same machine as **vBROOD**. This allows additional
processors to be used if they are available.

When all options are set, click "Run" to start the **BROOD** run and advance to the *Run BROOD* page.

Run BROOD
=========

+-----------------------------------------------+--------------------------------------------------+
| .. image:: ../images/vbrood_running_bnr.png   | .. image:: ../images/vbrood_run_complete_bnr.png |
|   :width: 100%                                |    :width: 90%                                   | 
|   :align: Left                                |    :align: Left                                  |
|   :alt: A run in progress                     |    :alt: A completed run                         |
+-----------------------------------------------+--------------------------------------------------+
|   A run in progress                           |   A completed run                                |
+-----------------------------------------------+--------------------------------------------------+
             
    **Figure 3.** A comparison of in-progress and completed **BROOD** runs.

The screen will then switch to display a 2D hit list, the *Output* window, and the *Status*
window. This display will dynamically update as the run progresses.

   * The *Hit list* window shows the current cluster heads from the database.

   * The *Status* window on the left shows information about how many fragments have been processed, how many were
     actually scored against the query, and how many were eliminated.

   * The *vBROOD Output* window at the bottom displays the output of the **BROOD** run as if it were run from the command line.
     You can toggle between this output log and a spreadsheet of the top results by using the "Log" and "Results" buttons on the bottom right.
   * At the bottom right of the **vBROOD** window is a progress bar and a "Stop" button for aborting the run.

As the run progresses, the top results are displayed in the 2D hit list and the spreadsheet continues to update.
Both the spreadsheet and the 2D hit list provide scrollbars for browsing the hit list.  Clicking on a 2D depiction highlights
the same row in the spreadsheet and vice versa.
 
After a run completes, the buttons "Open in VIDA" and "Show on Disk" will be displayed and enabled.  Clicking "Open in
VIDA" opens **VIDA** with the **BROOD** *Results Viewer* tool loaded (see :ref:`vida-cluster`).  Clicking "Show on Disk" opens a
window displaying the directory containing the results of the run. If the run did not complete successfully, **BROOD** displays
a dialog box, and the *Output* window at the bottom shows the *Log* view.  Scanning the log may provide an indication of the problem.

Click "Browse Results" to bring up the list of all runs for the current session.  See :ref:`vbrood_view_results` for
more information.



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _vbrood_build_query:

===========================
Build a New Query
===========================

The process for building a query is as follows:

#. Load a molecule.
#. Select a fragment.
#. Modify the fragment to be replaced.  

The workflow will stop after editing the fragment and allow you to save the query.

Loading a Molecule
==================

The first step in creating a **BROOD** query is to load or create a source molecule.
The molecule can be loaded from a file, entered by name, or sketched in the sketcher.  

* To load a molecule from a file, either click the folder in the *Molecule* text entry box or choose a recently loaded
  molecule from the drop-down menu, which can be accessed from the arrow in the text entry box.

* To enter a molecule by name, type a structure name or a SMILES string in the text entry box. The 2D display will show
  a molecule if the entry is valid.

* To sketch a new molecule, click the + in the text entry box.  This opens the sketcher for input.  Sketch a molecule
  and click "OK" when you are satisfied with the sketch.

.. figure:: /_images/vbrood_load_molecule_bnr.png
   :width: 85%
   :alt: Loading a Molecule
   :align: center 
   
   **Figure 1.** Loading a molecule into **vBROOD**.

A protein can be loaded to provide a bump-check for generated
results, although protein chemistry is not used as part of the score.  You can also specify a
selection protein, which requires a protein atom to be close to the query as a simplistic screen for selectivity.

Below the protein text entry boxes, **vBROOD** displays the properties of the loaded molecule.  Any properties that
might need attention are highlighted in red.

Selecting a Fragment for Replacement
====================================

After loading or creating a molecule, **vBROOD** will display the 2D structure.  You must then select some portion of the
molecule for replacement.  You can select the fragment to be replaced in two ways:
 
* Click one or more of the highlighted fragments.

* Select a fragment by lassoing it.

+--------------------------------------------+--------------------------------------------+
|.. image:: ../images/vbrood_fragment.png    |.. image:: ../images/vbrood_lasso.png       |
|   :width: 85 %                             |   :width: 85 %                             |
|   :align: center                           |   :align: center                           |
|   :alt: Fragment-based selection           |   :alt: Lasso selection                    |
+--------------------------------------------+--------------------------------------------+
|   Fragment-based selection                 |   Lasso selection                          |
+--------------------------------------------+--------------------------------------------+

   **Figure 2.** How to select a fragment. For the fragment-based option, clicking on the
   pyrrolidine ring fragment highlighted it in orange.

Fixing Issues with the Query Structure
========================================

Some molecules may need additional fixes for problems found when they are loaded or selected. **vBROOD** highlights any
problematic atom or bond and displays a message in the lower-right corner.  If the message is red, the problem must be
addressed before you can continue to build the query.  Messages in yellow can be ignored, but should be addressed as
they may lead to unexpected behaviors.

The following examples show some common issues and how to fix them.

Unspecified Stereochemistry
---------------------------

**BROOD** requires the specification of certain types of stereochemistry.  Ignoring this problem can result in issues
with coordinate generation or with property filtering.  To fix unspecified stereochemistry, right-click on the red
highlighted atom or bond and select *Set Chirality* or *Set Bond Stereo* and choose the appropriate stereochemistry.

.. figure:: /_images/vbrood_fix_stereo.png
   :width: 50 %
   :align: center
   :alt: Fixing bond stereo

   **Figure 3.** Fixing bond stereo.

Broken Double Bonds
-------------------
BROOD does not allow double bonds to be broken by selection. To correct this problem, either click *Select Bond* or redo the selection.

.. figure:: /_images/vbrood_broken_double_bond.png
   :width: 50 %
   :alt: A double bond broken by selection
   :align: center

   **Figure 4.** A double bond broken by the selection.

Partially Selected Rings
------------------------

Broken aliphatic rings can be ignored (but will always be closed), but broken aromatic rings must be fixed.  To do this,
either click the *Select Ring* button or redo the selection.

.. figure:: /_images/vbrood_broken_ring.png
   :width: 50 %
   :alt: A ring broken by selection
   :align: center

   **Figure 5.** A ring broken by the selection.

More than Three Attachment Points
----------------------------------

BROOD databases have fragments containing between one and three attachment points. Thus with 
**BROOD** will not produce any results when you use a query with four or more attachments.
Redo the selection so that it has between one and three attachment points.

.. figure:: /_images/vbrood_too_many_attachments.png
   :width: 50 %
   :alt: A selection resulting in 4 attachment points
   :align: center         

   **Figure 6.** A selection resulting in four attachment points.

Overlapping Attachment Points
-----------------------------

Selecting two atoms that are each bonded to a third, unselected atom results in two attachment points overlapping.
To correct this, click *Fix* or redo the selection.

.. figure:: /_images/vbrood_overlapping_attachments.png
   :width: 50 %
   :alt: A selection resulting in overlapping attachment points
   :align: center         

   **Figure 7.** A selection resulting in overlapping attachment points.

No Selection
------------
**vBROOD** requires you to  select some fraction of the molecule or it will not continue. To fix this, select a fragment of the molecule.

Once a molecule has a valid selection and all problems have been resolved, the "Next" button will be enabled. Click "Next" to advance to the *Edit Fragment* step.

.. figure:: /_images/vbrood_fragment_edit_bnr.png
    :width: 85%
    :align: center 
    :alt: Edit fragment screen
             
    **Figure 8.** Edit fragment screen.

    
Editing fragments
=================

The *Edit Fragment* step allows users to edit some aspects of the replacement query. You can add and remove color atoms,
add and remove constraints, or remove atoms in the query.  This step
also displays the query structure in 3D and the attachment vectors as R-group atoms.
Color atoms are displayed as large spheres patterned and colored according to the color atom type.  
Constraint atoms are displayed as colored and patterned rings with a diameter corresponding to
the diameter of the constraint.
 

The Fragment Editor provides five tools for editing a query, shown as icons on the left side of the 3D window.

* *Select*. This option can be used to select a group of atoms for deletion.
* *Add Color Atom*. A drop-down menu is provided to select the color atom type.
* *Add Constraint Atom*. A drop-down menu is provided to select the constraint type.
* *Eraser*. This option can be used to erase an atom, color atom, or constraint.
* *Delete Selected*. This option deletes all selected atoms.

If the query includes a protein, it is also possible to toggle the visibility of the protein with the *Show Protein* and *Hide Protein* buttons.  

Adding a color atom
-------------------

.. figure:: /_images/vbrood_color_atoms.png
   :width: 45%
   :align: center
   :alt: Add Color Atom

   **Figure 9.** The menu to add color atoms.
   
Color atoms allow users to specify desired chemistry at specific places on the fragment.  Adding a color atom to a molecule is simple.

#. Select a color atom type from the *Color Atom* menu in the
   Fragment Editing toolbar.
#. Click an atom.  

Either color atoms or molecular atoms can be selected.  Multiple color atoms placed in the same location are displayed as
slices of the same color atom sphere.  By placing the same type of color atom at the same location, color atoms may be
weighted to increase their influence on the score.

To place a color atom in between one or more atoms, hold the Shift key while clicking additional atoms.  The color atom
will be placed at the center of mass of the selected group.

Adding a constraint
-------------------
+-------------------------------------------------+-------------------------------------------------------+
|.. image:: ../images/vbrood_constraint_atoms.png |.. image:: ../images/vbrood_constraint_atoms2.png      |
|   :width: 85 %                                  |   :width: 85 %                                        |
|   :align: center                                |   :align: center                                      |
|   :alt: The constraint menu                     |   :alt: A constraint                                  |
+-------------------------------------------------+-------------------------------------------------------+
|   The constraint menu                           |   A constraint                                        |
+-------------------------------------------------+-------------------------------------------------------+

    **Figure 10. Constraint options and example.**

A constraint is much like a color atom in that it represents desired chemical features.
Unlike a color atom, however, a constraint is a requirement, not a component of the score.
Adding a constraint to a molecule is largely the same as adding a color atom.

#. Select a constraint type from the constraint menu in the Fragment Editing toolbar.
#. Click an atom.  Multiple constraints in the same location will be displayed as segments of the same ring.

As with color atoms, to place a constraint in between one or more atoms, hold the Shift key while clicking additional atoms.  The constraint will be placed at the center of mass of the selected group.

.. figure:: /_images/vbrood_custom_const_dlg.png
   :width: 70%
   :align: center

   **Figure 11.** The custom constraint dialog box.

Custom constraints can also be defined with user-supplied SMARTS patterns.  To define a new constraint type,
select *Add Custom Constraint*.  
The *Add Custom Constraint* dialog prompts for a constraint name, a constraint SMARTS pattern, and a radius.
SMARTS patterns can either be typed into the SMARTS text editor or selected from the SMARTS dialog by clicking the + button.

  

Once these steps have been completed, click "Next" to progress to the next page.

Finishing up
============

After editing the query, either click "Save" or "Save and Run."  "Save" will ask for the file name and
return you to the task selection screen. "Save and Run" will ask for a file name, save, and then continue to the :ref:`Run BROOD<vbrood_run_brood>` task.


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


.. _vbrood_run_brood:

===========================
Run BROOD
===========================

**vBROOD** runs the **BROOD** command line application using a query.  It can run **BROOD** on multiple processors,
provide access to the command line options, display the output of the command line in a log window, and display
the best fragments found as the run progresses.

Load a Query
================

.. figure:: /_images/vbrood_run_query_select.png
   :scale: 40
   :align: center

   **Figure 1.** Loading a query.

The first step to running **BROOD** is to load or select a query.  

   * Previously built queries appear in the query list.

   * Queries can be loaded by clicking the *Open* option.

   * If the query does not have an associated protein, clicking on the *Open* icon in the *Protein* text box will allow you to add one.

After a query is selected, it is displayed in the 3D window.  Once it is loaded, clicking "Next" will take you to :ref:`filter-select`.

.. _filter-select:

Select a Filter
==================
.. figure:: /_images/vbrood_run_filter_select.png
   :scale: 40
   :align: center

   **Figure 2.** Choosing a filter.

A filter can limit the **BROOD** search and can shorten the run time.  **vBROOD** provides
a built-in drug-like filter; you can also build additional filters.  To use a filter,
select one from the list or open a previously saved filter.

To open a previously saved filter:

   * Click the *Open* item in the list.  This brings up a dialog that can be used to select a filter.
   
   * Select a filter file and click *Open*.  This adds and selects a new entry in the list.
   
Alternatively, you can select a filter from the *Recents* menu.  Selecting a filter will display its given properties in
the *Filter Values* box below the filter list.  When you are satisfied, click "Next" to continue to *Set up BROOD*.

Set Up BROOD
============

.. figure:: /_images/vbrood_run_setup.png
   :scale: 40
   :align: center 
   :alt: Run options

   **Figure 3.** Options for running **BROOD**.
         
The next step in running **BROOD** is choosing the run parameters.  Most options correspond directly to a command line option.
Hovering over most elements in the interface provides a brief description of the option as well as
the command line flag it represents.
 
The multiprocessor options, found in the *Quick Options* section, are particularly useful.  These options allow you to
run multiple **BROOD** instances using OpenMPI on the same machine as **vBROOD**.  This allows additional
processors to be used if they are available.

When all options are set, click "Run" to start the **BROOD** run and advance to the *Run BROOD* page.

Run BROOD
=========

+-----------------------------------------------+--------------------------------------------------------+
| .. image:: ../images/vbrood_running_bnr.png   | .. image:: ../images/vbrood_run_complete_bnr.png       |
|   :width: 100%                                |    :width: 85%                                         | 
|   :align: Left                                |    :align: Left                                        |
|   :alt: A run in progress                     |    :alt: A completed run                               |
+-----------------------------------------------+--------------------------------------------------------+
|   A run in progress                           |   A completed run                                      |
+-----------------------------------------------+--------------------------------------------------------+

    **Figure 4.** A comparison of in-progress and completed **BROOD** runs.

The screen will then switch to display a 2D hit list, the *Output* window, and the *Status*
window.  This display will dynamically update as the run progresses.

   * The *Hit list* shows the current cluster heads from the database.

   * The *Status* window on the left shows information about how many fragments have been processed, how many were actually
     scored against the query, and how many were eliminated.

   * The *Output* window at the bottom displays the output of the BROOD run as if it were run from the command line.
     You can toggle between this output log and a spreadsheet of the top results by using by using the "Log" and "Results"
     buttons on the bottom right.

   * At the bottom right of the **vBROOD** window is a progress bar and a "Stop" icon for aborting the run.

As the run progresses, the top results are displayed in the 2D hit list and the results spreadsheet continues to update.
Both the spreadsheet and the 2D hit list provide scrollbars for browsing the hit list.  Clicking on a 2D depiction highlights
the same row in the spreadsheet and vice versa.
 
After a run completes, the buttons "Open in VIDA" and "Show on Disk" will be displayed and enabled. Clicking on "Open
in VIDA" opens **VIDA** with the **BROOD** *Results Viewer* tool loaded (see :ref:`vida-cluster`).  Clicking "Show on Disk"
opens a window displaying the directory containing the results of the run. If the run did not complete successfully,
BROOD displays a dialog box, and the *Output* window at the bottom shows the *Log* view.  Scanning the log may provide
an indication of the problem.

Click "Browse Results" to bring up the list of all runs for the current session.  See :ref:`vbrood_view_results` for
more information.



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


.. _vbrood_view_results:

============
View Results
============

The final wizard launches the *Results Viewer*. This displays a list of all **BROOD** runs since launching **vBROOD**.
Selecting a single run displays the cluster heads from the hit list file. It also allows you to locate the file on disk
(using "Show on Disk") and to launch the **vBROOD** *Results Viewer*. Finally, previously generated results saved on
disk may also be loaded.

.. figure:: /_images/vbrood_browse_results.png
   :scale: 40
   :alt: Browsing results
   :align: center

   **Figure 1.** Browsing results from a **BROOD** run.

If the run was from the current session of **vBROOD**, the *Log* window will be populated with the output of **BROOD**.
This includes detailed information regarding how the results were generated.  Otherwise, it will be blank.

The **vBROOD** *Results Viewer* displays the cluster heads in 2D along with a spreadsheet containing medicinal chemistry
properties and scores.  The currently browsed run can be changed in the *Results* list box or by selecting the corresponding
spreadsheet tab.  Additional results can be loaded by selecting the *Open Results* option in the list box or choosing
*Open Results* from the *File* menu and choosing a hit list file.  *Results* can be closed by clicking on the red *X*
in the *Results* list.

Once a result hit list is selected, you can browse the cluster heads via the spreadsheet or by scrolling the 2D window.
Clicking on "Open in VIDA" will launch the **vBROOD** *Results Browser* for more full-featured exploration of the clusters (see :ref:`vida-cluster`).

If a set of results came from a run in the current **vBROOD** session, the *Log* file may be displayed by clicking on the
*Log* button in the lower right-hand corner. This displays the command line output of **BROOD** and can be useful in
diagnosing unexpected output.



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _vida-cluster:

===========================
Viewing Results in VIDA
===========================

:ref:`VIDA <vida-application>` is OpenEye's molecular visualization tool.
Although **vBROOD** provides some facility for browsing results,
**VIDA** allows for more full-featured cluster browsing.
**vBROOD** can launch the *Results Browser* tool from either the last page of a **BROOD**
run or from the *Results Browser* in **vBROOD**.  Click "Open in VIDA" to launch **VIDA** with the **BROOD**
Cluster Browser loaded.

.. figure:: /_images/vida_cluster_browser.png
   :width: 85%
   :align: center
   :alt: BROOD cluster browser in VIDA

   **Figure 1.** The **BROOD** Cluster Browser in **VIDA**.

Getting Started
========================

To open the **BROOD** Cluster Browser in **VIDA**, click "Open in VIDA" from either the *Browse Results* wizard or from
the *Run BROOD* page in the either the *Run BROOD* wizard or the *Build and Run* wizard.  If **VIDA** cannot be found or
has not been previously launched, **vBROOD** will prompt you to locate it.  The path to **VIDA** can also be specified in the
**vBROOD** preferences dialog.

When **vBROOD** launches **VIDA** with the cluster browser, it first displays the new user interface and then loads the
**BROOD** results.  After the results have been loaded, the cluster browser will open the *Hotkey Help* dialog box displaying
the various shortcut keys that can be used in the 3D window. This dialog can be closed by clicking "OK" and reopened
by clicking on the *Hotkey Help* button in the **BROOD** Cluster Browser window.

The **BROOD** Cluster Browser window displays information about the hit list as well as tools for controlling the visualization
of results, marking favorite molecules, and hiding other molecules in the *Trash*.

The **BROOD** Cluster Browser also adds a new menu, **BROOD** Viewer, which allows for loading and reloading **BROOD** results.

Viewing Clusters
==================

The **BROOD** Viewer has four sections: *Browsing Information*, *Visualization Control*,
*Favorites*, and *Garbage*.

Browsing
---------

.. figure:: /_images/vida_cluster_browser_browsing.png
   :width: 45%
   :align: center
   :alt: VIDA cluster browser Browsing section

   **Figure 2.** The *Browsing* section of the **BROOD** Viewer.
   
The *Browsing Information* section provides general information about the displayed hit list. It shows which hit list,
query, and protein are being displayed, information about the clusters in the file, and the current cluster being viewed.

The browsing window also contains a spinner that displays which cluster and which member you are currently browsing. The
left spinner lists the clusters. If the selected cluster is blue, you are navigating the cluster heads. The right spinner
shows the members of the current cluster. If the selected number in the right spinner is highlighted in blue, you are
navigating with the cluster.  This spinner can be useful for keyboard navigation.

Visualization
--------------

.. figure:: /_images/vida_cluster_browser_vis.png
   :width: 45%
   :align: center
   :alt: VIDA cluster browser Visualization section
    
   **Figure 3.** The *Visualization* section of the **BROOD** Viewer.

The *Visualization* section contains the primary set of controls.  The four buttons—*Favorites*, *Heads*, *Clusters* and
*Garbage*—control which structures are being displayed in the main view.

   * *Heads* navigates among the cluster heads.  

   * *Clusters* switches to browsing the current cluster members.  

   * *Favorites* displays any structures marked as favorites by the user.  
   
   * *Garbage* displays any molecules hidden in the garbage through the use of the Delete button.

The *Visualization* section also provides checkboxes to control the view.

   * *Lock Query* displays the query alongside a result in each pane in 3D.

   * *Lock Protein* displays the protein alongside a result in each pane in 3D.

   * *View in 3D* toggles the cluster display between 3D and 2D.

   * *View Multiple Structures* toggles between viewing a single result structure and a grid of structures.

   * *Properties* toggles the display of a context-sensitive spreadsheet which displays medicinal chemistry properties for the current cluster.

   * *Show Color Atoms* turns on the display of color atoms, if enabled by *Attach Color Atoms* under *Advanced Options* in **vBROOD**.

   * *Show Hydrogen Bonds* toggles the display of hydrogen bonds between the protein and the result molecules.

   * *Display Structures* controls the number of structures displayed in *Multiple Structure* view.

Favorites and Garbage
----------------------

.. figure:: /_images/vida_cluster_browser_fav_gar.png
   :width: 45%
   :align: Center
   :alt: VIDA cluster browser Favorites and garbage sections

   **Figure 4.** The *Favorites* and *Garbage* sections.

The *Favorites* section allows users to tag individual molecules as *Favorites* for further follow-up or saving.  The
number of favorites are displayed in the caption.  Below the caption are four buttons.

   * *Add* puts the current structure (surrounded by the blue box) into the *Favorites* list.
  
   * *Remove* takes the current structure (surrounded by the blue box) out of the *Favorites* list.

   * *Save* gives a prompt for a file name, then saves the *Favorites* list to disk.

   * *Clear* empties the *Favorites* list, moving all molecules back to their original location.

The *Garbage* section provides a way to hide structures from view. They are still available but are hidden from normal
browsing. The number of structures in *Garbage* is displayed in the heading. The *Garbage* can be browsed by
clicking *View Garbage*.  Clicking *Recover* while viewing a structure in the *Garbage* will put the molecule back into its original cluster.

Keyboard Control
------------------

.. figure:: /_images/vida_cluster_browser_hotkey.png
   :width: 45%
   :align: center
   :alt: VIDA cluster browser hotkey help screen

   **Figure 5.** The *Hotkey Help* dialog box.

The **VIDA** Cluster Browser script has key bindings for many common operations. The keyboard operations fall into two categories:
cluster navigation and display control.

Cluster Navigation Hotkeys
-----------------------------

The arrow keys are the primary navigation tool. They allow users to switch between navigating cluster heads and
cluster members, as well as to navigate among the cluster heads or cluster members.

 * The Right Arrow switches from navigating the cluster heads to the cluster of the currently selected head.

 * The Left Arrow switches back from a given cluster to the cluster heads.

 * The Up Arrow and Down Arrow navigate among the cluster or the cluster heads, whichever is currently being browsed.
 * Page Up and Page Down navigate by several molecules at once when multiple structures are displayed.
 * Delete moves a molecule to the *Garbage*.
 * Home moves to the first page of molecules (in the cluster members or among the heads).
 * End moves to the last page of molecules (in the cluster members or among the heads).

Display Control Hotkeys
------------------------

Many of the controls available in the *Visualization* section are also keyboard accessible.

 * *Q* toggles display of the query.
 * *E* toggles the hydrogen bond display.
 * *C* toggles between navigation of the heads and the clusters.
 * *D* toggles between the 2D and 3D display.
 * *A* toggles display of the protein (if any).
 * *S* toggles display of the spreadsheet.
 * *V* toggles display of multiple structures.
 * *F* adds a molecule to favorites.



.. _chapter_brood:

BROOD
=====

.. toctree::
   :maxdepth: 2

   brood_overview
   brood_inputs
   brood_example
   brood_help
   brood_params
   brood_outputs

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _brood_overview:

======================
Overview
======================

The basic idea behind **BROOD** is that you have a lead molecule and would like to
generate analogs with somewhat different properties by changing a portion of
the molecules.  Normally, you will load the lead molecule into the GUI and
select and edit the fragment you would like to replace.  The GUI will also
allow you to edit the chemical description of the query as well as define
required motifs (constraints).

**BROOD** will search the database of fragments for fragments with similar
shape, chemistry and electrostatics to your query fragment, replace them in your query
molecule and generate a hitlist of analog molecules.

If you are just getting started with **BROOD**, we highly recommend you use the
graphical interface.  Even if you prefer to use the command line, walking
through the graphical interface one time will give you a good overview of the
workflow involved in running **BROOD**.


.. _brood_input:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: brood

======================
Input Files
======================

Typically, a user will find it most convenient to generate the **BROOD** query
using the graphical interface.  Even if one wants to run **BROOD** on a
cluster or other machine where it isn't convenient to use the graphical
interface, the graphical interface can be used to generate the necessary input
and then **BROOD** can be executed on a different machine after moving the
input files.  **BROOD** requires one input file, a query fragment file.  With a
default installation, the **BROOD** application can search either one of the default
fragment database or a user-generated database.

.. _queryfiles:

-----------------------
Query Files
-----------------------

The entire query is encapsulated into a single query file, typically generated
in the GUI.  When generated, the GUI names the file *brood_1_query.oeb.gz*
where the *1* is replaced with the next appropriate integer to maintain unique
file names.  This **BROOD** query includes the original molecule, the fragment that
the user has chosen to replace, and the user-edited description of the shape,
chemistry, and electrostatics of the query.  In addition, if the query includes
protein structures either for bump-check or selectivity-check, these too will
be encapsulated in the query file.

**BROOD** carries out a 3D search, and a 3D search is required for the search and
is usually included in the query file.  The **BROOD** GUI can take either a 2D or a
3D query file.  If the original input is 2D, a 3D structure will be generated
in the GUI and used during the search.

.. _fragmentDatabase:

----------------------------------------
Fragment Database
----------------------------------------

As mentioned in the theory section, **BROOD** comes with a pregenerated,
multiconformer fragment database.  This database is made from fragments of
known molecules that contain 1-15 heavy atoms and 1-3 attachment sites.

**BROOD** can also search user-generated fragment files.  A custom database 
can be created using :ref:`chapter_chomp`.

.. _queryFileExamples:

-----------------------------------
Example Fragment Files
-----------------------------------

The database file used for **BROOD** searches is in a highly optimized format with
many precalculated properties and a complex structure intended to minimize
disk access during the time-critical search.  These database files can be
generated by the **CHOMP** program included with your **BROOD** distribution.  By
default, **CHOMP** will generate fragments from complete molecules.  On the other
hand, if a user has their own fragment files they would like to search, these
can be loaded directly into the **CHOMP** program and used to generate a searchable
database.

In this case, an input database fragment for bioisosteric searching must be a
molecular fragment with one or more "attachment points".  An attachment point
represents a bond from the fragment to the rest of the molecule.  Inside
**OEChem TK**, this is represented as a bond to an atom with atomic number 0 (termed a
"Dummy Atom").  If it is necessary to uniquely distinguish these dummy
atoms, Map Indices can be used via the :ref:`SetMapIdx and GetMapIdx methods of OEAtomBase <oechem_OEAtomBase>`.

The input fragment does not need to have 3D coordinates (they can, optionally, be generated
on-the-fly).  This makes SMILES and 2D SDF file formats the most convenient 
for query fragment input.  On the other hand, the fragment database should 
contain 3D coordinates with multiple conformers per fragment.  In the examples
below, a simple amide fragment with generic (amide) and uniquely labeled
(amideR) dummy atoms are shown.

SMILES format:

::

   *C(=O)N* amide
   [*:1]C(=O)N[*:2] amideR

SDF format:

::

   amide
     -OEChem-01040614232D

     5  4  0     0  0  0  0  0  0999 V2000
       0.0000    0.0000    0.0000 *   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 O   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 *   0  0  0  0  0  0  0  0  0  0  0  0
     1  2  1  0  0  0  0
     2  3  2  0  0  0  0
     2  4  1  0  0  0  0
     4  5  1  0  0  0  0
   M  END
   $$$$
   amideR
     -OEChem-01040614232D

     5  4  0     0  0  0  0  0  0999 V2000
       0.0000    0.0000    0.0000 R#  0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 O   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 R#  0  0  0  0  0  0  0  0  0  0  0  0
     1  2  1  0  0  0  0
     2  3  2  0  0  0  0
     2  4  1  0  0  0  0
     4  5  1  0  0  0  0
   M  RGP  2   1   1   5   2
   M  END
   $$$$

---------------------------
Molecular File Formats
---------------------------

**BROOD** can read and write a variety of molecular file formats.  The file format 
is automatically interpreted from the filename suffix.

.. _molecular_file_formats_table:

.. list-table::
   :widths: 20 20 50
   :header-rows: 1

   * - File Type
     - Input | Output
     - Extension
   * - SMILES
     - Output
     - :file:`.smi .ism .smi.gz .ism.gz`
   * - CXSMILES
     - Output
     - :file:`.cxsmiles .cxsmiles.gz`
   * - SDF
     - Input and Output
     - :file:`.sdf .sdf.gz`
   * - MOL2
     - Input and Output
     - :file:`.mol2 .mol2.gz`
   * - OEBinary v2
     - Input and Output
     - :file:`.oeb .oeb.gz .oez`
   * - List files
     - Input
     - :file:`.lst .list .lst.gz .list.gz`

Gzipped OEBinary version 2 (:file:`oeb.gz`) is the recommended output
format.

**BROOD** is capable of piping formatted input and output.  The simple "-" can be 
used in place of a filename to indicate :file:`std::cin` or :file:`std::cout` 
with the default SMILES format.

.. code-block:: bash

   prompt> brood -in .oeb.gz -db myDB < brood.query_1.oeb.gz

This execution will run **BROOD** with :file:`std::cin` as the input with *.oeb.gz*
format.  The format is controlled by the suffix.



.. _brood_example:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: brood

======================
Example Commands
======================

This section has a series of example **BROOD** command line executions.  Most **BROOD**
runs are carried out using **vBROOD**. Each example is followed by a brief
description of its behavior.

If you would like to execute the following examples as written, 
the appropriate paths to the executable file and the database file must be
included.  In addition, the query file :file:`q1.oeb` will need to be in the
working directory.

.. code-block:: bash

   prompt> brood -in q1.oeb -db chembl31

This command will execute BROOD with the default parameters. The file :file:`q1.oeb` is opened 
as the query, and the database is read from the chembl31 folder. The default hit list
will be written to :file:`brood_hitlist.oeb.gz`, using the default -prefix argument “brood”. 
Similarly, the informational output files :file:`brood_hitlist_rpt.csv`, :file:`brood_log.txt` 
and :file:`brood_parm.txt` will also be written.

.. code-block:: bash

   prompt> brood -in q1.oeb -db chembl31 -prefix 4dfr

This command is the same as the previous except that the prefix to all of the output files 
has been changed from “brood” to “4dfr” (for example, the log file will be written to 
:file:`4dfr_log.txt` rather than :file:`brood_log.txt`).

.. code-block:: bash

   prompt> brood -param 4dfr_parm.txt

This execution of **BROOD** will read all the command line arguments from the file
:file:`4dfr_param.txt`.  Every time **BROOD** is executed, a param file is generated
that can be used to exactly reproduce the run (*vida infra*).  This option is
most useful when the job is set up in **vBROOD** and the query and param file are
written out for later execution.  Using the command detailed here with a query
and param file from **vBROOD** will give the same results as running the search
from within **vBROOD**.

.. code-block:: bash

   prompt> brood -param 4dfr_parm.txt -ringOnly 0

This example illustrates two points: that command line arguments take
precedence over arguments in the :file:`.param` file, and that the
:option:`-ringOnly` flag is an important flag in altering **BROOD** results.  This
command line will execute **BROOD** with the parameters from ":file:`4dfr_parm.txt`",
but the :option:`-ringOnly` parameter will be overridden (taking precedence)
over the :option:`-ringOnly` parameter that is specified in :file:`4dfr_parm.txt`.
A similar outcome could be achieved by editing :file:`4drf_parm.txt` in a text
editor, but this command line alteration is a more direct means to the same
behavior.

By default, **BROOD** only returns fragments that have at least two ring atoms on
the shortest path between attachment points, or at least three ring atoms total
if there is only one attachment point.  This example shows that a user can turn
off this constraint using the :option:`-ringOnly` flag.  If one wants to
generate results that *only* avoid the rings as described above, one can pass
**-1** to the :option:`-ringOnly` parameter.

.. code-block:: bash

   prompt> brood -in q1.oeb -db chembl31 -quickLook 120

This execution will use the query in :file:`q1.oeb` to search the
fragments in the database :file:`chembl31`.  The use of the
:option:`-quickLook` parameter will limit the search to approximately the number of seconds (120) 
provided after the flag. The parameter is a great way to get a quick notion of interesting
results.  The databases are organized to allow rapid identification of
some interesting results.  The full search can take minutes to hours, and is
often more appropriate when designing molecules that may take days or weeks to
synthesize; nevertheless, in an iterative design session, it can be useful to
quickly generate ideas using the :option:`-quickLook` parameter.

.. code-block:: bash

   prompt> brood -in q1.oeb -db chembl31 -neutralpH false -tautomers false

When **BROOD** is building analogs by putting similar fragments into a molecular
framework, sometimes the electronic environment of certain functional groups
changes dramatically (amines converted to amides for instance).  To properly
handle these cases, it is useful for **BROOD** to normalize the ionization and
tautomer states of the new molecules before generating the final hit list.  In
some cases, users are better served without these normalizations.  The
ionization and tautomer normalizations can be turned off with the
:option:`-neutralpH` and :option:`-tautomers` flags, respectively.

.. code-block:: bash

   prompt> brood -in q1.oeb -db chembl31 -scoreType linkOnly

By default, **BROOD** compares the shape, chemistry, electrostatics, and attachment
geometry of fragments in order to suggest analog molecules.  For some
applications, such as joining fragments or closing rings, it is useful to build
fragments into empty space.  In these cases, one wants to only compare the
attachment geometry of fragments, in a manner similar to the original CAVEAT
searches [Lauri-1994]_. The :option:`-scoreType` ``linkOnly`` flag instructs **BROOD**
to compare fragments using only their ability to form low-energy bridges
between attachment points.

.. code-block:: bash

   prompt> brood -in q1.oeb -db chembl31 -property false

By default, **BROOD** filters the final analog hit list with a series of property
filters, each specified with a pair of range parameters.  While this can be
useful, on some occasions, users prefer to avoid all of the property filters.
By passing *false* to the :option:`-property` flag, all of the property filters
can be turned off in one easy step.


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _brood_help:

.. program:: brood

======================
Command Line Help
======================

A description of the command line interface can be obtained by executing **BROOD**
with the `--help` option.

.. code-block:: console
   
   > brood --help

will generate the following output:

::

   Help functions:
    brood --help simple      : Get a list of simple parameters
    brood --help all         : Get a complete list of parameters
    brood --help defaults    : List the defaults for all parameters
    brood --help <parameter> : Get detailed help on a parameter
    brood --help html        : Create an html help file for this program
    brood --help versions    : List the toolkits and versions used in the application




.. _brood_opt_params:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: brood

======================
Parameters
======================

File Options
==================

.. option:: -log

   The argument for this flag specifies the name of
   the log file.  The level of detail for logfile information can be
   altered using the :option:`-verbose` flag.  Generation of an
   output log may be disabled by providing ``nul`` as a argument in Windows and ``/dev/null`` as an
   argument on Linux and macOS.  
   [default = ``prefix`` _log.txt]

.. option:: -prefix

   The argument for this flag defines the prefix to be used
   for various information and data files generated.  Most
   important among these is the '*prefix_parm.txt*' file which includes a
   copy of all the parameters used in the run.  The prefix is
   also used to generate a default log file name if not explicitly
   specified with the *-log* flag. 
   [default = <app_name>].

.. option:: -verbose

   This is a boolean flag that controls the level of
   detail written to the log file.  By default only
   minimal information is written to the log file. 
   Verbose logging will cause more information to be written to the log
   file in order to follow behavior during program execution.  
   [default = false]

.. option:: -molNames

   This parameter takes a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set then only molecules in the
   input file(s) (see parameter :option:`-in`) with names that match those
   in the text files will be read in.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecule(s) that are contained in a large file, without
   having to extract those molecules by hand from the input molecules file.
   [default = NONE].


.. option:: -in (-qMol, -queryMol)

   Molecular file encapsulating the query.  It contains the primary molecule of
   interest, the query fragment, description of the query potential function
   and constraints, and the protein structures for the active site and for
   selectivity.  

.. option:: -out (-o)

   Output filename to be generated. Accepted file formats are:
   ``cxsmiles``, ``ism``, ``mol2``, ``oeb``, ``oez``, ``sdf``, ``smi``.

Execute Options
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -param

   The argument for this flag is the name of a
   file containing control parameters.  The control parameter file acts
   to either replace or augment the command line interface.  All
   parameters necessary for program execution may be provided in the
   control parameter file, although any command given explicitly on the
   command line will supersede options found in the parameter file.
   The application generates a new parameter file containing the full set of
   execution parameters upon every execution.  The name of the
   parameter file is created by combining the prefix
   base name with the *'_parm'* suffix and the *'.txt'* extension.

.. option:: -mpi_np <n>

   Specifies the number of processors ``n`` when the application is run in MPI mode.

.. option:: -mpi_hostfile <filename>

   Specifies the name of the file containing the processor's configuration. For every host,
   this file should contain a line ``host_name slots=n`` where ``n`` is the number of
   processors on the host.



-----------------
BROOD App Options
-----------------

.. option:: -db (-database) 

  Specified the directory containing the **BROOD** database files.  Additional
  details on the files contained in the directory can be found in the section
  on the :ref:`fragmentDatabase`.

.. option:: -cpddb 

  The user can specify a file of available compounds (either commercial or
  internal) with this flag.  If specified, molecules from this file that
  are similar to any created analogs will be used to annotate the newly
  suggested molecule. More details about analog similarity is described in
  :ref:`brood_compound_similarity` method. 

.. option:: -quickLook <n> (-quick)

   This flag allows a user to do a quick **BROOD** search (in ``n`` number of seconds).
   **BROOD** is designed to identify as many interesting hits as soon as possible.
   Thus while a thorough search may take minutes to hours, useful preliminary
   results can be generated in approximately ``n`` seconds with this option.

------------------------------
BROOD Hit List Builder Options
------------------------------

.. option:: -idea (-cluster)

   This flag determines if the hit list will be organized according to a reduced
   graph hierarchy.  This is quite useful for clustering similar analogs and
   thus allowing a user to quickly scan the different analog families and
   drill down into the most interesting clusters without needing to examine
   hundreds of analogs. [Default=true]

.. option:: -maxHits (-maxHit)

   This flag determines the number of compounds saved in the hit list.
   Allowable range is 1–50000.  **The legal range of this parameter has been
   increased by an order of magnitude.**  [Default=1000]

.. option:: -buildType 

   This flag determines the type of building to perform. Accepted values are
   ``2d`` (2 dimensional build), ``noopt3d`` (3 dimensional build without optimization),
   and ``optimized`` (3 dimensional build with optimization). [Default=optimized]

.. option:: -checkBond

   If this flag is set to ``True``, **BROOD** will check all bonds formed between
   new fragments and the rest of the query molecule and eliminate fragments
   that form bond types that are typically unstable.  Rather than being
   discarded entirely, these hits will be written in the
   :file:`brood_removed.oeb.gz` file by default. [Default=true]

.. option:: -deltaLocalStrain 
  
   Boolean flag indicating if the relative local strain between
   query and analog should be used as a measure of strain. [Default=false]

.. option:: -maxLocalStrain 
  
   Maximum local strain allowed to fit an analog molecule on top of a query. [Default=6.5]

.. option:: -neutralpH

   This flag controls whether the final molecules are set to an ionization
   state suitable at pH=7.4.  Because new bonds are formed in the process of
   generating analogs, functional groups sometimes need adjustment even if
   their state was properly normalized prior to fragmentation. This flag allows
   the user to turn off pKa normalization. [Default=true]

.. option:: -tautomers (-tautomer)

   Similarly, the :option:`-neutralpH` adjustment of tautomer states can be
   necessary after joining the new fragments with the static portions of the
   original molecule. This flag allows the user to turn off this normalization.
   [Default=true]

--------------------
BROOD Match Options
--------------------

.. option:: -attachCutoff  (-attachmentCutoff, -attachCut)

   Minimum acceptable attachment point score cutoff.  The cutoff is for the
   shape overlap score of the beginning and ending atom of each attachment
   bond.  The default was chosen empirically to assure all fragments in the
   hit list would have sensible attachment geometries.  This value does not
   affect runs when the :option:`-scoreType` flag is set to ``linkOnly``. [Default=0.78]

.. option:: -bondOrder (-bo)

   When this Boolean flag is set, only fragments with the same attachment bond
   orders as the query fragment are allowed. [Default=true]

.. option:: chargeType (-fileChrg)

   When this flag is set to ``fileChrg``, the partial charges for electrostatic Tanimoto
   calculations are taken from the input files.  If this flag is set to ``mmff94``, or the
   input file does not contain partial charges, MMFF94 charges will be used.  The
   partial charges on the database molecules are pregenerated.  [Default=mmff94]

.. option:: -checkGeometry

   By default, regardless of the attachment score (used primarily to drive the
   optimization), the fit of a fragment at the attachment points is controlled
   by geometric constraints.  These require that the two attachment vectors
   that will be jointed into a bond are overlapping and pointing in roughly
   opposite directions.  In some cases, particularly when the required geometry
   is unusual or strained, it can be useful to turn off this constraint check.
   [Default=true]

.. option:: -property (-prop)

   This Boolean flag indicates whether ANY of the molecular properties should
   be used to eliminate compounds from consideration.  While these filters can
   be useful, if a user expects to see a particular fragment or analog and it
   does not appear in the hit list, it will often have been eliminated by the
   property filters.  The :ref:`reportFile` will indicate which, if any, property
   filter affected each fragment.  If set to false, all of the related flags
   below become irrelevant. [Default=false]

.. option:: -ringOnly (-ring)

   This is a complex flag whose purpose is to allow the user to control the
   number of ring atoms in the selected fragments.  It allows input of "-2,
   -1, 0, or an integer 1 <= x <= 12".  This flag has to do with a count
   of the number of ring atoms in the shortest path between attachment points
   in a fragment.  In cases with more than two attachment points, all shortest
   paths are calculated and the number of ring atoms is summed.

   By default, the flag is set to "-2" (true) and requires at least two ring atoms in
   the path.  If the flag is set to "0" (false), no ring atom filtering is done,
   while if the flag is set to "-1" (none), only fragments without ring atoms in the
   shortest paths are returned.  If the flag is set to a number between 0 and
   13, then that will be the **minimum** number of ring atoms required.
   [Default=-2]

.. option:: -shapeCutoff

   Indicates the minimum required shape Tanimoto score required for a fragment
   to appear in the color, elect, or queryAnalog hit lists.  This cutoff is
   useful for cases when few shape-similar fragments exist in the database
   being searched.  [Default=0.6]

--------------------
BROOD Score Options
--------------------

.. option:: -attachScale (-attachmentScale, -attach, -aScale)

   This floating point value determines the balance between the chemical color
   score and the attachment point scores.  Higher values indicate more
   weighting for the attachment-point alignment.  This parameter has complex
   effects; please use it with care. [Default=1.5]

.. option:: -bumpRadius

   This real number flag determines the minimum distance between ligand heavy
   atoms and protein heavy atoms in the final relaxed solution for there to be
   considered a clash.  New analogs with atoms closer than this cutoff to the
   active site protein are discarded from the hit list.  If a selectivity
   protein is being used, at least one clashing atom must be found in order for
   the hit list ligand to be retained.  Because the molecular model of the
   protein is rigid, it may be advantageous for this cutoff to be
   shorter than in a system with a flexible protein model. [Default=2.25]

.. option:: -ignoreProtein (-noqueryprot, -noqueryprotein)

  When a query is created with the GUI and an active site protein is included,
  the section active site protein becomes part of the query.  This flag makes
  **BROOD** ignore the active site protein even though it is part of the query.
  The flag makes it easy to run the **BROOD** job with and without the active site
  protein. [Default=false]

.. option:: -ignoreProteinSelect (-noqueryselectionprotein, -noqueryselection)

  When a query is created with the GUI and a selectivity protein is included, the
  selectivity protein becomes part of the query.  This flag makes **BROOD** ignore the
  selectivity protein even though it is part of the query.  The flag makes it
  easy to run the **BROOD** job with and without the selectivity protein. [Default=false]

.. option:: -rangeOffset

   By default, the range of fragment heavy atoms specified by the
   :option:`-rangeSize` flag is centered around the same number of heavy atoms
   as the original query fragment.  Instead, the user can use this flag to bias a
   search toward smaller or larger fragments with positive or negative values
   passed to this flag. [Default=0]

.. option:: -rangeSize

   By default, only fragments with a number of heavy atoms +/- N from the
   fragment being replaced are considered.  This flag lets the user control
   this setting.  It should not be necessary to change this value except in
   unusual circumstances.  This flag determines the range of heavy atoms around
   query fragment's number of heavy atoms to examine. [Default=6]

.. option:: -scoreType  

   This flag can have three legal values: ``rocs``, ``et``, and ``linOnly``.
   If set to ``rocs``, the shape and color Tanimoto
   similarities are calculated. If set to ``et``, the electrostatic Tanimoto
   similarity is calculated on all of the fragments that also have a good shape score. 
   If this flag is set to ``linkOnly``, then the shape and chemistry of the fragment are
   ignored and ONLY the attachment point geometry (and constraints) are used to
   identify similar fragments. This is similar to Bartlett's Caveat algorithm,
   one of the first algorithms in this genre.  This type of search can be
   useful when trying to bridge one or more fragments without any prior
   knowledge, such as when linking two fragments in fragment-based design.[Default=rocs]
 
-------------------------
Molecule Property Options
-------------------------

.. option:: -eganEgg (-egan)

   This Boolean parameter determines whether analog compounds will be required
   to fulfill the "Egan egg" measure of bioavailability.  This measure was
   published by Bill Egan while at Pharmacopia [Egan-2000]_, and rejects
   compounds with a LogP > 5.88 or a PSA > 131.6. [Default=true]

.. option:: -veber (-gsk)

   This Boolean parameter determines whether analog compounds will be required
   to fulfill the measure of bioavailability Veber published at GSK
   [Veber-2002]_.  His measure of bioavailability eliminates compounds with a
   PSA > 140 or more than 10 rotatable bonds. [Default=false]

-------------------------
Extrinsic Property Values
-------------------------

.. option:: -minAcceptors (-minLipinskiAcceptors, -minLipinskiAcc)
.. option:: -maxAcceptors (-maxLipinskiAcceptors, -maxLipinskiAcc)

   These flags indicate the upper and lower bound of the Lipinski hydrogen bond
   acceptor range of any analog.  Analogs higher or lower in number of Lipinski
   hydrogen bond acceptors than these cutoffs will be eliminated from
   consideration.  For the purpose of this measure, hydrogen bond acceptors are
   determined by the method of Lipinski [Lipinski-1997]_.  [Default=2, 11]

.. option:: -minComplexity (-minComp)
.. option:: -maxComplexity (-maxComp)

   These flags indicate the upper and lower bound of the molecular complexity
   range of any analog.  Analogs higher or lower in molecular complexity than
   these cutoffs will be eliminated from consideration.  For more on molecular
   complexity, please see the theory section.  [Default=0.0, 2.5]

.. option:: -minDonors (-minLipinskiDonors, -minLipinskiDon)
.. option:: -maxDonors (-maxLipinskiDonors, -maxLipinskiDon)

   These flags indicate the upper and lower bound of the Lipinski hydrogen bond
   donor range of any analog.  Analogs higher or lower in number of Lipinski
   hydrogen bond donors than these cutoffs will be eliminated from
   consideration.  For the purpose of this measure, hydrogen bond donors are
   determined by the method of Lipinski [Lipinski-1997]_.  [Default=1,8]

.. option:: -minFrequency (-minFreq)
.. option:: -maxFrequency (-maxFreq)

   These flags indicate the upper and lower bound of the frequency range of any
   analog.  Analogs higher or lower in frequency than these cutoffs will be
   eliminated from consideration.  For the purpose of this calculation, the
   frequency is a percentile number indicating the frequency of each fragment
   normalized relative to the frequency of fragments in ChEMBL.  Frequency as
   assessed here is a measure of how common each fragment is among the source
   molecules.  The most commonly occurring fragment would be in the 99th
   percentile, while the least commonly occurring fragments would be in the
   1st percentile. [Default=0, 100]

.. option:: -minLipinski 
.. option:: -maxLipinski 

   These flags indicate the upper and lower bound of the Lipinski violations
   range of any analog.  Analogs higher or lower in number of Lipinski
   violations than these cutoffs will be eliminated from consideration.
   [Lipinski-1997]_.  In Lipinski's work, in order to segregate molecules that
   progressed through clinical trials, he determined that one violation was
   acceptable, but two were not.  [Default=0, 1]

.. option:: -minlogp 
.. option:: -maxlogp

   These flags indicate the upper and lower bound of the calculated LogP range of any analog.
   Analogs higher or lower in LogP than these cutoffs will be eliminated from consideration.  
   [Default=-1.0,5.0]

.. option:: -minMartin (-minAbbott, -minABS)
.. option:: -maxMartin (-maxAbbott, -maxABS)

   These flags indicate the upper and lower bound of the Abbott Bioavailability
   Score (ABS) range of any analog.  Analogs higher or lower in ABS than these
   cutoffs will be eliminated from consideration.  This floating point ABS
   parameter (range 0.0-1.0) indicates the minimum allowable probability that F
   will be >10% in rats according the QSAR model developed and published by
   Yvonne Martin [Martin-2005]_. A value of 0.0 will allow all compounds to
   pass. [Default=0.2, 1.0]

-------------------------
Intrinsic Property Values
-------------------------

.. option:: -minAromFJCt
.. option:: -maxAromFJCt

   These flags indicate the upper and lower bound of the aromatic ring range of
   any analog.  Analogs higher or lower in number of aromatic rings than these
   cutoffs will be eliminated from consideration. For the purpose of this
   calculation, the number of aromatic rings is the number of aromatic rings is
   #aromatic bonds - #aromatic atoms + 1. [Default=0, 5]

.. option:: -minFsp3C
.. option:: -maxFsp3C

   These flags indicate the upper and lower bound of the fraction of carbons
   that are sp\ :sup:`3` range of any analog.  Analogs higher or lower in the fraction of
   carbons that are sp\ :sup:`3` than these cutoffs will be eliminated from
   consideration.  There is some evidence that increasing the fraction of
   carbons in a series that are sp\ :sup:`3` (escaping from "Flatland") improved success
   in clinical trials [Lovering-2009]_. [Default=0.3, 1.0]

.. option:: -minHvyAtom (-minHeavyAtom)
.. option:: -maxHvyAtom (-maxHeavyAtom)

   These flags indicate the upper and lower bound of the heavy atom range of
   any analog.  Analogs higher or lower in number of heavy atoms than these
   cutoffs will be eliminated from consideration.  [Default=7,35]

.. option:: -minMolWt (-minmolecularweight)
.. option:: -maxMolWt (-maxmolecularweight)

   These flags indicate the upper and lower bound of the molecular weight range of any analog.
   Analogs higher or lower in molecular weight than these cutoffs will be eliminated from consideration.  
   [Default=100,500]

.. option:: -minRotBond (-minRotatableBond)
.. option:: -maxRotBond (-maxRotatableBond)

   These flags indicate the upper and lower bound of the rotatable bond range
   of any analog.  Analogs higher or lower in number of rotatable bonds than
   these cutoffs will be eliminated from consideration.  [Default=0,13]

.. option:: -minpsa (-mintpsa)
.. option:: -maxpsa (-maxtpsa)

   These flags indicate the upper and lower bound of the topological polar
   surface area (TPSA) range of any analog.  Analogs higher or lower in TPSA
   than these cutoffs will be eliminated from consideration.  [Clark-1999]_
   [Ertl-2000]_.  [Default=60,150]

.. _exampleExecutions:




.. _brood_output:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: brood

======================
Output Files
======================

**BROOD** generates seven output files in addition to the
hitlist.  All of these files begin with the prefix specified by the
:option:`-prefix` flag, that by default is "brood".  They also include an integer to retain unique file names in the working directory (in this example, we will use the integer "1").  These files include:

#. :file:`brood_1_info.txt`, the info file (This file is only created if the run is initiated from the GUI.)
#. :file:`brood_1_log.txt`, the log file 
#. :file:`brood_1_parm.txt`, the param file
#. :file:`brood_1_hitlist_rpt.csv`, the hitlist report file
#. :file:`brood_1_removed_rpt.csv`, the removed hits report file

By default, there is one hitlist and the contents of the hitlist will be determined by the command flags.

* :file:`brood_1_hitlist.oeb.gz` 

In postprocessing of the search, some fragments are removed from the hitlist.  These are preserved in the "removed" file.

* :file:`brood_1_removed.oeb.gz`

If the :option:`-scoreType` ``et`` flag is used, the hitlist will include molecules
electrostatically similar to the query.

Before executing the search, the GUI also writes the encapsulated query into the query file.

* :file:`brood_1_query.oeb.gz`

.. _infoFile:

---------------------
Info File
---------------------

By default, an information file titled :file:`brood_1_info.txt` is written or
updated for every 500 fragments that are processed.  Reading this info file
allows a user to monitor the progress of the database search while it is
occurring and it serves as a record of the performance of that search after the
execution is completed.  During execution, the GUI uses this file as well as direct
communication with the application to keep the user apprised of all information
available in the info file.

An example info file is shown below.

::

  *********** Progress Update ***********
  Percent of Database Processed    = 100%
  Number of Packets Processed      = 578
  Number of Fragments Processed    = 1642376
  Number of Fragments Overlayed    = 1094381
  Number of Hits                   = 909
  Number of Warnings               = 0
  Number of Errors                 = 0
  Processed fragments/sec          = 896
  Elapsed Time (sec)               = 1832
  ***************************************

If any errors are noted in the info file, it is strongly 
suggested that a user check in the log file to determine the nature of
the problem!

.. _paramFile:

-------------------------
Param File
-------------------------

**BROOD**'s command line interface can be efficiently run using the
:option:`-param` command line parameter followed by the name of a parameter
file.  Param files are files that contain one command line parameter on each
line.  Every execution of **BROOD**, including executions started within the GUI,
generates a .param file called :file:`brood_1_parm.txt`.  This file contains all of
the parameters used by **BROOD**.  Further, this file can be used in subsequent
runs with the :option:`-param` flag either with or without user modifications.

The :file:`_parm.txt` file is particularly useful if you want to use the graphical interface to
set up a job, but execute the job on another machine (such as a cluster).  The :file:`_parm.txt`
file can be moved to a different machine along with the :option:`-in` -queryMol file it
specifies, and it can be used to execute exactly the same run as would have been executed from
within the graphical interface.

The following is an example of a :file:`_parm.txt` file generated by the GUI (:file:`brood_1_parm.txt`).  It can be used to regenerate the run using the command line below.

This file could be edited or used as-is with subsequent runs.  In addition, any explicit command line parameter takes precedence over parameters in the .param file, so this mechanism can be used to execute a series of similar jobs.

.. code-block:: bash

   prompt> brood -param brood_1_parm.txt

   prompt> brood -mpi_np 16 -param brood_1_parm.txt -prefix brood_mpi1

Listing of :file:`brood_parm.txt` file contents:

::

  #Interface settings

  #Mode brood
  #-failed (Not set, no default)
  -in  /Users/Chemist/Desktop/brood.query.oeb.gz
  #-log  
  #-molNames  
  -out  brood_hitlist.oeb
  -prefix  brood
  #-report  
  #-verbose  false

  #Execute Options :   
      -param  /Users/Chemist/Desktop/brood_parm.txt
      #-mpi_np (Not set, no default)
      #-mpi_hostfile (Not set, no default)

  #Brood App Options :   
      #-cpddb  
      -db  /Users/Chemist/WorkingDirectory/chembl31
      #-quickLook  0
      -status  true
      
      #BROOD Hitlist Builder Options :   
          -idea  true
          -maxHits  1000
          
          #Molecule Builder options :   
              #-buildType  0
              -checkBond  true
              -deltaLocalStrain  false
              -maxLocalStrain  6.5
              -neutralPH  true
              -tautomers  false
      
      #BROOD Match Options :   
          -attachCutoff  0.78
          -bondOrder  true
          -chargeType  5
          -checkGeometry  true
          -property  false
          -ringOnly  -2
          -shapeCutoff  0.6
          
          #Molecule Property Options :   
              #-eganEgg  true
              #-veber  false
              
              #Maximum allowed extrinsic property values :   
                  #-maxAcceptor  11
                  #-maxComplexity  1.25
                  #-maxDonor  8
                  #-maxFreq  100
                  #-maxLipinski  1
                  #-maxLogp  5.0
                  #-maxMartin  1.0
              
              #Maximum allowed intrinsic property values :   
                  #-maxAromFJCt  5
                  #-maxFsp3C  1.0
                  #-maxHvyAtom  35
                  #-maxMolWt  500.0
                  #-maxRotBond  13
                  #-maxTpsa  150
              
              #Minimum required extrinsic property values :   
                  #-minAcceptor  2
                  #-minComplexity  0.0
                  #-minDonor  1
                  #-minFreq  1
                  #-minLipinski  0
                  #-minLogp  -1.0
                  #-minMartin  0.2
              
              #Minimum required intrinsic property values :   
                  #-minAromFJCt  0
                  #-minFsp3C  0.3
                  #-minHvyAtom  7
                  #-minMolWt  100.0
                  #-minRotBond  0
                  #-minTpsa  60
      
      #BROOD Score Options :   
          -attachScale  1.5
          -bumpRadius  2.25
          #-ignoreProtein  false
          #-ignoreProteinSelect  false
          -rangeOffset  0
          -rangeSize  6
          -scoreType  0

.. code-block:: bash

   prompt> brood -param brood_parm.txt

This would result in exactly the same execution as the one which generated the
file above.

.. _logFile:

-------------------
Log File
-------------------

The log file contains all of the critical information about the execution in
one place.  It begins with a copy of the param file and it finishes with the
final info file output.  In between, it contains all the warnings and errors
that might have occurred during execution.  The log file gives a user a single
place they can check to determine what job was run, if it executed properly, and
how long it took.

.. _reportFile:

----------------------
Report Files
----------------------

Report files contain a detailed listing of the similarity scores for every
molecule in the database that was sufficiently similar to warrant being in the hitlist.
By default, the file titled :file:`brood_1_hitlist_rpt.csv` contains information 
about every molecule that remained in the hitlist after postprocessing,
and :file:`brood_1_removed_rpt.csv` contains information about every molecule 
that was removed from the hitlist during the postprocessing.
  
  Report files contain columns for 

- database fragment SMILES
- database fragment title
- query SMILES
- number of attachment bonds
- structural rms value
- attachment score
- shape Tanimoto
- color Tanimoto
- combo score (shape + color)
- et attachment score
- et shape Tanimoto 
- electrostatic Tanimoto
- et combo score (shape + et)
- a comment regarding the disposition of the fragment (if and why it failed to be built)

If a particular score was not calculated for any given fragment, "-" will 
be found in the report file under the corresponding column.
Files are in comma-separated value format and can easily be imported into a
spreadsheet program for further analysis of the results.

.. _hitlistFile:

------------------------
Hitlist File
------------------------

As discussed above, a hitlist is generated for each execution of **BROOD**.  All of
the hitlists are written in the file format specified by the output
file name :option:`-out`, which defaults to gzipped OEB format :file:`.oeb.gz`, 
if the :option:`-out` is not specifically used. For instance,
if :option:`-out` ``Output.oeb`` is specified, the hitlist will have OEB format instead.
The first entry in the hitlist is the query molecule.  Each subsequent analog molecule
in the hitlist is oriented in the optimum overlay on the query
molecule.  For the :option:`-scoreType` ``linkOnly`` hitlist, this overlay is the optimum
overlay of the attachment point atoms.  In addition, by default, the similarity
scores and physical property data for each molecule are attached as
SDTags (OEB and SD format only).

By default, the hitlist files are written periodically while the search is
being carried out. This allows a user to examine results at intermediate 
stages without waiting for the entire search to complete.

If the :option:`-in` flag specified a 2D input molecule, 
then all of the analog molecules in the hitlist will likewise be in 2D format,
though the fragment similarity search will have been carried out in 3D. 
When using the graphical interface with a 2D input molecule, 
a 3D molecule is generated prior to processing and the output format will always be 3D.

Below we provide a description of some of the SDtags attached to the hitlist molecules:

**AroRingCt:** Number of aromatic rings in the molecule

**ClusterID/IdeaGroup:** ClusterID of the molecule 

**color:** Color Tanimoto score of the replacement fragment against the query fragment

**combo:** Shape + color Tanimoto combo score of the replacement fragment against the query fragment 

**Egan:** Boolean specifying whether the molecule passes the Egan bioavailability model

**Fragment:** SMILES string of the replacement fragment 

**freq:** Frequency of the replacement fragment

**fsp3C:** Fraction of sp\ :sup:`3` hybridized carbon atoms in the molecule

**HvyAtoms:** Number of heavy atoms in the molecule

**LipinskiDon:** Number of Lipinski donors in the molecule

**LipinkskiAcc:** Number of Lipinski acceptors in the molecule

**LipinskiFail:** Boolean specifying whether the molecule fails Lipinski's Rule of Five

**Local strain:** Calculated local strain of the molecule

**Delta Local strain:** Calculated delta local strain of the hit with respect to the query molecule

**Molecular TanimotoCombo:** Shape + color Tanimoto combo score of the molecule against the query molecule

**MolWt:** Molecular weight of the molecule

**p(active):** Belief score of the molecule [Muchmore-2008]_

**RingCt:** Number of ring atoms

**RingRatio:** Ratio of the number of ring atoms to the total number of heavy atoms

**Rotors:** Number of rotatable bonds in the molecule

**shape:** Shape Tanimoto score of the replacement fragment against the query fragment

**Source Mols:** SMILES strings of the molecules the replacement fragment is part of 

**Source Mol Labels:** Labels of the molecules the replacement fragment is part of 

**tPSA:** Calculated topological polar surface area of the molecule

**Veber:** Boolean specifying whether the molecule passes the Veber bioavailability model

**XlogP:** Calculated LogP of the molecule

------------------------
Removed File
------------------------

At the end of the primary fragment search, a complete hitlist is generated.  In
postprocessing, the fragments are built into whole molecules and tested for
strain, the newly formed bonds are examined for chemical stability, potential
duplicates in the hitlist are removed, and the new molecules are checked for bumps
with the protein environment and against the optional selectivity protein.  At
any of these stages, fragments that are similar according to the primary search
criteria may be removed from the hitlist for these secondary criteria.  In rare
cases, few fragments may remain in the final hitlist and the user may want to
examine the removed fragments without needing to rerun the entire search.  For
this reason, any fragment removed at the postprocessing stage is written to
the removed hitlist :file:`brood_1_removed.oeb.gz`.



.. _chapter_chomp:

CHOMP
=====

.. toctree::
   :maxdepth: 2

   chomp_overview
   chomp_example
   chomp_help
   chomp_req_params
   chomp_opt_params


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chomp_overview:

.. program:: chomp

======================
Overview
======================

**BROOD** includes a default database of approximately six million molecular fragments that are carefully selected to be medicinally relevant.  While this database is quite thorough, we recognize that some users may want to supplement the default database with fragments generated from their own proprietary molecule collections.  To facilitate this process, the **BROOD** distribution includes two programs, **CHOMP** and **BroodDBMerge**.

**CHOMP** allows users to fragment molecules, filter the fragments, generate 3D conformations, organize and index the fragments for rapid searching, and write a **BROOD** database.  This process can be carried out from start to finish using a **BROOD** license and does not require access to **OMEGA**, **FILTER**, **MolProp**, or **OEChem** licenses.  **BroodDBMerge**, a utility that allows users to merge their own corporate databases with the OpenEye default database, will be covered in detail in the following chapter.

At its simplest, **CHOMP** takes molecules as input and fragments them to generate **BROOD** databases; simply specify the molecules you want to use to generate fragments using the :option:`-in` flag and the output database you want to create with the :option:`-out` flag.

By default, **CHOMP** assumes you want to create a database from your proprietary
collection in order to augment the default database.  **CHOMP** does not automatically 
remove any duplicates from the generated
database.  To remove duplicates, you can specify the database of
fragments from which you would like to eliminate duplicates with the :option:`-userUnique` flag.  

The output from **CHOMP** will be a directory filled with a **BROOD** database.  
To search the database with **BROOD**, specify the *directory name* with
**BROOD**'s :option:`brood -db` flag.

While the basic use of **CHOMP** is straightforward, there are many options for controlling the **CHOMP** process and filtering the fragments.

.. note::

   **CHOMP** input molecules are pKa normalized, that is, set to pH=7.4 ionization state. 



.. _chomp_example:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: chomp

======================
Example Commands
======================

This section gives a series of examples of **CHOMP** command-line executions.  Unlike
**BROOD**, **CHOMP** does not have a GUI and must be accessed from the command line.
Each of these examples is followed by a brief description of its behavior.

.. code-block:: bash

   prompt> chomp -in mymolecules.smi -out myfragDB
   prompt> chomp -i mymolecules.smi -o myfragDB
   prompt> chomp mymolecules.smi myfragDB

All three of these command lines specify exactly the same thing.  In each case,
**CHOMP** will read the molecules in :file:`mymolecules.smi` and write the **BROOD**
database in the directory :file:`myfragDB`.  This is the most basic and most
common **CHOMP** execution.  Since the :option:`-dots` flag defaults to ``True``,
dots will be written to ``std:cout`` to indicate the progress of the molecular
fragmentation as the job progresses.  The :file:`myfragDB` directory will be
filled with just over 40 files that contain all the information critical for
efficient 3D **BROOD** searches.

.. code-block:: bash

   prompt> chomp -param oldrun.param

This execution of **CHOMP** will read the command-line parameters from the
file :file:`oldrun.param`.  Every time **Chomp** is executed, a file called
:file:`chomp.param` is written that records the command-line parameters used.
This is useful for recalling what was used in a specific execution or for
repeating a previous calculation.

.. code-block:: bash

   prompt> chomp -userFrags myFrags.sdf -out newDB

This reads the molecular fragments from the :file:`myFrags.sdf` and, bypassing
the fragmentation phase, generates 3D conformers and relates precalculated
parameters, and writes the database into multiple files in the :file:`newDB`
directory.

.. code-block:: bash

   prompt> chomp -in myMolecules.sdf -userUnique oldDB -out newDB

This execution of **CHOMP** behaves the same as the prior execution, except that
every fragment generated by the fragmentation of :file:`myFrags.sdf` will be
compared to the fragments in the **BROOD** database :file:`oldDB` (generated
earlier). Fragments that exist in the old database will not be included
in the :file:`newDB`.

.. code-block:: bash

   prompt> chomp -in myMolecules.sdf -omega false -out newDB

This reads and fragments the molecules from
:file:`myMolecules.sdf`, then writes all of the fragments (including source
information) to the SMILES file :file:`newDB.ism`.  It will not generate
conformers nor will it write a **BROOD** database.  The newly generated SMILES file
is available for examination and editing.  After this partial run, the database
preparation can be completed by passing the SMILES :file:`newDB.ism` into **CHOMP**
using the :option:`-userFrags` parameter.

.. code-block:: bash

   prompt> chomp -in myMolecules.sdf -readConfs xtals.sdf -out newDB

This execution of **CHOMP** reads and fragments the molecules from
:file:`myMolecules.sdf`.  Then, rather than using OMEGA to generate conformers
for the database, **CHOMP** uses the conformers read from the structures in
:file:`xtals.sdf` to generate conformers for the fragments.  These conformers
will be written into the new **BROOD** database :file:`newDB`.

.. code-block:: bash

   prompt> chomp -smarts bondids mymolecules.smi myfrags.oeb.gz
   prompt> chomp mymolecules.smi myfrags.oeb.gz -smarts bondids

This example demonstrates two important principles. The first is that the first of these two
command lines will work, but the second will result in an error.  When
specifying a command line with keyless arguments for the :option:`-in` and
:option:`-out` files, these files must be the final two arguments on the
command line.  

The second principle involves use of non-default fragmentation patterns.  In this
example, **CHOMP** uses the SMARTS patterns in the file :file:`bondids` to
generate fragments rather than the default fragmentation scheme.

.. code-block:: bash

   prompt> chomp -mpi_np 16 -in mymolecules.sdf -out newDB

In this execution, the :file:`mymolecules.sdf` is read, the molecules are
fragmented, 3D conformers are generated and the database is written to the
directory :file:`newDB`.  The fragmentation and the more expensive conformer
generation will be carried out on 16 local processors.  On modern multicore
workstations, this parameter is often a highly efficient means to execute
**CHOMP**.


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chomp_help:

.. program:: chomp

======================
Command Line Help
======================

A description of the command line interface can be obtained by executing **CHOMP**
with the `--help` option.

.. code-block:: console
   
   > chomp --help

will generate the following output:

::

   Help functions:
    chomp --help simple      : Get a list of simple parameters
    chomp --help all         : Get a complete list of parameters
    chomp --help defaults    : List the defaults for all parameters
    chomp --help <parameter> : Get detailed help on a parameter
    chomp --help html        : Create an html help file for this program
    chomp --help versions    : List the toolkits and versions used in the application



.. _chomp_req_params:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: chomp

======================
Required Parameters
======================

.. option:: -in (-i)

   This flag specifies the input molecule file that contains the database of
   molecules you want to break up into a fragment database.  If you have pregenerated
   fragments rather than whole molecules, please see the :option:`-userFrags`
   flag (see below).

.. option:: -out (-o)

   This flag specifies the location in which to create the **BROOD** database.
   **CHOMP** will create a new directory using the specified flag and will fill
   that new directory with a series of files.



.. _chomp_opt_params:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: chomp

======================
Optional Parameters
======================

Execute Options
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -param

   The argument for this flag is the name of a
   file containing control parameters.  The control parameter file acts
   to either replace or augment the command line interface.  All
   parameters necessary for program execution may be provided in the
   control parameter file, although any command given explicitly on the
   command line will supersede options found in the parameter file.
   The application generates a new parameter file containing the full set of
   execution parameters upon every execution.  The name of the
   parameter file is created by combining the prefix
   base name with the *'.param'* extension.

.. option:: -mpi_np <n>

   Specifies the number of processors ``n`` when the application is run in MPI mode.

.. option:: -mpi_hostfile <filename>

   Specifies the name of the file containing processors configuration. For every host
   this file should contain a line ``host_name slots=n`` where ``n`` is the number of
   processors on the host.



----------------------------
Input parameters
----------------------------

.. option:: -userFrags

   This option is similar to the :option:`-in` flag except that it is for
   passing pregenerated fragments rather than for passing whole molecules.
   Using this flag skips the initial cutting apart stage; fragments are passed
   directly into the conformer generation and database construction phase.
   Fragments passed using this flag will be added to the database in the order
   in which they are read (no resorting occurs).  It is important to note that
   the :option:`-in` and :option:`-userFrags` flags can be used together.

.. option:: -userUnique

   This flag allows you to specify a database you would like to
   use for duplicate removal.  The fragments in the specified database will be
   determined as unique; if the fragment is seen again in the current run,
   those fragments will be skipped rather than incorporated into the new
   database.

----------------------------
Output parameters
----------------------------

.. option:: -prefix

   This string flag determines the prefix of the ``info``, ``log``, ``report``, ``param``, and
   ``output`` files.  For example, if :option:`-prefix` is set to foo, then the
   output files will include ``foo.info``, ``foo.log``, ``foo.report``, and
   ``foo.param``.  [Default=chomp]

.. option:: -dots

   When this flag is set, the program will write a series of dots (.) to the
   terminal (:file:`stdout/cout`) to track the progress of the program.  The
   dots are written in two phases: first as the molecules are cut apart and
   organized and second as the conformers are generated and the database is
   written.  [Default=true]

----------------------------
Control parameters
----------------------------

.. option:: -smarts

   This flag specifies the built-in SMARTS pattern to use to identify bonds to break,
   or a file containing user-defined rules for identifying bonds to break.

   Legal values are ``rlf``, ``recap``, ``both`` (both ``rlf`` and ``recap``), ``all``, or a filename containing user-defined rules.

   Please see :ref:`CHOMP Theory<chapter_brood_theory>` for a more detailed description.

.. option:: -capAttach

   When a fragment is generated with multiple attachment points, this flag
   controls whether all the related fragments can be generated by capping
   one or more of the attachment points with a hydrogen.  This can generate
   many more fragments, but is quite efficient. [Default=true]

.. option:: -flipper

   This flag controls whether the flipper algorithm is used to generate the 2^N
   specific isomers by enumerating the stereo on unspecified stereocenters.
   The flipper flag takes an integer indicating the N in the 2^N isomers that
   can be generated from N stereocenters.  If the stereocenters in the molecule
   exceed N, then 2^N random unique isomers are sampled from the available
   isomers. By default, no more than 32 isomers will be generated from any
   molecule.  [Default=5]

.. option:: -forceFlip

   The :option:`-forceFlip` flag causes all stereocenters in a ligand to be
   enumerated, even if they had specified stereo on the input structure.  While
   this can generate fragments that are not specifically represented in the
   input molecules, it is also a means of exploring more of the chemical fragment
   space. [Default=false]

.. option:: -flipN

   This flag controls whether or not nitrogen atoms with potential
   stereochemistry are enumerated. Some nitrogens atoms have real
   stereochemistry, while most others are easily invertible in solution.  In
   fragment replacement, specific invertible static nitrogen structures are
   often being compared to carbon-based structures that are not invertible.  It
   can therefore be useful to enumerate the nitrogen structures in the database
   even though they are interconvertible in solution.  For this reason, the
   flag here controls whether or not nitrogen atoms with potential
   stereochemistry are enumerated.  [Default=true]

.. option:: -omega

   This flag controls whether the conformer generation using the **OMEGA**
   conformers is applied to the fragments.  This flag has two important
   repercussions.  First, by turning it off, the process can be stopped after
   the relatively quick fragmentation phase.  This allows users to examine the
   fragments that are automatically written to an intermediate SMILES file
   before paying the high cost of generating conformers.  Second, you can
   choose to replace the **OMEGA** algorithm with sampling conformers from known
   structures using the :option:`-readConfs` flag.

.. option:: -readConfs

   This flag allows users to specify a 3D structure file from which the
   database generation algorithm will sample conformers.  For each fragment
   generated in the cutting algorithm, all examples of the fragment's
   conformers that are present in the molecule file specified by this flag will
   be added as conformers and saved in the **BROOD** database.  Identical
   conformers are recognized and duplicates are removed.  If you have access
   to a large database of small-molecule crystal structures, this flag can be
   used to sample conformers from that database rather than using the **OMEGA**
   algorithm.

   .. note::

      The input molecules used to generate the fragments (from the
      :option:`-in` or :option:`-userFrags` flags) do not need to be the
      same as the input molecules specified with this flag.

.. option:: -primaryFrag

   This flag indicates that **CHOMP** should only process the smallest possible
   fragments with the given fragmentation pattern.  It is primarily for
   fragmentation applications unrelated to **BROOD**.

.. _fragment_selection_params:

-----------------------------
Fragment selection parameters
-----------------------------

.. option:: -filter

   This is a complex flag that specifies both whether the default filter
   should be applied to the fragments with the values (True and False).
   The :option:`-filter` flag can also be used to specify a filter
   file describing a non-default filter to be used to filter the fragments.
   For additional information on filtering, please see the documentation for the
   filter product.

.. option:: -minFrequency

   During the breaking of input molecules into fragments, the number of source
   molecules from which a fragment can be extracted is tracked.  This flag
   indicates the minimum number of source molecules that are required in order
   for the fragment to be retained.  The frequency in this case is normalized
   as a percentile where 99 indicates the most common fragments and 0 indicates
   the least common fragments.  By default, all fragments are retained. [Default=0]

.. option:: -maxDegree
.. option:: -minDegree

   The :option:`-minDegree` and :option:`-maxDegree` flags specify the range of 
   acceptable attachment points for fragments generated by **CHOMP**. The :option:`-maxDegree` can not be more than 3
   to produce a compatible fragment with the **BROOD** app. [Default=1,3]

.. option:: -maxMolWt

   This is a simple flag that allows the user to specify the maximum molecular
   weight of any fragment generated by **CHOMP**. [Default=350.0]

.. option:: -maxHvy
.. option:: -minHvy

   These flags specify the range of heavy atoms allowed in fragments generated by the **CHOMP** algorithm.
   [Default=0,15]

.. option:: -maxChiral

   This flag allows you to specify the maximum number of chiral centers (both
   atom and bond centers) in a fragment.  While there are many drugs and
   other useful molecules with a large number of stereocenters, they are often
   added for a specific purpose and should not be suggested lightly in a design
   setting.  For this reason, fragments with many chiral centers may be
   undesirable in some databases.  This flag allows the user to efficiently
   eliminate these fragments. [Default=3]


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


..  program:: brooddbmerge

.. _brooddbmerge:

*********************************
BroodDBMerge
*********************************

=================================
Overview
=================================

The **BROOD** distribution includes a utility, **BroodDBMerge**, that allows users to
create a single database by merging two databases, such as BROOD's default
database and their own corporate database.  **BroodDBMerge** accomplishes this task
using three required parameters: :option:`-in1`, :option:`-in2` and
:option:`-out`.  This allows combining two databases in the directories
specified by the two *in* options and writing a new database to the directory
specified by the :option:`-out` flag.  By default, **BroodDBMerge** will not
overwrite a database.

**BROOD** databases are complex structures with many precalculated parameters and
indices organized into multiple binary files for fast access of multiple
fragments in an efficient manner.  Because of this complex structure, it is not
possible to simply string two database files together in order to merge
databases.  Instead, **BroodDBMerge** reorganized the molecular fragments and
recalculates the database indexes. 

By default **BroodDBMerge** removes duplicate fragments from the new database (see
:option:`-removeDuplicates`).  When **BroodDBMerge** identifies a unique
fragment, it is written to the new database.  If a second copy of a fragment is
identified, it is discarded.  The database passed in using the :option:`-in1`
parameter takes precedence in duplicate removal Duplicate fragments in the
database specified by :option:`-in2` will be discarded.  In addition, if a
fragment appears twice in either database, the later instance will be
discarded.  The user can use the database input order to control which
duplicate fragments will be present in the final database.

=================================
Command Line Help
=================================

A description of the command line interface can be obtained by executing **BroodDBMerge**
with the `--help` option.

.. code-block:: console
   
   > brooddbmerge --help

will generate the following output:

::

   Help functions:
     brooddbmerge --help simple      : Get a list of simple parameters
     brooddbmerge --help all         : Get a complete list of parameters
     brooddbmerge --help defaults    : List the defaults for all parameters
     brooddbmerge --help <parameter> : Get detailed help on a parameter
     brooddbmerge --help html        : Create an html help file for this program
     brooddbmerge --help versions    : List the toolkits and versions used in the application

=================================
Example Commands
=================================

This section has a brief series of examples of **BroodDBMerge** command-line
executions.  Each example is followed by a brief description of its behavior.

.. code-block:: bash

   prompt> brooddbmerge -in1 dbA -in2 dbB -out dbAB

This is the most basic merge of the two databases dbA and dbB into the new
database dbAB.  By default, the new database dbAB will not contain any
duplicate fragments, but will contain all of the unique fragments that were
present in either dbA or dbB.

.. code-block:: bash

   prompt> brooddbmerge -in1 dbA -in2 dbB -out dbB

In this execution, it is most likely the user accidentally used :file:`dbB` for
the output.  Rather than allow this typo to accidentally erase or corrupt the
:file:`dbB` database, the execution will stop.  This behavior can be overridden with the
:option:`-overwrite` flag.

.. code-block:: bash

   prompt> brooddbmerge -in1 dbA -in2 dbB -out dbAB -removeDuplicates false

This execution of **BroodDBMerge** will not include duplicate removal.  All of the
fragments that are in :file:`dbA` and :file:`dbB` will occur in :file:`dbAB` no
matter how many times any fragment may appear in either or both databases.
When **BROOD** searches the resulting database, each instance will be treated
separately.

============================
Required Parameters
============================

.. option:: -in1 (-i1)

   This option is for loading the first **BROOD** database.  The value passed with
   the flag should point at the directory of the database rather than any files
   inside the database.

.. option:: -in2 (-i2)

   This option is for loading the second **BROOD** database to be merged with the
   database specified by the :option:`-in1` flag.  

.. option:: -out (-o)

   This option indicates the new database to create based on merging the
   databases specified by the :option:`-in1` and :option:`-in2` flags.  By
   default **BroodDBMerge** will require you to specify a new directory for the new
   database (see :option:`-overwrite` for details).

============================
Optional Parameters
============================

.. option:: -verbose (-v)

   This flag controls the amount of output generated by the program.  By
   default, all essential information is presented in a summary.  When the flag
   is set, a large amount of detailed information is also written to stdout.
   [Default=false]

.. option:: -overwrite (-over)

   By default, **BroodDBMerge** will only write a new database (it will not
   overwrite another file or directory).  Brood databases can be quite
   expensive to generate; to avoid accidental erasure of databases **BroodDBMerge**
   will not overwrite a previous database.  If you *want* to overwrite a
   database, you can set the :option:`-overwrite` flag. [Default=false]

.. option:: -removeDuplicates (-duplicates)

   When merging two databases, users can choose whether to remove duplicates.
   By default, any fragment that is present more than once in the combined
   databases will only be written one time.  No fragment-level merging occurs;
   only the first instance of a fragment is written.  [Default=true]



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _brood_tutorials:

.. program:: chomp

===========================
Overview
===========================

The **BROOD** product contains four applications as well as a script that can be
run in conjunction with OpenEye's molecular visualizer **VIDA**.  Two of the
programs, **vBROOD** and **BROOD**, and the **VIDA** script provide the ability to generate
queries, search for similar fragments and visualize and triage the resulting
analogs.  The additional pair of applications, **CHOMP** and **BroodDBMerge**, are
utilities that generate and merge **BROOD** fragment databases, respectively.

In these tutorials, we will primarily focus on generating and exploring
analogs of an input molecule or molecules.

The basic workflow for **BROOD** is:

#. Build a query fragment from an input molecule.
#. Search for database fragments that are similar to the query fragment.
#. Examine the analog molecules built from putting the similar fragments into the initial molecule.

=====================================
Human Complement C3a Receptor Example
=====================================

This example follows some of the work on Human Complement C3a Receptor (C3aR) from Reid and coworkers [Reid-2014]_. C3aR is a G-protein coupled receptor important for human inflammatory processes and has been identified as a potential drug target for several inflammatory diseases.  In their work, Reid replaced a bridging ether with a heterocycle to convert a known antagonist compound into a potent and selective agonist for Human C3aR.  In this example, we will design analogs to the known compound. The results will include several compounds studied by Reid.

Specifying the Database
=======================

Open **vBROOD** by double-clicking the icon or typing **vBROOD** at a command prompt. The GUI will start, displaying the information screen and the five primary task buttons (*Build and Run*, *Build a new query*, *Run BROOD*, *Filtering*, and *View Results*).

* The first time you open **vBROOD**, you need to specify a default database. If you have not already done so, download the default database or build your own database and specify it.

  + For this example, be sure to specify the default **BROOD** database.
  + If you do not have the **BROOD** database available locally, you need to download it from the
    OpenEye `Download Page <http://www.eyesopen.com/downloads/>`_ (select your platform and then
    the product BROOD).
  + For help with installing a **BROOD** database, see :ref:`Database Installation<defaultDatabase>`.
  + To specify a database, select *Edit Preferences* under the *Edit* menu and type the name of
    the database you want to use in the first line of the pop-up preferences dialog. Alternatively, click
    the *Browse* button to navigate to the database.

* If you have previously specified the database, you will not need to do this again unless you want to change the database.

.. note::

   The **BROOD** database is a directory. After the default **BROOD** database has been downloaded, you need to
   unpack it and select the new directory.  We do not recommend renaming the **BROOD** database, since you must then
   rename all the files contained within it.  Consistency is required to prevent confusion between the name of the database
   and the files being searched under that name.

Loading a Molecule
==================

Of the five primary tasks, the one most commonly used is *Build and Run*. This brings you to a five-step GUI wizard that
takes you through building and editing a query, selecting an optional property filter, selecting parameters for the **BROOD** search, and visualizing the results.

#. Begin by clicking the *Build and Run* button, which launches the *Load Molecule* interface.

#. Load the molecule ``c3a-4.sdf`` by clicking on the small folder icon in the molecule entry space, then navigate to the
   **BROOD** directory of the **OpenEye-applications** data installation and load the file ``c3a-4.sdf``.

   a. On the right, the c3a compound 4 is displayed in a 2D image and is highlighted to suggest several
      fragments for possible replacement.
   b. On the left, the current molecular property table is now filled to reflect the properties of the
      molecule. These calculated properties can be used as a guide to consider some of the things that
      might need to be changed in the loaded molecule.

.. note:: The c3a compound **4** has appropriate aqueous formal charges. **BROOD** retains the state of the molecule as it is in the input file, so your query molecule *must* be in the charge and tautomer state you desire before loading it into **BROOD**.

3. Multiple fragments can be selected by shift-clicking. In this case, though, we will simply lasso the fragment we want to
   select. Hold down the Left button on your mouse and circle the fragment of the molecule shown in the image below. The
   lassoed fragment will then be highlighted (Figure 1).

.. _tutorial_c3a_1.png:

..   figure:: /_images/tutorial_c3a_1.png
     :width: 85%
     :align: center
     :alt: Loaded c3a-4

     **Figure 1.** Selecting a query fragment.

.. note:: When **BROOD** is run, the selected fragment will be replaced by fragments from the database with similar shape and chemistry.

4. After the fragment is selected, click the *Next* button to move on to query editing.

.. note:: In general, if the molecule you loaded in this step has 3D coordinates, **BROOD** will use them and will replace
   the fragment in place.  This allows fragment replacement to work in an active site.  If the loaded molecule has only 2D
   coordinates, then a single low-energy conformer will be generated for the ligand using the **OMEGA** algorithm.

Editing the Query
=================

As the wizard moves to the second stage, the fragment is extracted from the whole molecule and is displayed along with the
color atoms generated from the input structure. This interface is designed to help users inspect and edit either the shape or color
(i.e., chemistry) atoms of the query.  Initially, the three heavy-atom, two attachment-point query will appear annotated with
an acceptor color atom. In this example, Reid and coworkers discovered that this acceptor moiety is extremely important.
Emphasis to the color force field at this point will be added as well as a constraint.

.. note:: For additional information about the theory of shape and color force fields, please see the :ref:`Shape TK <shapetk_theory>`
   or :ref:`ROCS Application <rocs_theory>` theory sections.

The toolbar with query editing tools is located on the left-hand side of the 3D window. Hovering over each icon gives a brief description.

The first step is to increase the score for replacement fragments that match the constraint.

  #. Select the *Color Editing* tool (second icon).

  #. Click on the small arrow next to the icon and choose *Add Acceptor*. This prepares the *Selection* tool for adding color atoms.

  #. Click on the current acceptor atom, thus adding a second color atom. The annotation on the 3D window should now read "acceptor x2"
     to reflect the change.  This means that the color potential is doubly weighted in this position.

Second, a constraint must be added that requires all analogs identified by **BROOD** to include an acceptor near this position.

  #. Select the *Constraint* tool (third icon).

  #. Click on the small arrow next to the icon and choose *Add Acceptor Constraint*. This prepares the *Selection* tool to add a constraint.

  #. Now click on the same acceptor atom we chose above. A dashed circle will appear around the atom, annotating the newly added
     constraint. The query should now look similar to Figure 2 below.

.. _tutorial_c3a_2.png:

.. figure:: /_images/tutorial_c3a_2.png
   :width: 85 %
   :align: center
   :alt: Edited c3a-4

   **Figure 2.** Color and constraint on a query fragment.

Third, click *Next* to move to the next step in the wizard.

Selecting Properties
====================

This interface allows **BROOD** to filter the output by the properties of constructed molecules with replacement fragments.
For example, **BROOD** filters by simple rule-of-five, predicted bioavailability, and complexity. Any constructed molecules that
fail to meet these property filters will not appear in the output.  In all cases, the property filters consider the properties of the whole molecule (rather than only the fragment).

For this example, we will leave property filtering turned off. Click *Next* to move to the *Setup* stage in the wizard.

.. note:: There is a button for saving the query at this stage. In all cases, a copy of the query is written into the working
   directory when **BROOD** is run. This button is for saving another copy of the query or for saving a query when you don't
   want to follow through and set up a **BROOD** run. Saving at this point is for convenience only and not necessary.

Using the Property Filter (Optional)
------------------------------------
At some point, you may want to use the property filter.

#. While still on the *Selecting Properties* step, check the *Property Filter* checkbox.

#. Choose a default *Drug-like* filter or a filter that was built earlier.

Setting Up the BROOD Search
===========================

The *Set Up BROOD* step has many options. Hovering over the options will reveal tooltips describing them. For this tutorial:

#. Select an *Output Prefix*.  All output files will have this text pre-appended to their filenames.  If the prefix has been used
   previously in the same directory, **BROOD** will automatically increment a trailing integer. If there is a danger of overwriting
   the previous output, the prefix will appear in red text.

#. Select an *Output Directory*. All output files will be written to this directory.
#. If you are running on a machine with more than two processors, click the multiprocessor box and set the number of processors.

   .. note:: In general, **BROOD**'s speed scales by N-1, where N is the number of processors.

#. You should also verify that:

   a. The database you selected earlier in this tutorial appears in the *Database* setting.

   b. *Shape & Color* is selected under *Search Options*.  This is the default, but if you changed it in a previous run, the GUI will remember that value.

   c. *Any Size Ring* is selected under *Ring Requirements*. This is the default, but if you changed it in a previous run, the GUI will remember that
      value. Setting the option to *Any Size Ring* requires that all substituted fragments have at least two ring atoms on the shortest path
      between the attachment points, thus providing a conformationally constrained replacement fragment.

   d. The annotated query fragment in the 3D window is the query you intend.

#. Click *Run* to start the search.

Opening and Viewing Results
===========================

As **BROOD** searches, the GUI writes log information to the window's lower portion and continuously updates the status information in
the upper left.  The lower right corner of the GUI displays a graphical progress bar. The search in this tutorial takes a few minutes
to complete and results in 60 analog molecules in three clusters. At intermediate intervals, the current hit list of identified fragments
is displayed in **vBROOD**'s 2D depiction area. A discrete progress bar in the lower right of the GUI also shows the progress.
When the job is complete, the bottom half of the screen displays results in a spreadsheet while the upper-right portion gives a preliminary
view of the 2D analogs (Figure 3 below).

.. _tutorial_c3a_3.png:

.. figure:: /_images/tutorial_c3a_3.png
   :width: 85 %
   :align: center
   :alt: c3a-4 search results

   **Figure 3.** Search results.

Once the run is complete, **vBROOD** automatically passes the search results to **VIDA** with a script that allows
convenient viewing of the **BROOD** results. This **VIDA** interface is simplified and specialized for viewing **BROOD** results.

Click *Open in VIDA* for further exploration and triage of the results.

Exploring the Results
=====================

**BROOD** results are organized into clusters; the interface is designed to help users explore these clusters. Along the way, you
can identify analog molecules of particular interest and save them to a *Favorites* list that can be saved as a separate hit list.
This portion of the tutorial explains how to navigate through the clusters, add molecules to your *Favorites* list, and save the *Favorites* list as a new molecule file.

Keyboard Shortcuts for Navigating BROOD Results
------------------------------------------------

When you first open the **BROOD** *Results Viewer*, the keyboard shortcuts are immediately displayed (Figure 4). For this tutorial,
we will use the Left, Right, Up, and Down Arrow keys as well as the Q, F, and Delete keys.

.. _tutorial_c3a_5.png:

.. figure:: /_images/tutorial_c3a_5.png
   :width: 50 %
   :alt: c3a-4 search results
   :align: center

   **Figure 4.** Keyboard shortcuts.

Dismiss the keyboard shortcuts window. It can be redisplayed by clicking the *Hotkey Help* button on the left.

If this is your first time using the **BROOD** *Results Viewer*, you will see the results of the search in four 3D panes as well as a
navigation and information pane on the left.  The upper-left 3D Viewer pane always contains the query molecule with the replaced fragment
highlighted in green and the constant part shaded in deep maroon.

The remaining panes each contain a cluster head of the three clusters identified in this query. By default, the new analog molecules are overlaid with a wireframe version of the query.

* Rotate and zoom the panes to examine some of the analogs.  The panes will automatically be centered on the replaced fragment.

* Use the Q hotkey to toggle the wireframe query overlay on and off.

BROOD Results in the Results Viewer
-----------------------------------

The results of a **BROOD** search are automatically organized into clusters based on the similarity of their molecular framework.
Particular attention is given to rings and aromaticity while different chemistries are allowed to be grouped. The Arrow keys can be used
to explore the results for this search. Clusters found by **BROOD** are not hierarchical; instead, they are a series of collections, each
represented by the compound from the cluster that receives the best **BROOD** score (Figure 5).

A look at the information pane of the **BROOD** *Results Viewer* shows the total number of clusters (three in the case of this tutorial).
In addition, two tumblers identify the molecules that are currently visible.  The left tumbler represents the cluster being viewed.
When the blue highlight is on the left tumbler, the 3D panes are showing the cluster representatives. The Up and Down Arrow keys
toggle through the cluster heads, with the selected cluster head highlighted in blue; and the matching blue square around the selected
cluster representative in the 3D window will also change.  If there are more than three clusters, the Up and Down Arrow keys will also
handle scrolling through the all the cluster representatives.

.. _tutorial_c3a_4.png:

.. figure:: /_images/tutorial_c3a_4.png
   :width: 85 %
   :align: center
   :alt: c3a-4 search results

   **Figure 5.** Exploring clusters in the BROOD results.

#. Click the Down Arrow key.  Note that the left tumbler changes from highlighting "1" to highlighting "2" and that the blue
   highlight box in the 3D window moves from highlighting the first cluster representative to highlighting the second representative.
   If you want to see all the members of a cluster, you can drill down into a cluster to see all of its members. In this section, we
   will explore navigation through Cluster 2 using the Arrow keys.

#. Use the Up and Down Arrows to select the representative molecule of Cluster 2.  Note that it is labeled with "Cluster 2, 1 of 30,"
   indicating that it is the first molecule in a cluster with 30 total members.

#. Press the Right Arrow key to expand Cluster 2.  Notice that in the top-left pane, the blue highlight has moved onto the right tumbler,
   indicating that you are now viewing cluster members.  It is highlighting "1," indicating that the highlighted molecule in the 3D window
   (the one surrounded by the blue box) is the first molecule in the cluster.

#. Use the Up and Down Arrows to move through the cluster members.  By default, six panes will be visible and the Arrow keys will cause the
   molecules to scroll through the panes one by one.  Look through some of the molecules in Cluster 2 using the Arrow keys. To toggle the
   number of molecules displayed, use the V hotkey.

   .. note:: The Page Up and Page Down keys can be used for more efficient navigation.  If multiple panes are visible, Page Up and Page Down will change all the visible molecules at one time.  This navigation is analogous to the Up and Down Arrow keys, but more efficient.

#. Use the Page Up and Page Down keys to move through the cluster members.

#. The Home and End keys will navigate to the first page or the last page of the cluster of molecules you are currently examining.
   Use the Home and End keys to navigate to the beginning and end of Cluster 2.

The Up Arrow, Down Arrow, Page Up, Page Down, Home, and End keys are all available for navigation throughout all the cluster representatives
in the same way they were for navigating the molecules inside Cluster 2.

Working with Favorites in the BROOD Results Viewer
--------------------------------------------------

When examining **BROOD** hit lists, some users like to select particular molecules for future sharing or examination by saving them into
a separate culled list.  To facilitate this, the **BROOD** *Results Viewer* includes *Favorites* and *Trash* features.  While navigating
the analogs as discussed in the previous section, you can choose any molecule and move it to your Favorites.  In addition, if you identify
molecules you would prefer not to examine again, you can move them to the *Trash*.  Both the *Favorites* and the *Trash* can be opened if you inadvertently placed a molecule in the wrong category.

#. Using the navigation skills developed previously, choose a molecule in Cluster 2.  To save it to your *Favorites* list, first select it
   by navigating until the blue box is highlighting the molecule (this can also be done by clicking on the molecule).  Once highlighted,
   you can add it to your *Favorites* list either by using the F hotkey or by clicking the *Add* button under the *Favorites* menu. Select several more molecules and add them to your *Favorites* list.

#. To examine your current *Favorites* list, click the *Favorites* button in the navigation pane. The 3D window will then display the molecules
   you've added to your *Favorites* list.  Navigate to your least favorite
   molecule in the *Favorites* list and press the Remove button.  This action removes the molecule from the *Favorites* list and puts
   it back into its original position in the *Results* cluster.

#. When your list of favorite molecules is complete, you can save it to share with colleagues or for later examination.  Click the
   *Save* button under the *Favorites* pane and a *File-Save* dialog will open.  The default file format will be OpenEye Binary, although
   a variety of other file formats are also available.  The query molecule will be saved in your *Favorites* list. If you have any proteins,
   color annotations, or property annotations, they will also be saved in your hit list.  The data saved in your hit list is only limited by the
   file format you select.  While OEB is preferred, SDF can also save much of the information.

In addition to keeping track of your favorite analogs, it can also be useful to get rid of some of the less desirable molecules.  For this purpose,
there is a garbage can that allows you to place molecules in the *Trash*.

#. Using the navigation skills developed previously in this tutorial, navigate to a molecule in Cluster 1 that is not useful.  When the
   blue highlight box is around the molecule, hit the Delete key.  The molecule will be removed from the list and the remaining molecules will be
   renumbered.  For example, if you highlight and delete cluster member 15 (labeled "15 of 54"), it will be moved to the *Trash* and the molecules
   formerly labeled "16 of 54" to "54 of 54", will now be relabeled "15 of 53" through "53 of 53".

#. If you inadvertently put a desirable molecule in the *Trash*, you can open the trash can using the *Trash* button in the
   *Visualization* pane of the *Results Viewer*.  When you click this button, the 3D view will
   change to display the molecules in the trash.  These molecules can be navigated as described above, and can be returned to their original
   place in **BROOD**'s *Results* clusters by highlighting them and then clicking the *Recover* button under the *Trash* pane on the left panel.

=========================
Fragment Joining Tutorial
=========================

In the fragment-based design setting, users may occasionally want to link two fragments with crystal orientations in the active
site into a single molecule.  Ideally, when the two fragments are linked without additional entropy, the binding energies can simply be added.
In practice, this kind of additivity is often not possible for a number of reasons, including ligand strain, protein strain, entropy,
and desolvation.  Nevertheless, **BROOD** can be quite useful in this setting to suggest potential linker groups that might span
the fragment–fragment gap in a low energy manner.  This tutorial walks you through the steps for identifying linker fragments.

This tutorial follows the work of Ward et al. [Ward-2012]_, in which they designed linkers to join two crystallographic fragments to generate a lead.

BROOD Database
==============

If you have not yet installed the **BROOD** database, please see the :ref:`Database Installation<defaultDatabase>` section for further information before continuing this tutorial.

Loading Two Molecules
=====================

For this exercise, we will take two fragments positioned in the same active site and join them with an unstrained linker.

#. Open vBROOD and select *Build and Run* from the primary window.

#. Click on the small down arrow in the *Molecule* input box.

#. From the pop-up menu, choose *Open Fragments for Bridging*.  This will open a two file dialog.

#. Choose two separate fragment files using the appropriate function for your operating system.
   For this tutorial, select the files ``ward-22-21.oeb`` and ``ward-21-22.oeb`` from the ``brood``
   directory in :ref:`examples_data_loc`.

When the files are properly loaded, the 2D window should display them as shown in Figure 6 below.

.. _tutorial_join_1.png:

.. figure:: /_images/tutorial_join_1.png
   :width: 75 %
   :align: center
   :alt: two fragment depiction

   **Figure 6.** Two molecules loaded for query selection.

Loading the Protein
===================

In any **BROOD** run, whether fragment replacement or fragment joining, a
:ref:`protein context<clash_detection_selectivity>` can be added.  When the
query molecule or molecules are from a protein active site and the protein is
passed to **BROOD**, the new analogs will be constructed in the context of the
protein active site.  Before the final hit list is generated, all the new
analogs will be tested for clashes against the protein.

#. After the two fragments are loaded, locate the *Protein* input box.

#. Click the folder icon to open an input dialog.

#. Select the file ``ward-protein-join.oedu``.  This will allow you to include the
   protein in the search and build joined fragment molecules in the active site of the protein.

Choosing a Query
================

When the two files are loaded, depictions of two separate molecules will appear in the 2D query window.  As with a single query,
the fragments for replacement can be lassoed, one from each molecule in this case (Figure 7).

.. _tutorial_join_2.png:

.. figure:: /_images/tutorial_join_2.png
   :width: 85 %
   :align: center
   :alt: selecting a join query

   **Figure 7.** Choosing a query to join two molecules.

#. Use your mouse to lasso the parahydroxyl and the terminal urea in a single circle.  It doesn't matter that the fragments are not close to each other.

#. Click *Next* to move to the 3D window.

#. Since you loaded a protein in the previous query selection stage, there is now a *Show Protein* button beneath the window that allows you to toggle the visibility of the protein on and off.  Try this now.  Having no visible protein makes it much easier to work with the query fragments.  On the other hand, being able to see the protein and how the current ligands interact with it can be quite helpful in designing a query.  For this exercise, turn off protein visibility.

#. Select the *Eraser* icon and delete all the color atoms by clicking them.  This will allow **BROOD** to bridge the two fragments independent of the influence of the terminal urea chemistry.

#. Now delete all the heavy atoms except for the pink attachment atoms and the oxygen and nitrogen atoms bonded to the attachment atoms.  This will allow **BROOD** to bridge the two fragments independent of the influence of the shape of the terminal urea.  In the end, you will have a minimal query required **BROOD** to carry out an unguided search (Figure 8).

.. _tutorial_join_3.png:

.. figure:: /_images/tutorial_join_3.png
   :width: 85 %
   :align: center
   :alt: edited 3D query

   **Figure 8.** Minimal query for molecule joining.

Setting up a Search
===================

#. Click *Next* to move to the filter pane, then click *Next* again to move to the **BROOD** *Run Setup* window.

#. If you have a multiprocessor machine, click the *Multiprocessor* check box under *General Options* and select the maximum number of processors.

.. note:: **BROOD** can use from 1 to N+1 processors, where N is the number of logical cores detected on the machine.  On many desktop systems, the OS remains responsive even with all the processors engaged by **BROOD**.  Users should explore performance on their own systems.

3. Under *Search Options*, select the *Link Geometry* search type.  This will carry out a CAVEAT-like search [Lauri-1994]_ that attempts to span the empty region between the two fragments.

4. Try this example with the *Quick Search* option (see below). Later you can also run without the *Quick Search* option to compare the calculation time and quality of results.

5. Next, consider ring selection in the search.  By default, **BROOD** requires a ring in the atom path connecting every two attachment hit.  For this exercise, under the *Ring Requirements* section, select the "Zero Rings" option.  This will require that fewer than two ring atoms are located on the shortest atom-path connecting the fragments in each **BROOD** hit.

6. Finally, when a protein is included in a search (as in this case), all solutions are checked for bumps with the protein using a 2.25 Å cutoff by default.  For this example, adjust the cutoff to 1.7 Å.  To do this, click the *Advanced Search* tab and adjust the number labeled "Protein-ligand bump radius" to 1.7.

7. Now click *Run*.  The view will switch to the *Results Tracking* view while the job is running.  When the run is complete, the results will be viewable in the **vBROOD** GUI and in the **BROOD** *Results Viewer*.  Navigation and exploration of those results work similarly to those in the first tutorial.  If you are not familiar with results navigation, it may be useful to review the first tutorial.  Here, special attention will be paid to features that are different in this tutorial.

Examining the Log Files
=======================

When the **BROOD** run is complete, click the *Log* button on the lower right of the **vBROOD** *Results* window.  You can read the logging information to learn details about the number of molecules that were processed, how many were overlaid, how large the initial hit list was, and the reason that any molecules were eliminated from the hit list.

When running a standard search, the *Results* page shows every fragment that was overlaid and the hit list of those that passed all requirements.  For this example, about 45,000 fragments were overlaid and a hit list of 300 was retained.

.. note:: The *Quick Search* function's  goal is to complete its search in approximately two minutes.  To accomplish this, the hit list is truncated up to the first 50 cluster representatives.  Further, each cluster is represented only by its best scoring molecule.  The *Quick Search* results are often interesting and contain a few attractive ideas.  *Quick Search* allows users to assess whether a more time-consuming search is likely to be fruitful.

Viewing Results in a Protein Site
==================================

Now examine the results in 3D by clicking the *Open in VIDA* button.  As in the previous example, this opens the **BROOD**
*Results Viewing* script and automatically loads the results with the modified interface.  As before, the results are organized
by cluster and displayed in the context of the query.  When you examine the *Quick Search* results, each cluster will have at
most one member, so navigation is simple.

* Because we loaded a protein as part of the query, the protein structure is also available in the *Results Viewer*.  Using
  the A hotkey or the *Lock Protein* check box in the visualization panel, the protein display can be turned on and off.
  When the protein is turned on, the protein residues near the query molecule are displayed.

* When the protein is visible, hydrogen bonds between the protein and the ligand annotations can be added and removed using the E
  hotkey or the *Show Hydrogen Bonds* check box.  This works best if the query is not locked (use the Q hotkey or the *Lock Query* check box).

* When the protein is visible, a partial surface covering the area of the active site can be turned on and off using the R
  hotkey.  The surface is colored with the electrostatic potential (Figure 9).

.. _tutorial_join_4.png:

.. figure:: /_images/tutorial_join_4.png
   :width: 85 %
   :align: center
   :alt: protein results viewer

   **Figure 9.** BROOD results in an active site with surface and interactions.

The other features of the *Results Viewer* can be reviewed in the first tutorial.

=========================================================
Generating a Database with Crystallographic Conformations
=========================================================

This example demonstrates how users can create a **BROOD** database with fragment conformations pulled from small molecule
crystal structures rather than conformations generated by **OMEGA**. For this task, we will be using **CHOMP**, **BROOD**'s application for fragment database generation.

Preparing Data Sources
======================

For this exercise, **CHOMP** requires two molecular inputs.  The first input will be the molecules you want **CHOMP** to use to generate molecular fragments for the **BROOD** database.  The second input will be the 3D molecular structures **CHOMP** should use to extract example conformers for the fragments generated from the first input.  The same file can be used for both inputs; for instance, if your company has a large collection of small molecule crystal structures, you can use it to both generate the molecular fragments for the **BROOD** database and to define the allowable conformations of those fragments.

The molecular file for fragmentation can be in any supported 1D, 2D, or 3D molecular file format (including :term:`SMILES` or 2D SDF).  If the molecules include titles, these can be used in the **BROOD** *Results* to track the most common sources of each fragment.

The molecular file for crystal conformer specification must be a 3D structure file.  We recommend using SDF, MOL2, or OEB.
These formats can be exported from common crystallographic database tools (refer to their manuals for details of the process).
In our experience, the PDB format has too many ambiguities for reliable handling of 3D fragment conformations; we recommend avoiding
the use of PDB files here if possible.

For this tutorial, example files have been included in the **BROOD** installation.  For the first input, you will use the file ``biotin.ism``; for the second input, you will use the structural file ``biotin.xtal.oeb``.

.. note:: Using the same input for fragment generation and conformer specification assures that there will be a crystallographic conformation for every fragment generated by **CHOMP**.  If different files are used, then fragments may be produced that have no representative conformation in the structural data.

Generating a Database
=====================

**CHOMP** generates **BROOD** databases in two phases.  In the first phase, a unique set of fragments is extracted from the molecular input.
In the second phase, conformers are generated for each fragment, the fragments are organized to optimize **BROOD** search times, and
then the fragments are written into a database.  For this exercise, each fragment from the first phase will be searched for in the
3D molecules.  If the fragment is identified as a substructure of any 3D molecule, the coordinates will be extracted and added as a new
fragment conformer.  Finally, duplicate conformers of each fragment will be removed before the fragment and its 3D conformations are passed on for organization and database writing.

.. note:: **CHOMP** is a command line only program.  It is part of the **BROOD** product and is installed as part of the **BROOD** installation process.  **CHOMP** is not available from within the **BROOD** GUI in this release but is available in   form on all supported platforms.

#. Click on the command line menu and select **CHOMP** from the drop-down menu.

   a. At the prompt, type and execute the command line ``chomp --help all``.

   b. This should generate a list of all the command line parameters and will test whether **CHOMP** is available in your path.

   c. Please check the first few lines generated and make sure you are running the current version of **CHOMP**.

#. Change directory to the ``brood`` directory under the :ref:`examples_data_loc` of your installation.
   It should contain the files ``biotin.ism`` and ``biotin.xtal.oeb``.  You can also copy these files to another directory if you would prefer.

.. _chomp_command_line_example:

3. Execute command line: ``prompt> chomp -in biotin.ism -out crystal -readconfs biotin.xtal.oeb``.

   a. The output is a directory named ``crystal`` with 45 paired files names ``crystal.N.idx`` and ``crystal.N.db``, where N varies from 0 to 44.  It also contains two metadata files, ``crystal.all.idx`` and ``crystal.info``.

   b. Because this is a very small database, many of these files are 0 bytes in size.  Only segments 0, 1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 15, 16, 17, and 18 are used, and even these files are quite small.  Use the appropriate file system listing mechanism on your platform to confirm that these files contain information.

4. The database is now ready for searching.  There are two ways to select it for searching within **vBROOD**.

   a. To use the newly created database as the default database:

      #. Start vBROOD and select ``Edit->Edit Preferences``.

      #. A preferences dialog will open; the first item will be the database directory.

      #. Either hand edit or use the *Browse* button to locate and select your newly created database.

   b. To use the newly created database without changing the default:

      #. Start vBROOD and select the *Build and Run* button.

      #. Open the crystallographic query file ``4ggz.oeb`` and select the central aliphatic chain connecting the acid to the ring.

      #. Click *Next* to move to the *Edit Fragment* tab.

      #. Click *Next* to move to the *Select Properties* tab.

      #. Click *Next* a third time to move to the *Setup BROOD* tab.

      #. Now, the *critical step* is in the second entry, labeled *Database*. Use the *Folder* icon to select the crystal database you just created with **CHOMP**.  Selecting the database this way will not change your default database in **vBROOD**.

      #. Finally, change the *Ring Requirements* parameter to the *No Requirements* selection and click *Run BROOD*.

   c. **BROOD** will quickly execute and return a single result that is nearly identical to the input structure.  The inclusion of the unusual torsion in the distal aliphatic chain just before the carboxylate moiety is an indication that the fragment is in fact using crystallographic conformations.

Advanced Topic: Editing the Fragments at an Intermediate Step
==============================================================

There are many fragment generation and fragment filtering parameters that control the number and type of fragments generated from your input molecules by **CHOMP**.  The defaults for these parameters mimic our best practices for the general case.  If you are generating a specific database for a special case, you may want to examine the fragments generated by **CHOMP** to determine in detail if you want to modify the default parameters.  This section of the tutorial explains how to make this part of the database preparation workflow.

The following steps will quickly lead you to an intermediate *Results* file containing all the fragments generated for your database.  Since this phase is typically significantly faster than full database generation, you can repeat it, adjusting the parameters until you are satisfied.  Alternatively, you can hand edit the intermediate file using your own criteria and then pass it into the final 3D database generation phase when you are satisfied with the results.

* Consider the :ref:`command line used above<chomp_command_line_example>` but without the 3D molecule file with the :option:`-readConfs` flag. Without the :option:`-readConfs` flag, by default, OMEGA conformations will be used.  Turn off this option by passing False to the :option:`-omega` parameter.

Whenever **CHOMP** is executed (regardless of 3D options), an intermediate file is generated that contains all the fragments generated from the input molecules.  With both of these options for conformations turned off, **CHOMP** will generate the fragment file and then stop.

#. In the command line described above, use the output designation crystal with the :option:`-out` flag.  The intermediate file will be called ``crystal.ism``.

   a. ``prompt> chomp -in biotin.ism -omega false -out crystal``
   b. The output file ``crystal.ism`` includes 18 fragments numbered one to 18.

#. This file contains the output fragments along with a complex molecular title.  The title includes information about the source molecules for the fragment and can be disregarded for this exercise.

#. Load this fragment file into your preferred molecular viewer, noting that it may contain a very large number of fragments.  By examining the fragments, you can determine if they fit your preferences.

#. Rerun the command line, using the flag :option:`-maxHvy` 8 and change the output to avoid overwriting the previous output (:option:`-out` crystal2).  Now you can compare the output of the ``crystal.ism`` and ``crystal2.ism`` files to see the effects of this parameter change.

   a. ``prompt> chomp -in biotin.ism -omega false -out crystal2 -maxHvy 8``
   b. Examining the output file ``crystal2.ism`` reveals that only 13 fragments are present: the five that are larger than eight heavy atoms have been removed.

In addition to modifying the *Fragment Selection* parameters, as with :option:`-maxHvy` above, the :option:`-smarts` parameter can have a powerful effect on the fragments that are generated by **CHOMP**.  This can be an effective tool regardless of whether the 3D conformers for your database are being extracted from crystallographic conformations or generated by **OMEGA**.



Theory
======

.. toctree::
   :maxdepth: 3

   brood_theory
   brood_app_howto
   chomp_app_howto


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*



.. _chapter_brood_theory:

Theory
======

There is a long history to fragment and bioisosteric replacement (see [Chen-2003]_).  Most
medicinal chemists are well versed in standard sets of bioisosteric fragments.
Likewise, there is a long history of computational approaches to fragment replacement
(see [Verloop-1987]_ and [Lauri-1994]_).  There have been several attempts to examine
sets of known active compounds to empirically identify bioisosteric fragments
(see [Ujváry-2003]_ and [Sheridan-2002]_).  While this is an interesting exercise, it has
two drawbacks.  First, it can only identify bioisosteric fragment pairs that
are already known.  While these provide interesting study, they are often already
familiar to experienced medicinal chemists and modelers.  Second, it identifies
many incidental rather than meaningful fragment pairs.  These result from the
fact that simply because two molecules bind to the same site does not mean they
differ only by bioisosteric replacement.  For instance, chemists may analog a
compound by substituting an N-methyl group with an N-benzyl group in order to
identify new binding pockets.  However, just because both of these compounds
are bioactive does not mean that methyl and benzyl are similar fragments (though
they would be identified as such by some methods).  While one may apply various
heuristics, such as size, to avoid this problem, we hope to explore methods
that are more robust.

An alternative approach has been to use an algorithm that would predict whether
two fragments are similar in relevant ways.  Several groups including Bartlett, Verloop, and Willett
(see [Lauri-1994]_, [Verloop-1987]_, and [Watson-2001]_) have developed methods in
this area.  Here we seek to capitalize on and extend the ideas developed by
these workers.

=================================
3D Fragment similarity searching
=================================

**BROOD** allows users to enter a single query fragment and
search a very large database of known molecular fragments in order to identify
fragments that are similar.  Each database fragment is compared to the query
fragment in 3D with regard to shape, chemistry, electrostatics, and geometric
presentation of attachment vectors.  The fragments that are most similar to
the query fragment will appear in a hitlist.

All similar fragments in a **BROOD** hitlist are organized into clusters.  The
clusters are organized so that molecules with the same ring structures and core
framework (reduced-graph) are placed in the same cluster.  The first cluster in
**BROOD** hitlists is always the molecules that are similar to the query, sharing
the same core atomic framework.  While some of these analogs may be obvious,
they often include alternative interesting chemistries.  The remaining clusters
are each organized around a unique core atomic framework.  Each cluster is
represented by its best scoring member and the clusters themselves are ranked
by the score of their best member.

.. _clash_detection_selectivity:

=================================
Clash detection and selectivity
=================================

**BROOD** allows users to specify protein structures for the purpose of testing
whether newly constructed analogs fit into the active site.  When the **BROOD**
query ligand is based upon a crystallographic co-crystal structure, **BROOD**
builds the newly created analog molecules in the same shape and orientation as
the query.  If the crystallographic ligand was originally in an active site and
the protein is passed to **BROOD** as the bump protein, the new analogs will be
built in poses that are also in the bump protein's active site.  When a bump
protein is passed, **BROOD** checks for clashes between the bump protein and each
analog.  By default, if any ligand heavy atom is less than 2.25 Angstroms from
a protein heavy atom, the analog is removed from the hitlist.

Users can also specify another protein for selectivity testing (referred to
here as the selectivity protein).  In order for an analog to remain in the
final hitlist, it must clash with the selectivity protein.  The bump protein
and the selectivity protein should be aligned and the **BROOD** query should be
based on a molecule that fits within the bump protein active site.  In this
case, analogs in the final **BROOD** hitlist will also fit into the bump protein's
active site, while they will also have clashes with the selectivity protein.
This combination is a simple model for analogs that have a chance to be active
against the bump protein, but have a very low chance of being active against
the selectivity protein.  This model assumes the analog molecules bind to the
bump protein in a manner that is similar to the original ligand and that the
most favorable pose for the ligand class in the selectivity protein is similar
to that in the bump protein.

======================================
Strain energy
======================================

**BROOD**'s output includes newly constructed analog molecules that are intended
to have a similar 3D shape to the query molecule.  These new analogs are
constructed partially from the original molecule and partially from new
fragments.  When these new molecules are generated and built into a
conformation that has good shape and chemistry overlap with the query
molecules, some strain may be introduced.  To produce high-quality results, it
is essential that the analogs are optimized while maintaining the query shape
and that little strain is introduced in the process.

The **BROOD** search process guarantees that each of the molecular fragments alone
is in a low energy state.  After the fragments are joined, this may no longer be
true.  For every **BROOD** analog in the final hitlist, two optimizations are
carried out to determine the local strain introduced by maintaining a shape
similar to the original query.  In the first optimization, the ligand is
allowed to relax into a local minimum.  In the second optimization, the ligand
atoms are only allowed to move a fraction of an Angstrom, keeping the same
overall shape of the molecule.  In both calculations, the OEMMFF
[Halgren-I-1996]_, [Halgren-II-1996]_, [Halgren-III-1996]_, [Halgren-IV-1996]_,
[Halgren-V-1996]_, [Halgren-VI-1999]_, [Halgren-VII-1999]_ potential is used with
a Sheffield solvation function [Grant-2007]_.  The local strain energy is the
difference in ligand energy between the two calculations.  By default, the
maximum strain for any successful **BROOD** analog is limited to 6.5 kCal/M.

======================================
Fragment joining
======================================

One approach to lead identification and development is based on the
identification and expansion of physically very small molecule inhibitors that
are commonly termed "fragments" (see [Hajduk-2007]_).  Fragments in this sense
are molecules with few atoms and should not be confused with the term fragment
used elsewhere in this document that refers to part of a molecule.
Nevertheless, the fragment replacement algorithm in **BROOD** can be useful in the
modeling of fragment-based design.  In fragment-based design, one strategy is
to combine two non-overlapping inhibitory fragments to form a single molecule.
While this is sometimes empirically done with a series of flexible linear
linkers, the linkers can also be modeled.

======================================
Cyclization
======================================

One of the first applications of **BROOD** many users want to explore is the
replacement of a flexible portion of a molecule with a more rigid fragment that
fills the same space.  **BROOD** excels at this application.  This type of exercise
can be considered a local cyclization.  In some molecules, rather than a local
cyclization, some chemists prefer to design a bridge between two portions of a
molecule that do not have a local link.  This is another task where **BROOD** can
be quite useful.  Long-distance cyclization, like fragment joining, is about
finding a chemical fragment that can bridge to moieties given a particular 3D
orientation.

======================================
Molecular complexity
======================================

In the early 1980's, Bertz first published a measure of the complexity of
molecules and asserted that his calculated complexity could be related to synthetic
ease ([Bertz-1981]_, [Bertz-1982]_).  Bertz built complexity terms that are
similar to a Shannon entropy ([Shannon-1949]_) but with regard to the elements
in a molecule and the diversity of small fragments that make up the structure
of the molecule.  While the actual synthetic accessibility can be heavily
influenced by the availability of complex synthetic building blocks and
advances in stereo synthetic methods, molecular complexity remains a useful
tool for prioritizing which compounds chemists should look at first when
primary modeling methods don't readily distinguish between them.

In 2007, Boda and coworkers extended Bertz's idea and compared it to
experimental chemists' predictions of synthetic accessibility ([Boda-2007]_).

Boda made the significant advance of adding stereo complexity to Bertz's
elemental, graph, and ring complexity.  We noted in the paper that nearly all the
signal was generated by the molecular complexity and stereo complexity.  In
fact, each of these measures, without the linear fitting presented in the
paper, correlated with chemists' predictions of synthetic accessibility as well
as the chemists' predictions correlated with one another.  Thus, in **BROOD**, we
have implemented a molecular complexity that is a normalized sum of the graph
and size complexity, elemental complexity, and stereo complexity.  The
normalized complexity score starts at zero for the simplest, smallest molecule
and grows to values that generally don't exceed 1.0 for medicinally relevant
small molecules.

**BROOD** uses molecular complexity to sort analog molecules in the final hitlist
that have very similar shape and color scores.

==============================================
Aromatic fragment comparison
==============================================

This is an example of applying **BROOD** as a technology to explore fragment
similarity outside the direct context of a specific drug-discovery project. Tu
and coworkers at Pfizer explored the chemical space of aromatic ring systems
([Tu-2012]_).  In their work, they used **BROOD** at the core of the NEAT (Novel
and Electronically Equivalent Aromatic Templates) tool.  This tool uses a
combination of high-level QM-derived partial charges along with **BROOD**'s
electrostatic similarity calculation to explore potentially aromatic system
replacements.  It allows medicinal chemists to explore the large space of
complex aromatic ring systems for replacements that are both electronically and
sterically analogous.  We present this example as an illustration of the more
diverse applications of **BROOD**'s fragment-matching technology.

==============================================
Shape-based belief model
==============================================

It is a well-known concept in medicinal chemistry that compounds with greater
similarity have a higher probability of having shared properties.  It is by
this premise that project teams seek to explore chemical space around a lead
compound in order to discover new active molecules.  Based on this concept,
Muchmore and colleagues at Abbott attempted to quantify the relationship
between various measures of ligand similarity and binding activity
([Muchmore-2008]_).  A large number of ligands with activities measured across
a large number and wide variety of targets were used to generate the
probability that two molecules with a given similarity would have activity
within one log unit of one another (the p[active]).  Several well-regarded
ligand similarity techniques showed sigmoidal curves where, at very low
similarity, the probability of shared activity was related to the prevalence of
inhibitors in the underlying data; whereas, as two molecules approached very
high similarity, the probability of similar activity approached something like
35-55%.  While perhaps surprising at first, both of these results are sensible.
It is well known that while similar molecules are much more likely to have
shared activity than two random molecules, similarity is by no means a
guarantee of shared activity.

As reported in their paper, one of the similarity techniques with the highest
maximum probability was the combo score (shape + color score) from the OpenEye
tool ROCS.  The critical change from color score to color Tanimoto occurred in
ROCS since the publication of Muchmore's paper.  The change to color Tanimoto
resulted in an even higher maximum probability of 0.512 ([Brown-Muchmore-2008]_) for
shape + color Tanimoto.  The curve that was refit using the Abbott data is used
in **BROOD** to convert the overall shape + color Tanimoto similarity of the analog
molecule to the query molecule to generate a p(Active) value that indicates the
probability, according the Abbott's belief model, that the analog compound will
have activity within one log unit of the query compound.

==============================================
Abbott bioavailability score
==============================================

In 2005, Martin published a predictive model for the probability that a
compound will have bioavailability (f) > 10% in rats ([Martin-2005]_).
Despite attempts to identify a useful model using straightforward linear
combinations of simple parameters, such as logP, logD, donors, acceptors, PSA,
or flexibility, Martin noted that different predictive models were required for
different ionization states.  Anions require a bioavailability model that
depends strongly on PSA.  By contrast, neutral species, cations, and zwitterions
require a model based on the rule-of-five.  The combination of these models
provides a single model for bioavailability in rats.

.. _brood_compound_similarity:

==============================================
Similarity to available compounds
==============================================

Sometimes it may be desirable to check whether compounds similar to the analogs 
generated by **BROOD** already exist in commercial or internal databases, allowing a 
chemist to consider molecules available for purchase before undertaking the synthesis 
of a given analog. 

**BROOD** uses similarity searching between compounds, based on two-dimensional circular 
fingerprints, to access compound similarity. The cricular fingerprints encode the presence 
of molecular substructures based on atom neighborhoods. This similarity is 
quantified using the Tanimoto coefficient, which measures the ratio of the intersection to 
the union of the fingerprint bit vectors. A Tanimoto similarity threshold of 0.15 is used as the cutoff 
to determine whether two compounds are considered structurally similar.

==============================================
BROOD Database Generation (CHOMP)
==============================================
**BROOD**'s database generation program, **CHOMP**, fragments molecules by
identifying critical bonds that can be broken.  **CHOMP** includes three 
sets of bond-breaking patterns: :ref:`RLF (ring, linkers & functional groups)<chompRLF>`, RECAP
rules [Lewell-1998]_, and ALL (indicating breaking all non-ring, non-resonance
single bonds).  By default, **CHOMP** breaks all bonds identified using any of these
methods.  Users can also specify a SMARTS file of their own bond identifiers.
This file should include a series of SMARTS patterns (one per line) that each
define two atoms on opposite ends of the bond to be broken.  For example, a line
with the SMARTS "*-*" will cause all single bonds to be broken, while a line
with the SMARTS "[R]-[!R]" will cause all bonds between ring atoms and non-ring
atoms to be broken and "[#6]-!@[!#6!#1]" will cause CHOMP to break every single
non-ring bond between a carbon atom and a heteroatom.

.. _chompRLF:

The RLF chemical heuristics seek to break compounds into three types of
primary fragments; contiguous ring systems, functional groups, and linkers.
Contiguous ring systems include any set of atoms that are bonded together by
at least one ring bond.  Thus, fused rings and spiro rings are included as a
single ring system, but biphenyl is broken into two ring systems.  Functional
groups are defined as any collection of bonded atoms including one or more
heteroatoms or unsaturated carbons separated by at most a single
fully saturated carbon atom.  The linkers are the remaining saturated carbon
skeletons.  It should be noted that linkers, like functional groups and
ring systems, can be terminal (i.e., degree 1).

**CHOMP** systematically identifies all the molecular fragments that can be
generated by breaking one or more of the specified bonds.  **CHOMP** first
eliminates fragments that have more than 15 heavy atoms or that have more than
three attachment points.  **CHOMP** also filters the fragments based on commonly
used molecular filters, eliminating unstable, reactive, or toxic functional
groups.  As a final fragment generation step, for every fragment with two
attachment points, **CHOMP** generates two single attachment fragments; for
every fragment with three attachment points, **CHOMP** generates six fragments
with two attachment points and three fragments with single attachment points by
capping the open attachment valence with hydrogens.  **CHOMP** then eliminates any
duplicate fragments.

This first portion of the **CHOMP** algorithm involves only graph processing and
can proceed very quickly.  Please note, however, that when processing molecular
databases of more than a few million compounds, **CHOMP** will use significant
amounts of memory.  Memory usage is especially aggressive early in the
execution, when many new fragments are being identified, and slows somewhat as
the algorithm progresses.

The next stage of the **CHOMP** algorithm is to generate 3D conformers using a
specialized version of the **OMEGA** algorithm.
**CHOMP**'s version of **OMEGA** has a modified TORLIB in order to
sample more generously around the attachment points.  It also differs from
default **OMEGA** parameters in having tighter constraints for removal of RMSD
duplicates (as the measure is very sensitive to size) and for having scaled
MAXCONFS and EWINDOW parameters based on the size of the fragments.  Finally,
**CHOMP** writes the fragments into a **BROOD** database.  To accomplish this,
**CHOMP** carries out several precalculations, including generating
physical properties and adding color atoms.  CHOMP also segregates the fragment
conformers into groups that are likely to match the same types of queries.  All
these processes help **BROOD** search the databases more quickly.

==============================================
BROOD Database
==============================================

**BROOD** databases are currently in the format of a directory or folder that
contains many files.  The databases can be easily compressed and uncompressed 
with standard compression algorithms. They can also be moved, but not easily renamed.  
To rename the **BROOD** database, you must also rename all the files contained 
within it.  Consistency is required to prevent confusion between the name of the 
database and the files being searched under that name.

Of the files in the database directory,
only one is human-readable.  This is the :file:`.info` file.  If you open the
:file:`.info` file with a text reader, you will see some information about the
database, its version, and a manifest of the files that are supposed to be in
the database.  Whenever a database is read, the manifest is checked to ensure the 
database has not been corrupted.



..  program:: brood

======================================
Fragment joining
======================================

In the **BROOD** GUI, it is possible to
load two fragments and use the :option:`-scoreType` ``linkOnly`` search to identify potential
linkers that can join the fragments with an energetically favorable,
medicinally relevant linker in a low-energy conformation.  This search can be
carried out in a protein's active site, taking account of the need for the
linker to fit into the active site as well as join the fragments.  For more
information on this application, please see the :ref:`tutorials section<brood_tutorials>`.

======================================
Cyclization
======================================

Long-distance cyclization, like fragment joining, is about
finding a chemical fragment that can bridge to moieties given a particular 3D
orientation. Use the :option:`-scoreType` ``linkOnly`` option for long-distance cyclization.



==============================================
BROOD Database Generation (CHOMP)
==============================================

..  program:: chomp

**CHOMP** offers additional options for duplicate removal.  To eliminate a set of
potential fragments, such as those from a previous proprietary fragment
database, you can specify the file containing those fragments with the
:option:`-userUnique` flag.

In many instances, users already have sets of fragments generated by their own
means.  **CHOMP** will read these fragments directly using the :option:`-userFrags`
flag.  This flag can be used to generate a **BROOD** database using only these
fragments or in conjunction with fragments generated using the molecular
fragmentation process discussed above.  In either case, **BROOD** will process the
user-defined fragments first and process them in the order they are read from
the :option:`-userFrags` file.  This feature is important for use in
conjunction with **BROOD**'s :option:`brood -quickLook` flag because those fragments will be
searched first.

This first portion of the **CHOMP** algorithm involves only graph processing and
can proceed very quickly.  Please note, however, that when processing molecular
databases of more than a few million compounds, **CHOMP** will use significant
amounts of memory.  Memory usage is especially aggressive early in the
execution, when many new fragments are being identified, and slows somewhat as
the algorithm progresses.  For this reason, about 1G of memory for every million 
molecules you wish to process is recommended.  If necessary, you can break a large 
molecular database into several groups, run each
individually, and save their intermediate results before recombining them
prior to the final stages of the **CHOMP** algorithm.

To write intermediate files, whether for the purpose of breaking a
database into chunks or simply to investigate the fragments **CHOMP** is generating,
a user can set the :option:`-omega` flag to ``False``.  This will cause **CHOMP**
to fragment the molecules but not generate a 3D database.  The 2D output
of this calculation is specified with the :option:`-out` flag, but with the
ISM suffix, which contains all the fragments processed so far.  These
molecules can be examined, filtered, sorted, joined with additional SMILES, and
otherwise manipulated.  The same molecules can be used with the
:option:`-userFrags` flag to generate a **BROOD** database.  Other than the changes
made by manipulating this intermediate output file, the databases generated
by stopping at this intermediate step will be the same as one generated by
executing **CHOMP** with the :option:`-omega` flag set to ``True`` from the start.

Like the **OMEGA** application, the **OMEGA** algorithm inside **CHOMP** can take
up to one or occasionally two seconds per fragment.  For this reason, **CHOMP** can be
run in multi-processor mode using MPI.

As an alternative to using **OMEGA** to generate conformers, **CHOMP** can extract the fragment conformers from a small-molecule structural database.  When a small-molecule structural file is passed to **CHOMP** using the :option:`-readConfs` flag, it signals that **CHOMP** should read the conformers rather than generating them.  For every fragment identified by **CHOMP**, it searches the structural file and identifies all instances of the fragment.  For each instance, the coordinates are extracted and added as a conformer of the fragment.  Finally, duplicate conformers for each fragment are removed.  In this manner, fragment conformers from any source can be included in the **BROOD** database.

.. _brood_brooddatabase:

BROOD Fragment Database 
==============================================

An essential feature of these methods is the generation of a database of
potential fragments.  While it may be tempting to generate fragments *de
novo*, these approaches often generate unrealistic chemical fragments.
Particularly in regards to a method that is related to a common medicinal
chemistry technique, we feel it is important to propose known fragments.

The following databases are available with **BROOD**.

==============================================
ChEMBL31 Fragment Database
==============================================

The ChEMBL31 fragment database is derived from the ChEMBL 31 molecule database. 
The compounds are fragmented and passed through the OpenEye fragment filter,
resulting in 20.7 million fragments.  

==============================================
ChEMBL31_lite Fragment Database
==============================================

The ChEMBL31_lite fragment database is also derived from the ChEMBL 31 molecule 
database. It is more size tractable and contains 8.8 million fragments. In 
addition to applying the OpenEye fragment filter, further filters based on the 
number of heavy atoms and the minimum frequency of fragments were applied in 
creating this database. 

==============================================
brood-database-chembl-3.0.0
==============================================

brood-database-chembl-3.0.0 is derived from the ChEMBL20 molecule
database. The compounds are fragmented resulting in approximately 11 million
unique molecular fragments after standard property filtering. The fragments are
prioritized according to their medicinal and geometric relevance to fragment
replacement and a final collection of approximately six million fragments are
retained for the database.

Users may also provide their own fragment database for searching.  These
fragments databases can be prepared from molecule collections using the **CHOMP**
program. **CHOMP** breaks the molecules into fragments, filters the fragments,
enumerates undefined stereochemistry, tracks molecules from which the fragments
came, and identifies the unique collection of fragments.  Once this set is
generated, **CHOMP** generates or reads multiconformer representations for each
fragment.  The conformers can either be generated by **OMEGA** technology within
**CHOMP** or extracted from small-molecule crystal structure databases passed into
**CHOMP**.  As a final step in database generation, **CHOMP** precalculates physical
and geometric properties, organizes the fragments for efficient retrieval, and
writes a database format that is optimized for efficient **BROOD** searching.

.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _brood_citation:

*********************************
Citation
*********************************

.. note:: To cite BROOD please use the following:

    BROOD |brood_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.




.. _brood_releasenotes:

Release History
===============

.. toctree::
   :maxdepth: 3

   version5_0_0
   version4_2_1
   version4_2_0
   version4_1_0
   version4_0_0
   version3_2_2
   version3_2_1
   version3_2_0
   version3_1_7
   version3_1_6
   version3_1_5
   version3_1_4
   version3_1_3
   version3_1_2
   version3_1_1
   version3_1_0
   version3.0
   version2.0
   version1.1.2
   version1.1.1
   version1.1
   version1.0.1
   version1.0
   version0.9_b2
   version0.9_b1

.. only:: oehtml


#################
BROOD 4.2.1
#################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************



OEBioisostere TK 4.2.1
================================================================================

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

* A new overload has been added to the :ref:`SetSmartsFile <OEBioisostere_OEFragmentOptions_SetSmartsFile>`
  method in :ref:`OEFragmentOptions<OEBioisostere_OEFragmentOptions>`, enabling the ability
  to pass in a file name directly.

* A new overload has been added to the :ref:`OEGenerateConformers<OEBioisostere_OEGenerateConformers>`,
  enabling the option for ``rotorOffset`` compression during conformer generation.
  The existing overload no longer performs ``rotorOffset`` compression.

* A new method, :ref:`HasProteinSelect<OEBioisostere_OEBroodQuery_HasProteinSelect>`, has been
  added to the :ref:`OEBroodQuery<OEBioisostere_OEBroodQuery>` class that can be called on a query to check
  whether it has a selectivity protein.


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

* Both :ref:`OEBroodOverlay<OEBioisostere_OEBroodOverlay>` and
  :ref:`OEFragOverlay<OEBioisostere_OEFragOverlay>` now transfer any residue
  information of query fragments into the overlaid fragments within the
  :ref:`Overlay<OEBioisostere_OEBroodOverlayBase_Overlay>` method.

* The :ref:`Build<OEBioisostere_OEHitlistBuilder_Build>` method in
  :ref:`OEHitlistBuilder<OEBioisostere_OEHitlistBuilder>` now properly
  updates the :ref:`tracer<OESystem_OETracerBase>` when provided.

* The :ref:`Init<OEBioisostere_OEBroodQuery_Init>` method in
  :ref:`OEBroodQuery<OEBioisostere_OEBroodQuery>` now properly
  adds the protein structures for a selectivity check to the query when provided.




..  program:: brood

#######################
BROOD 4.2.0
#######################

**********************
New Features
**********************

* **BROOD** has been rewritten to take advantage of newly released
  API and functionality in **Bioisostere TK**. This ensures that the results 
  from the **BROOD** application are consistent with those from **Bioisostere TK**.

* Some flags have been modified for more consistency with the toolkit and other applications.
  Old flags continue to be functional unless they are `REMOVED`. A complete list 
  of added and `REMOVED` flags can be found in the following table. The list of all
  existing flags could be looked up by running `brood --help all` in **BROOD** CLI app.
 
 .. _brood_flags_update_table:

.. list-table::
   :widths: 20 20
   :header-rows: 1

   * - OLD **BROOD**
     - NEW **BROOD**
   * - `-qMol`, `-queryMol` 
     - `-in`
   * - `-queryFrag`
     - **REMOVED**
   * - `-prot`, `-select`
     - **REMOVED**
   * - `-noqueryprot`
     - `-ignoreProtein`
   * - `-noqueryselectprot`
     - `-ignoreSelectionProtein`
   * - `-csv`
     - **REMOVED**
   * - `-maxFrag`
     - **REMOVED**
   * - `-hitlistProt`
     - **REMOVED**
   * - `-info`
     - **REMOVED**
   * - `-format`
     - `-out`
   * - `-dots`
     - **REMOVED**
   * - `-quickLook (bool)`
     - `-quickLook (int)` - **Old Flag REMOVED**
   * - `-ET`, `-linkonly`
     - `-scoreType  rocs/et/linkonly` - **Old Flags REMOVED**   
   * - `-sdTag`
     - **REMOVED** 
   * - `-interval` , `-hitinterval`
     - **REMOVED** 
   * - `-ringOnly (string->true, none, false,[1,12])`
     - `-ringOnly (int [-2,12])` -  `true -> (-2)`, `none -> (-1)`, `false -> (0)`
   * - `-attachColor`
     - **REMOVED**
   * - `-attachFrag`
     - **REMOVED**
   * - `-maxHit`
     - `-maxHits`
   * - `-attachmentCutoff`
     - `-attachCutoff`
   * - `-forcefield`
     - **REMOVED**
   * - `-`
     - `-buildType (2d, noopt3d, optimized)`
   * - `-attachmentScale`
     - `-attachScale`
   * - `-title`
     - **REMOVED**
   * - `-fromCT`
     - **REMOVED**
   * - `-fileChrg (bool)`
     - `-chargeType (mmff94, fileChrg)` - **Old Flag REMOVED**
   * - `-`
     - `-deltaLocalStrain`

* **vBROOD** has been updated to work with :ref:`OEDesignUnit <OEBio_OEDesignUnit>` contained
  in `.oedu` files for both active site and selectivity proteins. Molecule file formats, such
  as `.oeb` files, for proteins are no longer supported. 

* Two new parameters have been added to both **BROOD** and **vBROOD**: 

  * :option:`-quickLook`: Has been changed from being a `boolean` to an `integer` option,
    enabling users to perform timed searches.

  * :option:`-deltaLocalStrain`: Enables filtering based on relative local strain, instead
    of absolute local strain.

* The naming pattern of output files has been changed. The following files are now created
  as a result of a **BROOD** run:

  #. :file:`brood_log.txt`: the log file 
  #. :file:`brood_parm.txt`: the param file
  #. :file:`brood_hitlist_rpt.csv`: the hitlist report file
  #. :file:`brood_removed_rpt.csv`: the removed hits report file
  #. :file:`brood_hitlist.oeb.gz`: the hitlist
  #. :file:`brood_removed.oeb.gz`: the removed hitlist

  In addition, the following two files are generated when the run is initiated from **vBROOD**:
  
  * :file:`brood_info.txt`: the info file
  * :file:`brood_query.oeb.gz`: a copy of the ran query

****************************************
Related Toolkit Information
****************************************


Bioisostere TK 4.2.0
================================================================================

New Features
--------------------------------------------------------------------------------
* The new class :ref:`OECPDDatabase <OEBioisostere_OECPDDatabase>` has been added as a
  preliminary API, which can be used to perform 2D similarity comparisons between a **Brood**
  hit list and an external compound database.

* Eight new overloads have been added to the existing 
  :ref:`OECreateBroodQuery <OEBioisostere_OECreateBroodQuery>` function.
  The new overloads extend the API for query generation in the presence of an active site
  protein and/or a selectivity protein. Additionally, there are new overloads to create 
  a bridging query between two molecules.

* The following new methods have been added to :ref:`OEHitlistBuilder <OEBioisostere_OEHitlistBuilder>`:
  
  * :ref:`GetRemovedHits<OEBioisostere_OEHitlistBuilder_GetRemovedHits>`
  * :ref:`GetFailedCount<OEBioisostere_OEHitlistBuilder_GetFailedCount>`

  .. two methods later removed:

  * TrimHitlist
  * GetTrimmedCount

* The :ref:`Build<OEBioisostere_OEHitlistBuilder_Build>` method in the 
  :ref:`OEHitlistBuilder <OEBioisostere_OEHitlistBuilder>` has been expanded to accept
  an :ref:`OETracerBase <OESystem_OETracerBase>` as an optional argument.

* The following new methods have been added to :ref:`OEBroodHit <OEBioisostere_OEBroodHit>`:

  * :ref:`GetBuildStatus<OEBioisostere_OEBroodHit_GetBuildStatus>`
  * :ref:`GetDeltaLocalStrain<OEBioisostere_OEBroodHit_GetDeltaLocalStrain>`


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

* Some memory management issues have been fixed in :ref:`AddScores<OEBioisostere_OEHitlistBuilder_AddScores>`
  of the :ref:`OEHitlistBuilder <OEBioisostere_OEHitlistBuilder>` class.

* The :ref:`OEBroodScore <OEBioisostere_OEBroodScore>` returned from the
  :ref:`Overlay <OEBioisostere_OEBroodOverlay_Overlay>` calculation now always contains the fragment,
  irrespective of whether the overlay was a success.

* The :ref:`GetFrags<OEBioisostere_OEBroodDBPacket_GetFrags>` method
  in the :ref:`OEBroodDBPacket <OEBioisostere_OEBroodDBPacket>` now properly returns an empty
  iterator if there are no fragments in a packet.

* The :ref:`SetupRef<OEBioisostere_OEFragOverlay_SetupRef>` method in
  :ref:`OEFragOverlay<OEBioisostere_OEFragOverlay>` is now substantially faster for
  subsequently initializing it with new reference fragments.

* The :ref:`Init<OEBioisostere_OEDBReader_Init>` method in 
  :ref:`OEDBReader <OEBioisostere_OEDBReader>` is now returning an unsigned int
  (instead of bool), reflecting the :ref:`OEBioisostere OEBroodStatusCode Success <OEBioisostere_OEBroodStatusCode_Success>`
  or other error codes for database initialization.





BROOD  4.1.0
================================================================================

Minor internal improvements have been made.



Bioisostere TK 4.1.0
================================================================================

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

* A new algorithm, based on :ref:`OEFlexiOverlay <OEShape_OEFlexiOverlay>`, has been
  adapted in :ref:`Build <OEBioisostere_OEBroodMolBuilder_Build>`
  for optimization of generated poses for molecules obtained from fragment replacement.
  The new algorithm is more robust for optimization of poses for all geometries,
  including cyclic peptides.


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

* Query building algorithms in :ref:`OECreateBroodQuery <OEBioisostere_OECreateBroodQuery>`
  have been improved for robustness. The improved API automatically includes any associated 
  hydrogen atoms as part of the query fragment.  Behavior has also been improved
  to provide better error behavior against invalid selections.

* The new methods :ref:`SetSingleSourceMol<OEBioisostere_OEFragmentOptions_SetSingleSourceMol>`
  and :ref:`GetSingleSourceMol<OEBioisostere_OEFragmentOptions_GetSingleSourceMol>` have
  been added to :ref:`OEFragmentOptions <OEBioisostere_OEFragmentOptions>` to provide
  flexibility regarding source molecule storage during database building.


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

* Some memory management issues have been fixed in :ref:`Build<OEBioisostere_OEBroodMolBuilder_Build>`
  and :ref:`Generate<OEBioisostere_OEDBBuilder_Generate>`.



BROOD  4.0.0
================================================================================

..  program:: chomp

.. These notes have been commented out until the new features are fully ready. SR 5/8/2024

.. New Features
.. --------------------------------------------------------------------------------

.. * **CHOMP** has been rewritten to take advantage of newly released
  API and functionality in **Bioisostere TK**.

.. * **CHOMP** now generates outputs that are consistent with outputs generated
  in other applications (such as **OMEGA**).  The following outputs are
  generated by default:

    * chomp_log.txt: Output run log
    * chomp_param.txt: Parameter file for rerunning the job

.. * These new command line parameters have been introduced in **CHOMP**.

    * :option:`-minFreqHeavy`: This parameter allows treating larger fragments differently, based on frequency.
    * :option:`-filterFile`: This parameter simplifies the :option:`-filter` parameter.
    * :option:`-smartsFile`: This parameter simplifies the :option:`-smarts` parameter.

.. * The following parameters are no longer available in **CHOMP**.

    * ``-userFrags``: This functionality was removed in favor of :option:`-in`. The :option:`-in` automatically
      identifies and uses those as fragments, when applicable.
    * ``-dots``: Dots are now always used to display progress.
    * ``-capAttach``: Related fragments by capping attachment points with a hydrogen is now always turned on.
    * ``-primaryFrag``: This functionality is no longer supported.
    * ``-userUnique``: This functionality is no longer supported.

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

* The ``Filtering`` button was removed from the **vBROOD** home page to prevent irregular crashes and inconsistent UI behavior.


Bioisostere TK 4.0.0
================================================================================

This is the first commercial release of **Bioisostere TK**.


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

The following classes are available as preliminary API with the first
release of this toolkit.

  * :ref:`OEBroodBuildOptions <OEBioisostere_OEBroodBuildOptions>`
  * :ref:`OEBroodDBFilter <OEBioisostere_OEBroodDBFilter>`
  * :ref:`OEBroodDBPacket <OEBioisostere_OEBroodDBPacket>`
  * :ref:`OEBroodFragPrep <OEBioisostere_OEBroodFragPrep>`
  * :ref:`OEBroodGeneralOptions <OEBioisostere_OEBroodGeneralOptions>`
  * :ref:`OEBroodHit <OEBioisostere_OEBroodHit>`
  * :ref:`OEBroodHitlistOptions <OEBioisostere_OEBroodHitlistOptions>`
  * :ref:`OEBroodOverlay <OEBioisostere_OEBroodOverlay>`
  * :ref:`OEBroodOverlayBase <OEBioisostere_OEBroodOverlayBase>`
  * :ref:`OEBroodQuery <OEBioisostere_OEBroodQuery>`
  * :ref:`OEBroodScore <OEBioisostere_OEBroodScore>`
  * :ref:`OEBroodScoreOptions <OEBioisostere_OEBroodScoreOptions>`
  * :ref:`OEDBBuffer <OEBioisostere_OEDBBuffer>`
  * :ref:`OEDBBuilder <OEBioisostere_OEDBBuilder>`
  * :ref:`OEDBReader <OEBioisostere_OEDBReader>`
  * :ref:`OEDBScreenOptions <OEBioisostere_OEDBScreenOptions>`
  * :ref:`OEDBWriter <OEBioisostere_OEDBWriter>`
  * :ref:`OEFragConfReader <OEBioisostere_OEFragConfReader>`
  * :ref:`OEFragmentOptions <OEBioisostere_OEFragmentOptions>`
  * :ref:`OEFragOverlay <OEBioisostere_OEFragOverlay>`
  * :ref:`OEHitlistBuilder <OEBioisostere_OEHitlistBuilder>`
  * :ref:`OEMolPropertyOptions <OEBioisostere_OEMolPropertyOptions>`
  * :ref:`OEIntrinsicPropOptions <OEBioisostere_OEIntrinsicPropOptions>`
  * :ref:`OEExtrinsicPropOptions <OEBioisostere_OEExtrinsicPropOptions>`
   
The following functions are available as preliminary API with the first
release of this toolkit.

  * :ref:`OEBioisostereGetArch <OEBioisostere_OEBioisostereGetArch>`
  * :ref:`OEBioisostereGetLicensee <OEBioisostere_OEBioisostereGetLicensee>`
  * :ref:`OEBioisostereGetPlatform <OEBioisostere_OEBioisostereGetPlatform>`
  * :ref:`OEBioisostereGetRelease <OEBioisostere_OEBioisostereGetRelease>`
  * :ref:`OEBioisostereGetSite <OEBioisostere_OEBioisostereGetSite>`
  * :ref:`OEBioisostereGetVersion <OEBioisostere_OEBioisostereGetVersion>`
  * :ref:`OEBioisostereIsLicensed <OEBioisostere_OEBioisostereIsLicensed>`
  * :ref:`OECreateBroodQuery <OEBioisostere_OECreateBroodQuery>`
  * :ref:`OEGenerateConformers <OEBioisostere_OEGenerateConformers>`
  * :ref:`OEGetBroodStatus <OEBioisostere_OEGetBroodStatus>`
  * :ref:`OEGetDBIndices <OEBioisostere_OEGetDBIndices>`
  * :ref:`OEReadBroodQuery <OEBioisostere_OEReadBroodQuery>`
  * :ref:`OEWriteBroodQuery <OEBioisostere_OEWriteBroodQuery>`



BROOD  3.2.2
================================================================================

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

* **BroodDBMerge** can now merge databases built from any version of ``3.x``.

Minor internal improvements have been made.



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _brood_releasenotes_09b1:

************************
BROOD 0.9.b1
************************

*December 2005*

This is the first public release of the bioisostere program.  The
primary purpose of this release is to garner feedback concerning the
functional aspects of the scientific product.  Critical questions to
address include; does it work in prospective studies, are users
satisfied with the fragment database, are the three types of
bioisosteres incomplete, sufficient or overwhelming.  This release has
a minimal feature list, but should be stable and robust.  While it is
not exceptionally slow, it has not been optimized for speed nor has it
been adapted to PVM or MPI.  

New Features:

1. Multiconformer database of over 90 thousand unique molecular
   fragments generated from commercially available compounds.
2. Automatic 3D conformer generation for query fragments.
3. Automated generation of hitlists for geometric, chemical and
   balanced classes of bioisosteres.


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _brood_releasenotes_09b2:

=====================
BROOD 0.9.b2
=====================

*January 2006*

This beta release of the bioisostere program includes several significant
improvements despite coming soon after the first beta release.  Most
importantly, this release fixes a licensing bug, a best-overlay bug, an RMS
sorting bug, and a hydrogen placement bug in the fragment library.  New
features include, improved sampling for fragments with a single attachment
point and more complete SDTag data.

Release Notes:

1. Improved sampling and initial orientation of fragments with a single
   attachment point.
2. Incorporated color score file into the application.
3. Improved proton placement in the fragment library.
4. SDTag data now includes all the scores of a fragment.
5. Fixed RMS sorting bug.
6. Fixed best-overlay NaN bug.
7. Resolved internal licensing problems.
8. Improved documentation of attachment point representation in SMILES and
   SDF file formats.


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _brood_releasenotes_10:

================
BROOD 1.0.0
================

*April 2006*

This is the first official release of the bioisostere search program **BROOD**.  
This release is a significant overhaul of the beta2 release.
It includes dramatic feature enhancements, bug fixes and optimizations.  Most
notable are improvements in the manner in which fragments are ranked and
addition of electrostatic similarity.  Further, this release has been applied
to many bioisostere examples from the medicinal chemistry literature that have
helped to refine its performance.  Finally, this release makes generation of a
custom fragment database much easier.

Release Notes:

1. Fixed major bug in initial fragment orientation.
2. Added electrostatic similarity measure
3. Significantly refined the evaluation functions for ranking bioisosteres.
4. Added the ability to replace the query fragment with bioisosteric
   fragments in an initial molecule.
5. Added separate handling of query analog fragments to avoid filling the
   hitlists with obvious answers.
6. Allow user specified partial charges and query conformer.
7. Allow user defined scaling of the contribution to similarity resulting
   from the attachment points.
8. Added the ability to write intermediate hitlists during execution.
9. Allow user to limit results to ring fragments only.
10. Refinement of default fragment databases.
11. Execution speed optimizations.
12. Addition of two applications for generating a database of molecular
    fragments.


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _brood_releasenotes_101:

================
BROOD 1.0.1
================

*May 2006*

This version fixes several minor bugs.


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _brood_releasenotes_11:

================
BROOD 1.1.0
================

*May 2007*

This is a major new release of **BROOD**, OpenEye's fragment replacement search program.  This release 
fixes all known bugs from v1.0.  It includes significant re-working of the scoring methods.  Most 
notable among these are that the attachment geometry score is now used as a cutoff to assure that 
all poses have reasonable attachment geometries, but fragments are ranked according to their shape 
plus chemical similarity or their shape plus electrostatic similarity.  Further, several steps have 
been taken to eliminate the bias towards "over-colored" fragments (including implementing Tanimoto 
color rather than scaled color).  Last, but not least, there are dramatic improvements to the 
databases and database content, as well as **CHOMP**, the program for user-generated databases.  The two 
databases provided with **BROOD** now contain the most common fragments found in vendor compounds, are 
more complete, are better filtered, have improved conformer sampling and contain proper MMFF partial 
charges.  We believe this release is a major step toward maturation of the fragment searching methods 
available from OpenEye.

**BROOD** and **CHOMP** Features:

1. Improved conformers of constructed analog molecules to be as close to the original build molecule conformers as possible.
2. Added each score component to the report file as well as to the SDTags.
3. Added the frequency information to the SDTags.
4. Added bondOrder flag that by default requires attachment point bond order to be the same as those in the query fragment.
5. Changed color scoring from scaled-color to Tanimoto-color in order to prevent over-scoring of highly colored fragments.
6. Added shapeCut parameter to prevent very bad overlaps from appearing in hitlist when no good matches are found in the 
   database.
7. Added attachCut parameter to eliminate fragments with poor attachment geometries regardless of how good their shape and
   chemical similarity is.
8. Removed the attachment score as a component to the color combo and ET combo score.  Color combo is now the sum of the shape
   and chemical color Tanimoto scores.  ET combo is now the sum of the sum of the shape and the electrostatic Tanimoto scores.
9. Improved and clarified the handling of 2D and 3D coordinates in the query fragment and the build molecule.  This 
   includes generating depiction coordinates for the built analog molecules when the input build molecule doesn't contain 
   3D coordinates.
10. Improved documentation of hitlists and database generation.
11. Updated OEChem to include the ability to read SDTags from the .oeb formatted database file.
12. Added info file to CHOMP runs.
13. Added warnings when short hitlists are encountered.
14. Added fragment filtering progression and hitlist size to info file.
15. Cleaned up the column ordering in the report file.
16. Properly handle cases with more than three attachment points.
17. Changed :option: `-sdtag` default from "true" to "verbose".
18. Improved reporting of early initialization problems.

BROOD and CHOMP Bug Fixes:

1. Built analog molecules are now aligned with the input build molecule.
2. Fixed bug that caused the query fragment to be moved before the search began and never replaced.
3. Fixed bug that prevented the proper behavior of the :option: `-build` flag in conjunction with the :option: `-ET` flag.
4. Corrected bug related to the :option: `-fileCharge` flag.
5. Fixed query fragment to build molecule matching bug related to differing aromaticity models.
6. Fixed two CHOMP bugs that prevented the :option: `-smarts` flag from working properly.
7. Removed potential for double-counting non-default attachment scale parameter when used with the :option: `-ET` flag.
8. Fixed memory leak in large hitlist management system.

Database Features:

1. Improved database fragment content to include common fragments of all sizes up to 15 heavy atoms (or 350 MW).
2. Generate, use and attach fragment frequency information to each fragment.
3. Developed new methods for filtering fragments rather than filtering whole molecules before fragmentation.
4. Eliminated primary-fragment database.
5. Added simple chemical complexity filters.
6. Improved perception of anionic hydrogen-bond perception.

Database Bug Fixes:

1. Fixed partial charge errors that occurred on some attachment point methyl groups.
2. Fixed polar-proton partial charge error.
3. Removed duplicate fragments.
4. Fixed ring-opening bug that fragmented most aliphatic heterocycles, thus preventing them from occurring in the original 
   database.
5. Fixed branching bug that prevented some unusual branching patterns from occurring in the database.
6. Improved fragmentation schemes for identifying functional groups.

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _brood_releasenotes_111:

.. program:: brood

================
BROOD 1.1.1
================

*August 2007*

This is a minor bug-fix release for **BROOD** v1.1. This release includes a handful of fixes 
to bugs that have been reported over the past three months.  Several of the most important 
bugs related to the `-ET` flag.  We strongly recommend that anyone using
electrostatic similarity should upgrade to this new version.

Release Notes:

1. Fixed major bug that caused molecules in the queryAnalog.build hitlist to be disconnected 
   fragments when the `-ET` flag was true.
2. Fixed bug that allowed the electrostatic Tanimoto to still include the attachment score. 
3. Fixed bug that failed to include the total electrostatic Tanimoto score to be recorded 
   in the report file, even when all the components were present. 
4. Added explicit hydrogens to the entire rebuilt molecule when the `-build` flag
   is used with 3D input. 
5. Removed fragmented partial charges on fragments and built molecules before they are written 
   as output. 
6. Fixed counting error for the number of warnings reported in the information and log files. 
7. Categorized and ordered the appearance of parameters in the auto-help. 


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _brood_releasenotes_112:

================
BROOD 1.1.2
================

*February 2009*

This is a major bug-fix release for **BROOD** v1.1.  This fix includes a major fix 
to the licensing system that allows **BROOD** to use licenses that expire in the 
year 2010 and later.

Release Notes:

1. Updated the license system to work with licenses that expire in 2010 and later. 
2. BROOD installations now support having multiple versions and platform architectures 
   in the same directory structure. 

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _brood_releasenotes_20:

================
BROOD 2.0.0
================

*April 2010*

This is a major rewrite of **BROOD** including a new database format, faster searching, a much larger database and a graphical interface.  The graphical interface greatly simplifies selection of a molecular fragment for replacement and facilitates specification of constraints.

New Features:
-------------

*  **BROOD** now comes with a new graphical application, **vBROOD**, for setting up searches.
*  Includes specification and graphical editing of color constraints.  Pre-defined standard constraints and user-defined constraints are available.
*  New database of more than 3.6 million, common, medicinal fragments.
*  New database format for faster search times.
*  Improved hitlist organization, including a hierarchy based on reduced graphs.
*  Optimized analog molecule overlay.
*  Allows incorporation of a protein structure for clash detection.
*  Graphical interface allows designing of some physical properties.
*  Assessment of synthetic accessibility of generated structures.
*  Implementation of activity belief model for analog molecules.
*  Includes a VIDA extension for ease of exploring results.
*  1-step database generation, including fragment generation and filtering, charge and property calculation, conformer generation, and buffered database creation.

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _brood_releasenotes_300:

================
BROOD 3.0.0
================

*July 2015*

This is a significant release of **BROOD**.  It primarily to add user-requested
features and to fix user-reported bugs.  It includes important improvements in
all four programs included in the **BROOD** suite as well as numerous bug fixes.
This release of **BROOD** also include support for several new Linux platforms as
well as support for MPI multi-processing on Windows.

Platform Support
----------------

*  Added support for RedHat 6, 7, Ubuntu 14, OSX 10.7, 10.8, 10.9
*  Dropped support for RedHat 5 32 bit and OSX 10.6
*  Added MPI support for Windows
*  This will be the last release for SuSe 11

vBROOD
----------------

*  Added auto-suggestion of fragments for replacement in query
*  Reduced arbitrary strict stereo in query build
*  Streamlined query building, searching and results view
*  Improved cluster handling in hitlist filtering
*  Added 2D alignment of results viewing
*  Added upper and lower bound to filter properties

Results Viewer
----------------

*  Annotation of hitlist molecules with color atoms
*  Improved cluster navigation
*  Cleaned up cluster naming and manipulation
*  Improved viewer widget layout
*  Improved visibility of keyboard shortcuts and navigation

BROOD
----------------

*  Substantial improvement to the calculation of local strain
*  Improved elimination of over-strained analogs
*  Added the ability to suppress protein output in hitlists
*  Added the ability to annotate results with similar molecules from a user collection
*  Added protein selectivity
*  Fixed problems with property flag
*  Fixed bug in frequency data
*  Added upper and lower bound to filter properties

CHOMP
----------------

*  Added the ability to pull fragment conformations from user-supplied structure database
*  Added new fragment database derived from ChEMBL [Bento-2014]_
*  Mapping of top 5 source molecules onto each fragment
*  Added enumeration of stereochemistry to CHOMP
*  Fixed inconsistency between single-processor and MPI duplicate removal

Merge
----------------

*  Improved user interface with clearer output and verbose output
*  Added support for duplicate recognition and removal
*  Added ability to overwrite existing databases if necessary

BROOD 3.1.0
================================================================================

*November 2018*

* This version of **BROOD** has been built using **OEToolkits 2018.Oct**. The previous 
  version was built using **OEToolkits 2015.Jun**.

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

* The ``Documentation`` sub-menu of **vBROOD** now correctly points to the 
  online documentation.


BROOD 3.1.1
================================================================================

*May 2019*

* This version of **BROOD** has been built using **OEToolkits 2019.Apr**. The previous
  version was built using **OEToolkits 2018.Oct**.

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

* **BROOD** now correctly finds analogs for queries that does not contain any
  color atoms.

* A segmentation fault caused by **CHOMP**'s failure to construct a valid molecule fragment has been fixed.

BROOD 3.1.2
================================================================================

*Nov 2019*

* This version of **BROOD** has been built using **OEToolkits 2019.Oct**. The previous
  version was built using **OEToolkits 2019.Apr**.

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

* A bug that caused **CHOMP** to crash in some cases when using ``-userFrag`` has been fixed.

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

* A bug that caused the ``-userUnique`` flag of **CHOMP**  to not parse absolute or relative paths
  correctly has been fixed.

* **CHOMP** now properly runs in multi-node MPI mode when passing in a custom filter file.

* **CHOMP** now honors  ``-maxHvy`` values greater than the default value of 15 for
  post-fragmentation filtering.

* A segmentation fault caused by **CHOMP**'s failure to construct a valid molecule fragment has been fixed.



BROOD 3.1.3
================================================================================

*Spring 2020*

* This version of **BROOD** has been built using **OEToolkits 2020.0**.

Minor bug fixes
--------------------------------------------------------------------------------
* **BROOD** no longer fails when stereos are not specified for query fragments.

* **BROOD**’s warning messages about invalid query fragments are now clearer.

* Clicking `Show on Disk` in **vBrood** on macOS no longer uses Apple Script.  This avoids
  OS-generated log messages in the terminal window.

* **vBrood** no longer generates `libpng` warning messages upon startup.

* Clicking `Run` after creating a query no longer uses the deprecated ``OEFileRandomName``
  function. This avoids warning messages in the terminal window.



BROOD  3.1.4.0
================================================================================

*Fall 2020*

* Minor internal improvements have been made.

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

* Documentation and command line help for the ``-smarts`` parameter have been updated
  with information on built-in fragmentation methods.


BROOD  3.1.5
================================================================================

*July 2021*

* Minor internal improvements have been made.



BROOD  3.1.6
================================================================================

*Fall 2021*

* Minor internal improvements have been made.



BROOD  3.1.7
================================================================================

*Spring 2022*

* Minor internal improvements have been made.



BROOD  3.2.0
================================================================================

*Fall 2022*

New Features
----------------
* Two new fragment databases, ChEMBL31_lite and ChEMBL31, are now available. 
  Refer to the :ref:`BROOD Fragment Database <brood_brooddatabase>` section for details about 
  these new fragment databases.

Major bug fixes
--------------------------------------------------------------------------------
* An issue that caused :ref:`BROOD <chapter_brood>`
  to generate incorrect ``Molecular Tanimoto Combo`` with corresponding ``p (active)``
  has been fixed.

* An issue that caused :ref:`CHOMP <chapter_chomp>`
  to generate a much larger database than expected, by generating too many conformers
  per fragment, has been fixed.



BROOD  3.2.1
================================================================================

Minor bug fixes
--------------------------------------------------------------------------------
* The default for the ``-property`` parameter in **BROOD** has been changed to
  ``False``, so it is consistent with **vBROOD**.


.. EON documentation master file
.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. put headings inside the component RST files. 5/20/21

#################################
EON |eon_version|
#################################

.. toctree::
   :maxdepth: 3

   introduction
   eon/eon
   theory/eon_theory
   releasenotes/index
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt





.. _eon_introduction:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


..  program:: eon

************
Introduction
************

==============
Overview
==============

**EON** is a tool for aligning and scoring a database of molecules based on similarity
in molecular shape and electrostatic property.
Electrostatic property is described by either charge density (the default option)
or potential. The scores are used to rank molecules based on the probability that
they share relevant (biological) properties with the query molecule.

**EON** does not require prealigned molecules.
The alignment and scoring is done internally with molecular shape and charge density
similarity. When **EON** is run in the :option:`-potential` true mode, the
aligned geometries are scored with molecular shape and potential similarity.

The inputs into **EON** are a database of molecules in at least one 3D conformation, and a query molecule.
The minimal output is a file of the best alignments and shape and electrostatic similarity scores for each of the database molecules to the query.

==============
Applications
==============

The **EON** distribution contains a single application:

  :ref:`EON <chapter_eon>`

  Aligns and scores molecules in a database file to a query molecule.


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


*********************************
EON
*********************************

.. _chapter_eon:

.. toctree::
   :maxdepth: 2

   eon_overview
   eon_example
   eon_report_file
   eon_help
   eon_req_params
   eon_opt_params


.. _eon_overview:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: eon

======================
Overview
======================

**EON** calculates the electrostatic similarity between two small
molecules in the form of an Electrostatic Tanimoto (ET) score. **EON** supports
two descriptions of electrostatics: via charge density (by default)
and via potential (:option:`-potential` true) Given a query molecule and a set of
interesting molecules, **EON** will calculate the Electrostatic
Tanimoto between each database molecule and the query. Note, that starting
from version 3.0, **EON** does perform an overlay of the input structures using molecular
shape and charge density similarity optimization. Since
electrostatics calculations require high quality partial charges, **EON** will
calculate new partial charges for the input structures using
MMFF94. If the user provides an input file that contains
structures with higher-quality partial charges, EON can use them as
well (:option:`-charges` existing).

**EON** is also dependent on pKa state and formal charges as these have a
significant impact on electrostatics. EON now has the ability to
adjust both the query and database molecule to a neutral pH model. 
This feature is on by default, but can be turned off by using 
appropriate command line flags.

When **EON** is run in :option:`-potential` true mode, the best shape and charge density hits
are rescored with shape and potential similarity. In doing so the command line flag :option:`-num_top_scores`
(by default equal to 5) controls how many best hits per molecule are being re-scored.

Part of understanding **EON** results is visualization of the electrostatic grids used in the calculation.
Although off by default, when writing **EON** results to a binary (OEB) file, ET grids can be attached to each molecule
and visualized using the **EON** View mode in **VIDA**. When running with :option:`-writegrid` true,
for :option:`-potential` false the charge density grid will be outputted and for :option:`-potential` true the
electrostatic PB potential grid will be added to results.

Since **EON** calculations can be time-consuming (approximately 1 molecule per second per CPU for
the :option:`-potential` true case), EON can use the same distributed computing technology,
Open MPI, that **ROCS** uses to help distribute the workload across a cluster of machines.

.. _eon_example:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: eon

======================
Example Commands
======================

**EON** needs an input for a query file and a set of
molecules in the database file.

So for example:

.. code-block:: bash

   eon -in database_molecules.oeb.gz -query query.sdf -out EON_hits.oeb

will overlay and score all the structures in :file:`database_molecules.oeb.gz` against the molecule in :file:`query.sdf` and place the structures in
:file:`EON_hits.oeb` (with ET scores in SD tag data) and a table of
results in :file:`eon_hitlist_rpt.csv`.

To keep only the best 100 hits, use:

.. code-block:: bash

   eon -in database_molecules.oeb.gz -query query.sdf -out EON_hits.oeb -maxhits 100

Note that the use of an output structure file is mostly for generation
of a single file containing structures and tag data such that loading
this single file into **VIDA** provides easy analysis of the results. If
however, the only real desire is for the numerical scores, simply do not use :option:`-out` command line flag.

.. code-block:: bash

   eon -in database_molecules.oeb.gz -query query.sdf

..  program:: eon

By default, **EON** calculates partial charges using MMFF94. However, if
you have structure files that already contain good partial charges in
both your dbase file and query file, you can tell **EON** to use them
instead:

.. code-block:: bash

   eon -in database_with_charges.mol2 -query query_chg.mol2 -charges existing -fixpka_query false -fixpka_dbase false

Please note that both :option:`-fixpka_query` and :option:`-fixpka_dbase` should
be set to ``false`` if :option:`-charges` is set to ``existing``; otherwise EON
will fail.

To prevent continually overwriting output files, the :option:`-prefix` flag
allows you to give unique names to these files.

.. code-block:: bash

   eon -in database_molecules.oeb.gz -query query.sdf -prefix FOO

will write the hit structures into a file named :file:`FOO_eon.oeb.gz` and the
numerical values will be in :file:`FOO_hitlist_rpt.csv`. The parameter file for this run will likewise be named :file:`FOO_parm.txt` and the log file :file:`FOO_log.txt`. 

Finally, to create ET grids as used in the calculation and attach them
to each output molecule. Note, this only works for OEB output and can
be very memory intensive.

.. code-block:: bash

   eon -in database_molecules.oeb.gz -query query.sdf -writegrid true -out EON_results_with_ET_grids.oeb

.. _eon_reportfile:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: eon 

==============
Report File
==============

The **EON** report file format appears as a csv file *eon_hitlist_rpt.csv* with the following fields. Since the names of the query and the hits are of
indeterminate length, fixed size fields for these names could result
in loss of information. Unfortunately this gives a file that is hard
to read in a terminal session, but it can easily be read into a
spreadsheet program or into the data manager in **VIDA**. 

Name 
   This is the name of the database molecule.

SMILES
   This is the SMILES string of the database molecule.
  
Shape Tanimoto 
   This is the shape Tanimoto of the given database molecule with respect to query molecule.

Charge Tanimoto
   This is the charge Tanimoto with respect to query molecule. Note, that this field is only output when :option:`-potential` false is used.

Potential Tanimoto
   This is the potential Tanimoto with respect to query molecule. Note, that this field is only output when :option:`-potential` true is used.

Shape + Charge Tanimoto Combo  
   Sum of **Shape Tanimoto** and **Charge Tanimoto**. This is a useful
   score that takes into account both shape match and (charge) ET match. Note that this field is only output when :option:`-potential` false is used.

Shape + Potential Tanimoto Combo 
   Sum of **Shape Tanimoto** and **Potential Tanimoto**. This is a useful
   score that takes into account both shape match and (potential) ET match. Note that this field is only output when :option:`-potential` true is used.



.. _eon_help:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: eon 

======================
Command Line Help 
======================

A description of the commandline interface can be obtained by executing **EON**
with the `--help` option.

.. code-block:: bash
   
   prompt> eon --help

will generate the following output:

::

	Simple parameter list
		-in : Input filename to be processed.
		-out : Output filename to be generated.
		-query : -query filename to be used.

	Additional help functions:
	  eon --help simple      : Get a list of simple parameters (as seen above)
	  eon --help all         : Get a complete list of parameters
	  eon --help defaults    : List the defaults for all parameters
	  eon --help <parameter> : Get detailed help on a parameter
	  eon --help html        : Create an html help file for this program
	  eon --help versions    : List the toolkits and versions used in the application



.. _eon_req_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: eon 

======================
Required Parameters
======================

..  option:: -query

    Inputs the query or reference molecule.

..  option:: -in
..  option:: -dbase
      
    Inputs file containing one or more 3D molecules to overlay and score against a reference or query molecule.

File format for :option:`-dbase` can be one of:

============ ===========================
File type    Extension
============ ===========================
OEBinary     .oeb .oeb.gz .oez
------------ ---------------------------
SDF          .sdf .mol .sdf.gz
------------ ---------------------------
MOL2         .mol2 .mol2.gz
============ ===========================



.. _eon_opt_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: eon 

=======================
Optional Parameters
=======================

Execute Options
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -param

   The argument for this flag is the name of a
   file containing control parameters.  The control parameter file acts
   to either replace or augment the command line interface.  All
   parameters necessary for program execution may be provided in the
   control parameter file, although any command given explicitly on the
   command line will supersede options found in the parameter file.
   The application generates a new parameter file containing the full set of
   execution parameters upon every execution.  The name of the
   parameter file is created by combining the prefix
   base name with the *'.param'* extension.

.. option:: -mpi_np <n>

   Specifies the number of processors ``n`` when the application is run in MPI mode.

.. option:: -mpi_hostfile <filename>

   Specifies the name of the file containing processors configuration. For every host
   this file should contain a line ``host_name slots=n`` where ``n`` is the number of
   processors on the host.


File Options
==================

.. option:: -log

   The argument for this flag specifies the name of
   the log file.  The level of detail for logfile information can be
   altered using the :option:`-verbose` flag.  Generation of an
   output log may be disabled by providing ``nul`` as a argument in Windows and ``/dev/null`` as an
   argument on Linux and macOS.  
   [default = ``prefix`` _log.txt]

.. option:: -prefix

   The argument for this flag defines the prefix to be used
   for various information and data files generated.  Most
   important among these is the '*prefix_parm.txt*' file which includes a
   copy of all the parameters used in the run.  The prefix is
   also used to generate a default log file name if not explicitly
   specified with the *-log* flag. 
   [default = <app_name>].

.. option:: -verbose

   This is a boolean flag that controls the level of
   detail written to the log file.  By default only
   minimal information is written to the log file. 
   Verbose logging will cause more information to be written to the log
   file in order to follow behavior during program execution.  
   [default = false]

.. option:: -molNames

   This parameter takes a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set then only molecules in the
   input file(s) (see parameter :option:`-in`) with names that match those
   in the text files will be read in.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecule(s) that are contained in a large file, without
   having to extract those molecules by hand from the input molecules file.
   [default = NONE].

.. option:: -progress

   Show progress on screen.  Options are 'none', 'dots', 'log' and 'percent'.
   The 'dots' options will displays dots on screen to show molecules
   completed.  The 'log' option will duplicate the log file on screen.
   The 'percent' option will track progress through the input file.  
   [default = none]


EON App Options
^^^^^^^^^^^^^^^^

.. option:: -scdbase

   Treat the database file as a single-conformer input (when the format is not
   OEB). [Default=true]

.. option:: -fixpka_query

   Apply a neutral pH model to the query molecule. It should be
   set to ``false`` if  :option:`-charges` is set to ``existing``; otherwise EON will fail. [Default=true]

.. option:: -fixpka_dbase

   Apply a neutral pH model to the database molecules. It should be
   set to ``false`` if  :option:`-charges` is set to ``existing``; otherwise EON will fail. [Default=true]

.. option:: -writegrid

   Whether or not to output electrostatic grid when writing to .oeb file. [Default=false]

.. option:: -charges

   Specifies charges to be used on the query and the database. Default
   is to calculate them internally with ``mmff``. The option
   ``-charges existing`` will use precalculated charges that must be
   set in the input files. If ``existing`` is selected and any
   molecule doesn't have charges then EON will default to ``mmff`` for
   those molecules. Both :option:`-fixpka_query` and :option:`-fixpka_dbase`
   should be set to ``false`` if :option:`-charges` is set to ``existing``;
   otherwise EON will fail. [Default=mmff]

.. option:: -num_top_scores

   When potential mode is engaged, the shape and charge overlay will keep this many 
   best hits, and score them all with potential to choose best combo hit. [Default=5]

.. option:: -potential

   Scoring done with shape and potential similarity combo. [Default=false]

.. option:: -scoreonly

   Whether or not to score only or do full overlay. [Default=false]

EON Hitlist Options
^^^^^^^^^^^^^^^^^^^^

.. option:: -besthits <N>

   Keep a hitlist and find best N hits. Zero implies no hitlist, and streaming all
   scored input in the order of appearance. [Default=500]

.. option:: -maxhits <N>

   When this parameter is greater than zero, stop after *N* hits, otherwise find all hits. [Default=0]

.. option:: -rankby

   Score to use when ranking the hitlist.

   ========  ==============================
   Value     Meaning
   ========  ==============================
   ET_pb     Poisson-Boltzmann ET score
   ET_coul   Coulomb ET score
   ET_combo  Combined ET score (default)
   ========  ==============================

   [Default=ET_combo]

.. option:: -cutoff <N>

    Minimum score to keep. [Default=-1.0]

.. option:: -outputquery

   Output query molecule at the beginning of the hits file. [Default=true]

.. option:: -sdTags

   Attach score information to output molecules as SD data. [Default=true]

   [Aliases=**-sdtags**]

.. option:: -nostructs

   Do not output any structures to the hits file. [Default=false]

.. option:: -hitsfile <filename>

   Absolute filename for the output hits file. Must be a valid molecule file.
   Use ``none`` for no hit file output. Overrides the name generated from
   :option:`-prefix`.

.. option:: -reportfile <filename>

   Absolute filename for the report file. Use ``none`` for no report file
   output. Overrides the name generated from :option:`-prefix`.

.. option:: -oformat <extension>

   Format for the output structure file. Legal values:
   ``sdf``, ``mol``, ``mol2``, ``pdb``, ``ent``, ``mmod``, ``oeb``,
   ``sdf.gz``, ``mol.gz``, ``mol2.gz``, ``pdb.gz``, ``ent.gz``,
   ``mmod.gz``, ``oeb.gz``.
   [Default=oeb]

.. option:: -logfile <filename>

   Absolute filename for the log file. Use ``-`` for stdout, ``none`` for no
   log output. Overrides the name generated from :option:`-prefix`.

.. option:: -statusfile <filename>

   Write status information to this file. Use ``none`` for no status file.

ZAP/PB Options
^^^^^^^^^^^^^^^

.. option:: -salt

   Salt concentration (in mol/L) to use in the PB calculation. [Default=0.04]

.. option:: -spacing

   Grid spacing for internal ZAP grid. [Default=0.75]

Omega Conformer Options
^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -ewindow

   Energy window (kcal/mol) used for conformer selection. [Default=10.0]

.. option:: -rms

   RMS threshold used to identify and remove duplicate conformations.
   [Default=0.3]

.. option:: -sampleHydrogens

   Sample hydrogen positions for hydroxyl (OH), thiol (SH), and amine
   groups during conformer generation. [Default=false]

   [Aliases=**-sampleH**,**-samplehydrogens**]

.. _eon_theory:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


*********************************
Theory
*********************************

**Electrostatic Charge Density**
Starting from version 3.0 EON, incorporates  two types of electrostatic description: charge density and potential.
The charge density is modeled using partial charges and smearing them with a Gaussian function with a prefactor
that is proportional to the partial atomic charge.
This method has advantage of fast speed compared to more expensive potential
calculations; therefore, it is set as a default behavior of EON.

For two charge distributions A and B:

.. math::

	ChargeTanimoto_{A,B} = \frac{O(A, B)}{O(A, A) + O(B, B) - O(A, B)}

Charge Tanimoto similarly to potential Tanimoto below behaves for equal and opposite charge distributions similarly

.. math::

	ChargeTanimoto_{A,A} &= 1.0, \\
	ChargeTanimoto_{A,-A} &= -\frac{1}{3}

For hit list ranking, we report a score (Shape + Charge Tanimoto Combo) that is the sum of the Shape Tanimoto (ST) and the Charge Tanimoto.

**Electrostatic Potential**

EON uses a field-based measure of Tanimoto to compare the
electrostatic potential of two small molecules. This electrostatic
potential is calculated internally using Zap, OpenEye's
Poisson-Boltzmann (PB) electrostatics toolkit.

The basic equation for a field Tanimoto is:

.. math::

   PotentialTanimoto_{A,B} = \frac{\int A(\vec{r})*B(\vec{r})}{\int A(\vec{r})*A(\vec{r}) + \int B(\vec{r})*B(\vec{r}) - \int A(\vec{r})*B(\vec{r})}

The two boundary cases for Electrostatic Tanimoto occur when B = A:

.. math::

   PotentialTanimoto_{A,A} & =  \frac{\int A(\vec{r})*A(\vec{r})}{\int A(\vec{r})*A(\vec{r}) + \int A(\vec{r})*A(\vec{r}) - \int A(\vec{r})*A(\vec{r})}  \\
            & =  1

and the opposite case, when B = -A:

.. math::

   PotentialTanimoto_{A,-A} & =  \frac{\int A(\vec{r})*-A(\vec{r})}{\int A(\vec{r})*A(\vec{r}) + \int -A(\vec{r})*-A(\vec{r}) - \int A(\vec{r})*-A(\vec{r})}  \\
    & =  \frac{- \int A(\vec{r})*A(\vec{r})}{\int A(\vec{r})*A(\vec{r}) + \int A(\vec{r})*A(\vec{r}) + \int A(\vec{r})*A(\vec{r})}  \\
            & =  -\frac{1}{3}

In EON in the potential mode, we report electrostatic potential similarity
based on the outer dielectric used in the PB calculation. We use
an outer dielectric of 80. The rationale for using a PB electrostatic field is that the external potential is dampened by orientation of the aqueous solvent. It is a common observation that proteins essentially act to reproduce the
aqueous desolvation of well-bound ligands. As a result a PB
electrostatic field is more likely to correctly capture the essential
elements of binding than that from the Coulombic field.

For hit list ranking, we report a score (Shape + Potential Tanimoto Combo) that is the sum of the Shape Tanimoto (ST) and the PB Electrostatic Potential Tanimoto.



.. _eon_releasenotes:

Release History
===============

.. toctree::
   :maxdepth: 3

   version3_1_3
   version3_1_2
   version3_1_1
   version3_1_0
   version3_0_0
   version2_4_2
   version2_4_1
   version2_4_0
   version2_3_7
   version2_3_6
   version2_3_5
   version2_3_4
   version2_3_3
   version2_3_2
   version2_3_1
   version2_3_0
   version2.2.0
   version2.1.0
   version2.0.0


#################
EON 3.1.2
#################

Minor internal improvements have been made.

*************************************
Related Toolkit Information
*************************************



Eon TK 3.1.2
================================================================================

Minor internal improvements have been made.



Zap TK 2.5.2
================================================================================

Minor internal improvements have been made.



############################################
EON 3.1.1
############################################

Minor internal improvements have been made.

*************************************
Related Toolkit Information
*************************************


EON TK 3.1.1
================================================================================

Minor internal improvements have been made.


Zap TK 2.5.1
================================================================================

Minor internal improvements have been made.



EON 3.1.0
===============

..  program:: eon

New Features
--------------------------------------------------------------------------------
* Supported input and output file formats for **EON** have been revised
  to improve clarity.
* The output csv file now contains additional columns with a rank of hits and best conformer
  index.
* The Boolean flag :option:`-scoreonly` has been added to the **EON** application to
  allow passing prealigned molecules that only need to be scored.

Bug Fixes
--------------------------------------------------------------------------------
* An issue affecting the **EON** hit list has been fixed. **EON** now properly uses the best conformer
  for each database molecule based on shape and charge density scores, instead of the first conformer
  of the molecule, to generate the hit list.
* A bug in combining shape and electrostatics gradients has been fixed.


Eon TK 3.1.0
================================================================================

This is the first commercial release of **Eon TK**.


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

The following classes are available as preliminary API with the first
release of this toolkit.

  * :ref:`OEChargeFunc <OEEon_OEChargeFunc>`
  * :ref:`OEEonHit <OEEon_OEEonHit>`
  * :ref:`OEEonHitlistBuilder <OEEon_OEEonHitlistBuilder>`
  * :ref:`OEEonHitlistOptions <OEEon_OEEonHitlistOptions>`
  * :ref:`OEEonOverlapFunc <OEEon_OEEonOverlapFunc>`
  * :ref:`OEEonOverlapScore <OEEon_OEEonOverlapScore>`
  * :ref:`OEEonOverlay <OEEon_OEEonOverlay>`
  * :ref:`OEEonOverlayResults <OEEon_OEEonOverlayResults>`
  * :ref:`OEEonOverlayScore <OEEon_OEEonOverlayScore>`
  * :ref:`OEEonPBFunc <OEEon_OEEonPBFunc>`
  * :ref:`OEEonPBOptions <OEEon_OEEonPBOptions>`
  * :ref:`OEEonPBOverlay <OEEon_OEEonPBOverlay>`
  * :ref:`OEExactChargeFunc <OEEon_OEExactChargeFunc>`
  * :ref:`OEGridChargeFunc <OEEon_OEGridChargeFunc>`

The following functions are available as preliminary API with the first
release of this toolkit.

  * :ref:`OEEtGetArch <OEEon_OEEtGetArch>`
  * :ref:`OEEtGetLicensee <OEEon_OEEtGetLicensee>`
  * :ref:`OEEtGetPlatform <OEEon_OEEtGetPlatform>`
  * :ref:`OEEtGetRelease <OEEon_OEEtGetRelease>`
  * :ref:`OEEtGetSite <OEEon_OEEtGetSite>`
  * :ref:`OEEtGetVersion <OEEon_OEEtGetVersion>`
  * :ref:`OEEtIsLicensed <OEEon_OEEtIsLicensed>`
  


Zap TK 2.5.0
================================================================================

Minor internal improvements have been made.



.. _section_eon_releasenotes_3003:

EON 3.0.0.3
===============

* An issue affecting the **EON** hitlist has been fixed. **EON** now properly uses the best conformer
  for each database molecule, based on shape and charge density scores, instead of the first conformer
  of the molecule, in generating the hitlist.

.. _section_eon_releasenotes_3000:

EON 3.0.0.0
===============

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

* **EON** no longer requires pre-aligned molecules.
  The alignment and scoring are done internally with molecular shape and charge density similarity. Optionally, via modifying the boolean command line flag `potential` to `true`, rescoring of those alignments with shape and potential similarity is performed.



Zap TK 2.4.7
================================================================================

Minor internal improvements have been made.


.. Author: Kristi Carlson <kcarlson@eyesopen.com>
.. ================================================================================
.. commit 114f4499f82210c5adcf642dad8522e7f803faf3
.. Author: Kristi Carlson <kcarlson@eyesopen.com>
.. Date:   Tue Feb 20 09:12:45 2024 -0700
.. 
..     Setting the version number to 2.4.7.a.1
.. 
.. CMakeLists.txt





EON 2.4.2
===============

Minor internal improvements have been made.



Zap TK 2.4.6
================================================================================

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

* New overloads of :ref:`GetArea <OEPB_OEArea_GetArea>` have been added that return solvent
  accessible surface areas for specific residues.






EON 2.4.1
===============

Minor internal improvements have been made.



Zap TK 2.4.5
================================================================================

Minor internal improvements have been made.




===============
EON 2.4.0
===============

*Fall 2022*

Minor internal improvements have been made.


===============
Zap TK 2.4.4
===============

Minor internal improvements have been made.





EON 2.3.7
================================================================================

*Spring 2022*

* Minor internal improvements have been made.



Zap TK 2.4.3
================================================================================

* Minor internal improvements have been made.




EON 2.3.6
================================================================================

*Fall 2021*

* Minor internal improvements have been made.

Zap TK 2.4.2
================================================================================

*Fall 2021*

* Minor internal improvements have been made.





EON 2.3.5
================================================================================

*July 2021*

Minor internal improvements have been made.


Zap TK 2.4.1
================================================================================

*July 2021*

Minor internal improvements have been made.




EON 2.3.4.0
================================================================================

*Fall 2020*

* Minor internal improvements have been made.



Zap TK 2.4.0
================================================================================

* Minor internal improvements have been made.




EON 2.3.3
================================================================================

*Spring 2020*

* This version of **EON** has been built using **OEToolkits 2020.0**.


.. _eon_releasenotes_200:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


************************
EON 2.0.0 
************************

Release August 2007

Enhancements
------------
This is a significant new release of EON. This release incorporates
many internal changes in how Electrostatic Tanimoto is calculated
compared to EON 1.1.

*  Salt in the PB calculation is now on by default to help moderate
   large, local charges. This should make EON 2.0 perform much better
   than 1.1 in the case of molecules with formal charges.

*  OpenEye's neutral pH model has been incorporated allowing the
   setting of a pH model on both the query and database
   molecules. Since a significant use of EON is similarity searching,
   having a consistent model between the query and database molecules
   is very important. However, for the case where the states are well
   defined, this feature can be turned off.

*  Instead of the slow and buggy ``-spin`` model for searching
   terminal torsions, EON 2.0 uses technology from OMEGA to only search
   reasonable torsions and to prevent creation of bad structures while
   searching for better electrostatic overlap.

*  The hitlist is now sorted by default by a new score, ET_combo,
   which is the sum of the Shape Tanimoto (ST) and the Electrostatic
   Tanimoto (ET_pb).

*  To make visualization of results easier, EON can write out the
   actual ET grids to the hits file, attached to each hit. This file
   can be loaded into VIDA 3.0 or later and the grids can be visually
   compared.

*  There are also several changes to the mechanics of running the
   calculation including a new :option:`-progress` feature and a more
   detailed PVM log output for PVM jobs.



.. _eon_releasenotes_210:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


************************
EON 2.1.0 
************************

Released June 2011

.. program:: eon

Enhancements
------------

*  The command line flags for choosing which charges to use have been
   simplified. There is a single flag :option:`-charges`. The default is
   still to calculate MMFF charges. To use charges you have precalculated
   outside EON, first make sure you have charges for both the query and the
   dbase molecules, then use ``-charges existing``. 

   .. note::

      To use ``existing`` charges you must provide input files in a format
      that can store charges. This means input should 
      be in either OEB or MOL2.

*  This release adds EON to the set of applications that now use a
   common script in ``openeye/bin`` to determine the appropriate
   architecture and run the appropriate binary.

*  On Windows, there is now an installer that installs the
   documentation and sets up a command prompt to facilitate running
   the EON command line.

Bug Fixes
-----------

*  Fixed a bug to ensure that SD data present in the database is passed on to 
   the EON hitlist. Note that this is specific to SD data other than ROCS scores.
   Since EON can modify the conformation, any ROCS scores would no longer
   be valid so they are removed from the output. Note that the score
   reported as EON_ShapeTanimoto is the final Shape Tanimoto calculated from 
   the best conformation found inside EON.

*  Fixed a bug that caused a crash when trying to write an empty hitlist.

*  Fixed a bug that prevented :option:`-salt` from working.

*  Adding better error checking and messages for input.  All input must be molecules and cannot be shape queries.


.. _eon_releasenotes_220:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


**********
EON 2.2.0 
**********

Released June 2013

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

* The default hitlist format has been changed from sdf to oeb for increased functionality and decreased filesize.  The output format is adjustable with the `-oformat` parameter.

* The `-spacing` parameter has been added.  This parameter can be used to adjust the grid spacing of the Zap/PB calculations.

* An option has been added to allow hydrogen atoms in -OH, -SH, and amines to take part in conformational sampling.  This
  new option can be enabled via the `-sampleHydrogens` parameter.
  By default, hydrogen atoms are not sampled.

* Now SD tags are prefixed with `EON_`.  The tags are optional with the `-sdTags` parameter.  Additionally, 
  any existing ROCS tags will not be removed because ROCS and EON tags no longer conflict. 

Bug fixes
--------------------------------------------------------------------------------

* A bug has been fixed where the multiconformer check was being applied to OEB format files.  Additionally, the default for `-scdbase` has been changed from `false` to `true` to prevent inadvertent merging of molecules with other file formats.

* Warnings have been improved for charging failures.

* `-writegrid` will now write out a grid with the same spacing as the actual Zap/PB calculation.  Previously the attached grid had tighter spacing which could lead to confusion.

Other changes
---------------------------------------------------------------------------------

* PVM (parallel virtual machine) is no longer supported. OpenMPI version 1.6 is supported
  on all platforms.  The `-mpi_np` and `-mpi_hostfile` flags are now used to run EON in MPI mode.
  These new flags replace the `oempirun` script.

* This will be the last release to support SuSe 10.


EON 2.3.0
================================================================================

*November 2018*

* This version of **EON** has been built using **OEToolkits 2018.Oct**. The previous 
  version was built using **OEToolkits 2012.Oct**.


..  program:: eon

EON 2.3.1
================================================================================

*May 2019*

* This version of **EON** has been built using **OEToolkits 2019.Apr**. The previous version was built using **OEToolkits 2018.Oct**.

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

* EON now fails with an error message if `-charges` is set to ``existing`` and `-fixpkadbase` or `-fixpkaquery` is true


..  program:: eon

EON 2.3.2
================================================================================

*Nov 2019*

* This version of **EON** has been built using **OEToolkits 2019.Oct**. The previous
  version was built using **OEToolkits 2019.Apr**.

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

* **EON** now fails if `-charges` is set to ``existing`` and :`-fixpkadbase`
  or `-fixpkaquery` is ``true``.  This avoids the problem with ``fixpka`` incorrectly modifying the molecule but
  not the charges.


.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _eon_citation:

***********
Citation
***********

.. note:: To cite EON please use the following:

    EON |eon_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



.. OEDocking documentation master file

.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



#################################
OEDocking |oedocking_version|
#################################

.. toctree::
   :maxdepth: 2

   introduction
   tutorial/tutorial
   theory/theory
   fred/fred
   hybrid/hybrid
   posit/posit
   make_receptor/make_receptor
   utilities
   releasenotes/index
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt





.. _oedocking_introduction:

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


************
Introduction
************

==============
Overview
==============

OEDocking is a suite of programs and utilities that dock small drug-like molecules into a protein receptor site. The input to these programs is one (or more) crystallographic structures of the target protein (possibly including the ligand with which the protein was crystallized) and one or more drug-like molecules to be docked. The output is the docked structure of the molecules and information about the score or confidence in the docked structure.

==============
Applications
==============

The **OEDocking** distribution contains 3 primary command line programs for docking molecules:

  :ref:`FRED <chapter_fred>`

  * Docks multiconformer molecules using an exhaustive search algorithm
  * Uses the structure of a target protein to dock and score molecules
  * Uses one structure of the target protein

  :ref:`HYBRID <chapter_hybrid>`

  * Docks multiconformer molecules using an exhaustive search algorithm
  * Uses the structure of a target protein and the structure of a bound ligand to dock and score molecules
  * Uses either one or multiple protein-ligand complexes

  :ref:`POSIT <chapter_posit>`

  * Docks molecules by overlaying onto a similar ligand with a known docked pose (generally derived from X-ray crystallography)
  * Compares predicted poses to observed bound ligands in related co-crystals
  * Supplies a robust probability that the given pose is reasonable

==================
Utility Programs
==================

The following utility programs are also included in this distribution:

* :ref:`Make Receptor <chapter_makereceptor>`: A GUI utility for setting up a receptor.

* :ref:`ReceptorInDU`: Creates a receptor inside a prepared OEDesignUnit from Spruce.

* :ref:`OEB2DUReceptor`: Creates a design unit with a receptor (inside the design unit), converting a receptor OEB or OEB.GZ file.

* :ref:`docking_report`: Creates a PDF report for one or more docked molecules.

* :ref:`scorepose`: Rescores and optionally optimizes poses in an active site with the **FRED** scoring function.

* :ref:`receptor_toolbox`: A utility program for receptors that reports information about a receptor and can make simple edits of the receptor file

* :ref:`combine_receptors_usage`: Makes a single receptor using multiple ligands that may be a better target for predicting some ligands.

* :ref:`DU2OEBReceptor`: Converts a design unit with a receptor into a receptor OEB or OEB.GZ file.


.. _tutorial:

Tutorials
=========

.. toctree::
   :maxdepth: 3

   overview
   tutorial_sprucebeforedocking
   tutorial_combine_receptors
   fred_tutorial
   hybrid_tutorial
   tutorial_posit

.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _oedocking_tutorial_overview:

===================
Overview
===================

The OEDocking suite contains three docking programs, :ref:`FRED<chapter_fred>`, :ref:`HYBRID<chapter_hybrid>` and :ref:`POSIT<chapter_posit>`, and associated utilities. The input to :ref:`FRED<chapter_fred>`, :ref:`HYBRID<chapter_hybrid>` or :ref:`POSIT<chapter_posit>` is
one (or more) crystallographic structures of the target protein (possibly
including the co-crystallized ligand) and one or more
drug-like molecules to be docked. The output is the docked structure of the
molecules and information about the score or confidence in the docked structure.

At the end of these tutorials, you will be able to run:

  * :ref:`SPRUCE <chapter_spruce>` to prepare receptor files
    from PDB or MMCIF files for docking.

  * :ref:`COMBINE_RECEPTORS<combine_receptors_usage>`  to take
    disparate but sequence related
    proteins and combine the complexes into new
    receptors with more thorough binding information.

  * :ref:`FRED<chapter_fred>`  to dock multi-conformer molecules into the
    structure of a target protein and score the molecules.

  * :ref:`HYBRID<chapter_hybrid>`  to dock multi-conformer molecules into the
    structure(s) of a target protein and the structure of a bound ligand
    and score the molecules.

  * :ref:`POSIT<chapter_posit>`  to generate
    potential poses of ligands against *OEDocking* receptor targets.

  * :ref:`DOCKING_REPORT<docking_report>`  to generate a PDF report for one or
    more molecules docked by :ref:`chapter_fred` , :ref:`chapter_hybrid` or :ref:`POSIT<chapter_posit>`.

The basic workflow for docking ligands using :ref:`FRED<chapter_fred>`, :ref:`HYBRID<chapter_hybrid>`
or :ref:`POSIT<chapter_posit>` is as follows:

* Generate *OEDocking* receptors with bound ligands.
* Dock ligands into receptor.
* Analyze results.

.. note::

  Data for the tutorials is included in the application bundle.
  Please see :ref:`Example and Tutorial Data<examples_data_loc>` for platform specific information
  regarding the data's location.

.. note::

  For the following tutorials, the OpenEye application banner
  and run settings have been omitted for brevity.

.. _tutorial_sprucebeforedocking:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


=============================
Receptor Preparation Tutorial
=============================

The first step in using :ref:`FRED<chapter_fred>`, :ref:`HYBRID<chapter_hybrid>`, or
:ref:`POSIT<chapter_posit>` is the creation of an **OEDocking** receptor, which is
a collection of docking-related information connected
to a protein. A typical receptor is shown in Figure 1 below.

.. _tutorial_oedocking_receptor:

.. figure:: /_images/oedocking_receptor.png
   :scale: 70
   :align: center
   :alt: OEDocking receptor

   **Figure 1.** The **OEDocking** receptor and typical docking information.

There is an *automated* way to prepare **OEDocking** receptor files using :ref:`SPRUCE <chapter_spruce>`.
Alternatively, the graphical utility :ref:`Make Receptor <chapter_makereceptor>` provides an *interactive*
approach for flexible and customizable receptor preparation.

SPRUCE (Recommended)
------------------------

The :ref:`SPRUCE <chapter_spruce>` application provides functionality for automated biomolecule preparation for
modeling applications. The preparation functions include tautomer evaluation, charge normalization,
receptor grid generation, and missing protein loop building. A typical receptor generation session could begin with
the retrieval of a set of coordinates and an experimental electron density map from the PDB (in this case, the RCSB).
To automatically retrieve the data files from the PDB, the :ref:`Get Structure <chapter_getstructure>` utility in
:ref:`SPRUCE <chapter_spruce>` can be given a four character accession code.

For example, to retrieve the PDB entry 5TMG:

    .. code-block:: console

      > getstructure 5TMG

The above command downloads ``5tmg.pdb``, ``5tmg.cif``, ``5tmg.mtz`` files from RCSB database directly.
Once the files have been downloaded, :ref:`SPRUCE <chapter_spruce>` can be used to generate design units (DUs) and
other receptor components. DUs are explained in the :ref:`theory chapter <sprucetk_theory>` of **Spruce TK**.

    .. code-block:: console

      > spruce -in 5tmg.cif -map 5tmg.mtz

The above command creates the following intermediate DU files:

* ``5TMG_A__DU__7EK_A-402.oedu``
* ``5TMG_B__DU__7EK_B-402.oedu``

DU files are generated for each of the monomers in the crystallographic asymmetric unit; in this example, there are
two copies in the asymmetric unit.  If the user has supplied the electron density map (in this example, ``5tmg.mtz``)
to the **Spruce** command, the quality of the structure is evaluated using the Iridium protocols.

When there is no bound ligand detected, an error message is written into ``spruce_output.log``.
The parameter :option:`enumsites -site_residue` is required to specify a protein residue in the active site for apo
structures.

This command creates **OEDocking** receptor files that are readily used as docking input:

    .. code-block:: console

      > receptorindu -in 5TMG_A__DU__7EK_A-402.oedu -out rec_5TMG.oedu

The above command then creates receptors inside the DU ``rec_5TMG.oedu`` as an input receptor file for
:ref:`FRED<chapter_fred>`,
:ref:`HYBRID<chapter_hybrid>`, and :ref:`POSIT<chapter_posit>`.

Interactive Modification of a Receptor
--------------------------------------
The :ref:`Make Receptor <chapter_makereceptor>` GUI can be used to examine or modify a previously created receptor. The GUI can be used if
a user wants to define constraints or include specific water molecules in the receptor. The implementation of
**Make Receptor** generates an OEDesignUnit file (``.oedu``) for input to any of the **OEDocking** applications.
If using a legacy docking receptor (``.oeb`` or ``.oeb.gz``), conversion between the two file types
can be done using the **OEDocking** utility programs :ref:`OEB2DUReceptor` and :ref:`DU2OEBReceptor`. For example:

    .. code-block:: console

      > du2oebreceptor -in rec_5TMG.oedu -out rec_5TMG.oeb.gz
      > oeb2dureceptor -in rec_5TMG.oeb.gz -out converted_rec_5TMG.oedu

The OEReceptor files, such as ``rec_5TMG.oedu``, can be visualized using **VIDA**. The components are shown in Figure 2.

.. _tutorial_oedocking_receptor2:

.. figure:: /_images/oedocking_vidaoebreceptor2.png
   :width: 60%
   :align: center
   :alt: OEDocking OEBReceptor

   **Figure 2.** The view of the **OEDocking** receptor and components in **VIDA**.

This **OEDocking** receptor includes the protein structure and a
description of the binding site.  This description includes an *outer contour* (highlighted in the *List Window*),
which limits the placement of heavy atoms
during the :ref:`FRED<chapter_fred>`, :ref:`HYBRID<chapter_hybrid>`, or
:ref:`POSIT<chapter_posit>` search procedures.

See the  :ref:`Make Receptor <chapter_makereceptor>` section for generating receptors from structure coordinates instead of
from previously generated **OEDocking** receptor files.


.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _tutorial_combine_receptors:

CombineReceptors tutorial
---------------------------

Combining receptors is an optional step that can be used to take information
found in multiple receptors to create a new, merged, receptor.

:ref:`combine_receptors_usage` is intended to
be used in an automated fashion where the output aligned receptors
should be included with the original receptors when running 
:ref:`chapter_posit`.  As such, the output receptor files
are automatically named based on the input filenames and
only receptors that are capable of merging produce output.

This is particularly helpful when using small bound fragments to try and
predict binding poses for larger ligands.  Combining receptors works
by supplying a list of potential receptors and only receptors that
are deemed worthy or merging are output.  To be worthy of merging:
 
 1. It must be possible to align the protein sequences.
 2. The ligands must overlap, but be different enough to indicate
    that the combined receptor has more information content than
    each independently.

.. _tut_merge1:

.. figure:: /_images/merge1.png
   :scale: 85
   :align: center
   :alt: Merged receptors

   **Merged Receptors:**
   Merging the receptors 2IKO and 2IKU capture more potential
   interaction constraints than either does alone

.. _tut_merge2:

.. figure:: /_images/merge2.png
   :scale: 85
   :align: center
   :alt: Merged receptors

   **Ligand Posed to Merged Receptors:**
   REN9 is correctly predicted by the merged receptor

For example, consider the merged receptor shown in figure:
:ref:`Merged Receptors<tut_merge1>`.  In this case, one of the
ligands binds to a pocket that is not present in the other.
The expectation is that the combination of both ligands
has more information content than either alone.

For each valid
merge, two output files are generated, one in each reference frame.
See the :ref:`combine_receptors_usage` section for more details.

.. _fred_tutorial:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


FRED tutorial
-------------

:ref:`FRED<chapter_fred>` requires a protein to be docked into, a definition of a region in that
protein in which the docking will take place and a multi-conformer database
of molecules to be docked. The most common format for database file(s) is a multi-conformer OEBinary
file created by OpenEye’s OMEGA application, however, this file can be one of
several 3D formats. These formats include SDF, MOL2 and PDB. :ref:`FRED<chapter_fred>` determines
the database file format from the file extension, .sdf or .mol for SDF, .mol2
for MOL2, .pdb or .ent for PDB. Gzip compressed files of these same formats are
allowed as well. :ref:`FRED<chapter_fred>` will interpret `infile.sdf.gz` as a gzip’ed SDF file.

.. note::
   Even though all these formats are supported, using SDF, PDB or MOL2 can
   result in a loss of speed due to the I/O penalty of these formats.

:ref:`chapter_fred` requires a single receptor to dock ligands into. Receptors may be created
with the following programs: :ref:`chapter_makereceptor`, :ref:`ReceptorInDU`, :ref:`OEB2DUReceptor`,
and :ref:`Receptor preparation tutorial<tutorial_sprucebeforedocking>` .

.. note::
   Receptors are encapsulated inside a ``OEDesignUnit`` in .oedu files.

To dock a set of ligands into the receptor ``2IKO_rec.oedu``:

  .. code-block:: console

     > fred -receptor renin/receptors/2IKO_rec.oedu -dbase renin/all.oeb.gz

By default, :ref:`chapter_fred` generates several output files. Unless you specify a different
*Output prefix* during setup, :ref:`chapter_fred` will use the prefix ``fred`` for all output files.

* ``fred_docked.oeb.gz`` - top 500 scoring molecules of ``all.oeb.gz`` docked into ``2IKO_rec.oedu``.
* ``fred_undocked.oeb.gz`` - molecules of ``all.oeb.gz`` that could not be
  docked into the active site (generally occurs if the molecules are too big for the site).
  This file will not be present if all molecules were successfully docked to the active site.
* ``fred_score.txt`` - a tab separated text file containing the name and score of each of
  the top 500 ligands.
* ``fred_report.txt`` - a text report of the docking process.
* ``fred_settings.param`` - a text file containing the parameters used for this run.
* ``fred_status.txt`` -  a text file that is written periodically during the run with the
  status of the run.

If you have a multi-processor machine, you can harness the extra computing power by using
OpenMPI. To re-run the job on a host with 4 processors, you enter the following:

  .. code-block:: console

    > fred -mpi_np 4 -receptor renin/receptors/2IKO_rec.oedu -dbase renin/all.oeb.gz -prefix 2IKO_fred

The output from the docking runs may be viewed in VIDA, as depicted in figure :ref:`2IKO FRED Docked<2IKO_fred_docked>`.

.. _2IKO_fred_docked:

.. figure:: /_images/2IKO_fred_docked_screenshot.png
   :scale: 50
   :align: center

   **2IKO FRED Docked results showing the reference ligand (green) and the top docked ligand**

In addition to analyzing and visualizing the output from a docking run in VIDA, a summary PDF report
can be generated using :ref:`DOCKING_REPORT`.

      .. code-block:: bash

         > docking_report -docked_poses 2IKO_fred_docked.oeb.gz \
                             -receptor renin/receptors/2IKO_rec.oedu  -report_file 2IKO_fred_docked_report.pdf

The result of running the above command is depicted in figure :ref:`2IKO FRED Docking Report<2IKO_fred_docking_report>`.

.. _2IKO_fred_docking_report:

.. figure:: /_images/2IKO_fred_docked_report.png
   :scale: 50
   :align: center

   **2IKO FRED Docking Report**

The PDF report includes a 2D depiction of each molecule, a breakdown of the docking score components by atom,
a comparison of the molecule's score compared to the other docked molecules, and a 'Residue Fingerprint' which highlights
which residues in the receptor site the ligand is interacting with. Greyed out residues are
residues in the site that other ligands interact with, but the current ligand does not.


.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _hybrid_tutorial:

HYBRID tutorial
---------------

:ref:`HYBRID<chapter_hybrid>`  docks molecules using a single receptor or using multiple structures of the 
target protein. When using a single structure, the input files are simply the receptor 
and the ligand database. However, when using multiple structures of the target protein, 
the input files are all of the receptor files and the ligand database.
 
* ``receptor1.oedu`` - a receptor file containing the structure of the target protein
  and a bound ligand.
* ``receptor2.oedu`` - a receptor file containing the structure of the second target
  protein and a bound ligand. This receptor file should have a different structure of 
  the same target protein in ``receptor1.oedu``, generally with a different bound ligand.
* ``multiconformer_ligands.oeb.gz`` - conformationally expanded 3D ligands to dock.

See the usage for multiple receptor files in :ref:`Hybrid Docking with
Multiple Crystal Structures <hybrid_docking_with_multiple_crystal_structures>`.

Setting up and running a :ref:`HYBRID<chapter_hybrid>`  job is similar to :ref:`FRED<chapter_fred>`
job. As a comparison to :ref:`FRED<chapter_fred>`, :ref:`HYBRID<chapter_hybrid>` is used to
dock a set of ligands into the same receptor ``2IKO_rec.oedu``:

  .. code-block:: console

     > hybrid -receptor renin/receptors/2IKO_rec.oedu -dbase renin/all.oeb.gz

By default, :ref:`HYBRID<chapter_hybrid>`  generates several output files. Unless you specify a different 
*Output prefix* during setup, :ref:`HYBRID<chapter_hybrid>`  will use the prefix ``hybrid`` for all output files.

* ``hybrid_docked.oeb.gz`` - top 500 scoring molecules of ``all.oeb.gz`` docked into ``2IKO_rec.oedu``.
* ``hybrid_undocked.oeb.gz`` - molecules of ``all.oeb.gz`` that could not be 
  docked into the active site (generally occurs if the molecules are too big for the site). 
  This file will not be present if all molecules were successfully docked to the active site.
* ``hybrid_score.txt`` - a tab separated text file containing the name and score of each of 
  the top 500 ligands.
* ``hybrid_report.txt`` - a text report of the docking process.
* ``hybrid_settings.param`` - a text file containing the parameters used for this run.
* ``hybrid_status.txt`` -  a text file that is written periodically during the run with the 
  status of the run.

If you have a multi-processor machine, you can use the OpenMPI option.

  .. code-block:: console

    > hybrid -mpi_np 4 -receptor renin/receptors/2IKO_rec.oedu -dbase renin/all.oeb.gz -prefix 2IKO_hybrid

As with the output from :ref:`chapter_fred` docking runs, :ref:`chapter_hybrid`  results may be 
viewed and analyzed in VIDA as shown in figure :ref:`2IKO HYBRID DOCKED<2IKO_hybrid_docked>`.

.. _2IKO_hybrid_docked:

.. figure:: /_images/2IKO_hybrid_docked_screenshot.png
   :scale: 50
   :align: center
   
   **2IKO HYBRID DOCKED results showing the reference ligand (green) and the top docked ligand**

Likewise, you also can create a summary PDF report for the :ref:`HYBRID<chapter_hybrid>`  results using :ref:`DOCKING_REPORT`.


.. _tutorial_posit:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


..  program:: posit

POSIT tutorial
--------------

Given receptors, using :ref:`POSIT<chapter_posit>` is very straightforward.
There are two basic ways to input molecules to :ref:`POSIT<chapter_posit>`.

  * ``-in`` - converts input to 3D conformers ( if 3D structures
    are input, these initial structures are retained )
  * ``-dbase`` - takes the input conformations as is (these
    are normally generated with OMEGA.)

For usage of ``-dbase`` see :ref:`POSIT MPI Tutorial<tutorial_mpi_posit>`.

Given a set of input smiles strings:

  .. code-block:: console

     > posit -receptor renin/receptors/*.oedu renin/merged/*.oedu -in renin/all.smi

.. note::

 On *Microsoft Windows* systems, you need to expand the wildcard:

  .. code-block:: console

     > posit -receptor renin\receptors\2IL2_rec.oedu renin\receptors\2IKU_rec.oedu \
           renin\receptors\2IKO_rec.oedu reninmerged\combine_receptors_2IKO_rec_merged_2IKU_rec.oedu \
           renin\merged\combine_receptors_2IKU_rec_merged_2IKO_rec.oedu -in renin\all.smi

The following files are output:

  * ``posit_docked.oedu`` - contains all successful poses
  * ``posit_score.txt`` - contains the scores of all successful poses
  * ``posit_report.txt`` - contains the report of the run
  * ``posit_status.txt`` - a periodic status file generated during a run
  * ``posit_settings.param`` - parameters used in the run

The following files are output only if non-empty:

  * ``posit_clashed.oeb.gz`` - contains all poses with good enough
    probability but clash
  * ``posit_undocked.oeb.gz`` - contains all unsuccessful poses
  * ``posit_rejected.txt``    - list of rejected structures and status of rejection

There is more than one reason a pose may be unsuccessful.  The
most common is that the probability of the predicted binding mode is
too low. To control this behavior use the :option:`posit -outputall` flag, which
writes all output to the file specified by :option:`-out` in order
of input molecule.

**POSIT** by default writes docked structure results to ``.oedu`` file which can be viewed using **VIDA 5**.  If an
``.oeb`` or ``.oeb.gz`` file is desired use the :option:`hybrid -docked_molecule_file` flag.

To specify the *-prefix* option to add a prefix to all files output
by :ref:`POSIT<chapter_posit>`
or use the *-docked_molecule_file* option to output a pose file with particular name.

When :ref:`POSIT<chapter_posit>` is finished, it prints the final status and indicates what new data
was added to the results that are output.

The ``posit_score.txt`` file contains the scores and ranking of docked structures.

The ``posit_rejected.txt`` file can be used to identify the status of rejected molecules, 
for instance "All conformers clashed with protein" indicates that while the probability 
was good, the protein could not accept the desired pose.

.. note::
  While :ref:`POSIT<chapter_posit>` can take most molecule formats as input,
  with large datasets it is fastest to use a pre-generated database of OMEGA [Hawkins-2010]_
  generated conformers.  It is recommended, above two rotatable bonds, 
  to generate 100 conformers per rotatable bond when running OMEGA:

    .. code-block:: console

       > omega2 -in renin/all.smi -out renin/all.oeb.gz -rangeIncrement 1 \
          -maxConfRange 200,200,300,400,500,600,700,800,900,1000,1100,1200,1300,1400,1500,1600
       > posit -receptor renin/receptors/*.oedu -dbase renin/all.oeb.gz \
          -prefix renin

See the :ref:`posit usage<chapter_posit>` section for more details.

.. _tutorial_mpi_posit:

POSIT MPI tutorial
------------------

Running :ref:`POSIT<chapter_posit>` on multiple cores is a simple matter
of adding the :option:`-mpi_np` argument and specifying the number
of cores desired.  When :ref:`POSIT<chapter_posit>` is run on 
a small job as shown above (with 11 molecules and 6) receptors,
using a large number of cores is overkill.  

  .. code-block:: console

    > posit -mpi_np 3 -receptor renin/receptors/*.oedu -dbase renin/all.oeb.gz \
         -prefix renin

.. _small_posit_mpi:

.. figure:: /_images/posit_small_mpi.png
   :height: 451
   :width: 722
   :align: center
   :alt: POSIT running under MPI for a small number of molecules.
   
   **POSIT performance varying the number of cores against a
   small lead-optimization example.**

As seen in figure :ref:`Posit Performance<small_posit_mpi>`, running
with 3 cores gives a large boost in the run-time and adding another
is only marginally faster.  Note that running under two cores
is not recommended as one core is always the master so, 
in effect, this is the slowest way to run :ref:`POSIT<chapter_posit>`.

Also note that using OMEGA conformations as input is the fastest
way to run :ref:`POSIT<chapter_posit>`.



Theory
======

.. toctree::
   :maxdepth: 3

   receptor
   fred_theory
   hybrid_theory
   scoring
   pose_stub_apps
   pose_howto_stub_apps

.. _receptor_theory:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


*********
Receptors
*********

Overview
--------

A receptor is an integral part of a Design Unit (see :ref:`Spruce Introduction<spruce_introduction>`)
and contains information about the location and characteristics of the binding pocket.
Receptors are used by every program in the OEDocking suite of programs.

A receptor always contains:

   * The :ref:`target mask<receptor_theory_target_mask>` that describes the target
     protein.

   * A :ref:`negative image<receptor_theory_negative_image>` that describes the
     shape of the active site.

A receptor may contain:

   * Docking :ref:`constraints<receptor_theory_constraints>` specifying required
     protein-ligand interactions.

   * A :ref:`score cache<receptor_theory_score_cache>` to speed up the startup
     of :ref:`chapter_fred`, :ref:`chapter_hybrid` or :ref:`SCOREPOSE`.

Contents of a Receptor
----------------------

.. _receptor_theory_target_mask:

Target Mask
^^^^^^^^^^^^^^^^^

The target mask defines the subset of design unit components that should be
included in defining the *protein structure* for docking or pose prediction.

The protein structure includes all molecules that a ligand being docked or
scored interacts with. This generally only includes the protein, but may also
include key cofactors or solvent molecules (e.g. a crystallographic water). All
parts of the receptor structure are static during both docking and scoring and
any cofactors or solvent molecules in the receptor structure are not
displaceable.

.. _receptor_theory_negative_image:

Negative Image
^^^^^^^^^^^^^^

The negative image describes the shape of the active site. It is stored as a
potential grid surrounding the active site.  The negative image has high
potentials where ligand atoms make many contacts with atoms of the active site
without clashing and in positions some ligand atoms are likely to occupy when
other atoms of the ligand make good contacts with the receptor (e.g. bridging
positions ligand atoms will likely occupy when a ligand is stretched between two
pockets).

During docking two shapes are created by contouring the negative image potential
grid. The two shapes control the docking process as follows:

Outer Contour Shape

    During docking any pose examined by the exhaustive search that does not fit
    within this shape will be rejected. A pose is considered to fit if the
    center of every heavy atom is within this shape. The volume of this shape
    is typically between 500 and 2000 cubic Ångströms.

Inner Contour Shape

    During docking any pose examined by the exhaustive search that does not
    touch this shape is rejected. A pose is considered to touch if the center
    of at least one heavy atom falls within this shape. The volume of this shape
    is typically 50 to 100 cubic Ångströms.

The negative image of the receptor is setup when the receptor is created.
When a receptor is made the
contour levels are automatically set for both the inner contour and outer
contour, however the inner contour will be disabled.  The receptor inner
contour can be enabled using the :ref:`RECEPTOR_TOOLBOX` program, which
will slightly improve docking speed at the expense of some sampling.

.. _receptor_theory_constraints:

Constraints
^^^^^^^^^^^

Constraints define key interactions ligands are required to make when docking into
the active site. They are optional and user defined.

Constraints do not affect how a given pose scores, however they do affect how
the docking algorithm chooses poses to score during the docking process. Any
pose that does not match the docking constraints will be rejected and replaced
by the next best scoring pose. If no poses of a ligand match the docking
constraints the ligand will not be docked. If multiple constraints are specified
every constraint must be satisfied or the pose will be rejected.

.. note::

   The docking process used by both :ref:`chapter_fred` and :ref:`chapter_hybrid` has a resolution
   of approximately 1 Ångström, and thus the constraints have a similar resolution.
   Therefore it is possible that poses docked with a constraint may have small
   violations of the constraint distance, up to approximately 1 Ångström.

Receptors support two general classes of constraints; protein constraints and
custom constraints. There may be any number of either class of constraint.

.. note::

   Each individual custom or protein constraint has an enabled flag. A disabled
   constraint is ignored during the docking process.

Protein Constraints
+++++++++++++++++++

A protein constraint specifies an interaction that must be made with a heavy
atom of the protein structure (i.e. protein constraints cannot be placed on
hydrogen atoms). There are five types of protein constraints.

Contact

    A contact constraint is satisfied when any ligand heavy atom is within
    4 Ångströms of the protein heavy atom.

Lipophilic

    A lipophilic constraint is satisfied when any non-polar heavy atom on
    the protein is within 4 Ångströms of the protein heavy atom.

Donor

    A donor constraint is satisfied when a donor on the ligand makes a
    hydrogen bond interaction with the protein heavy atom.

Acceptor

    An acceptor constraint is satisfied when an acceptor on the ligand makes
    a hydrogen bond interaction with the protein heavy atom. Acceptor
    constraints must be placed on the protein heavy atom the donor hydrogen is
    interacting with.

Chelator

    A chelator constraint is satisfied when a chelator on the ligand makes a
    metal-chelator interaction with the protein heavy atom.

Only one protein constraint is allowed per protein heavy atom. If a protein
constraint is set on a protein atom that already has a protein constraint the
original protein constraint will be discarded and replaced by the new
constraint.

Custom Constraints
++++++++++++++++++

A custom constraint requires that docked poses have at least one atom within
a sphere (or set of spheres).  Any heavy atom on the docked pose can
satisfy the constraint, unless the constraints has SMARTS patterns with it,
in which case on atoms matching one of the smarts patterns can satisfy the
constraint.

A custom constraint always has at least one sphere.  If it has multiple spheres
then a matching atom within any of the spheres will satisfy the constraints.

If the custom constraint has no associated SMARTS patterns then any heavy atom
on the ligand will satisfy the constraint if it is in one of the constraints
associated spheres.  If one SMARTS pattern is specified then only an atom
matching the SMARTS pattern will be able to satisfy the constraint.  If multiple
SMARTS patterns are specified then an atom matching any of the SMARTS patterns
will be able to satisfy the constraint.

.. _receptor_theory_score_cache:

Score Cache
^^^^^^^^^^^

A receptor may optionally contain a score cache.  A score cache is scoring
setup information usable by either :ref:`chapter_fred`, :ref:`chapter_hybrid` or
:ref:`SCOREPOSE` to speed up the initialization process prior to docking
and scoring.  Using a score cache will not change the docking or scoring
results.

A score cache is most useful when :ref:`chapter_fred`, :ref:`chapter_hybrid` or
:ref:`SCOREPOSE` are started and stopped often to dock one or a small
number of ligands as the initialization cost must be paid each time the
program is started, and using a score cache can substantially reduce this time.



﻿.. _fred_theory:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


..  program:: fred

*************************
FRED Theory
*************************

:ref:`chapter_fred` docks multiconformer molecules into a single 
:ref:`receptor<receptor_theory>` using an exhaustive search that systematically
searches rotations and translations of each conformer of the ligand within the
active site.  Following the exhaustive search the top scoring poses are
optimized and assigned a final score.  These two steps are described in more
detail below

*Exhaustive Search*

  #. Enumerates, to given resolution, every possible rotation and translation
     of each conformer of the ligand being docked within a box enclosing the
     active site. The resolution of the exhaustive search is determined by
     the overall resolution setting of :option:`fred -dock_resolution` flag.

  #. Discard poses that either clash with the protein or extend too far
     from the binding site using the receptor's negative image outer contour
     (see :ref:`receptor_theory_negative_image` section).  

  #. If the negative image inner contour is enabled discard any poses that
     do not have at least one heavy atom that falls within the inner contour.
     (see :ref:`receptor_theory_negative_image` section).  

  #. Discard any poses that do no match any user specified constraints.
     (see :ref:`receptor_theory_constraints` section).

  #. Score all remaining poses using :ref:`theory_algorithm_chemgauss3`.

  #. Sort poses by score and pass the top scoring poses to optimization.

*Optimization*

  #. Enumerate nearby positions of each pose by having the initial pose
     take one positive and one negative step for each translational and
     rotational degree of freedom (729 poses total).  The resolution of
     these steps is half that of the exhaustive search, and is determined
     by the setting of the :option:`-dock_resolution` flag.

  #. Each pose is scored with :ref:`theory_algorithm_chemgauss4`.

  #. The best scoring poses are retained.  The number of poses retained is
     determined by the setting of the :option:`-num_poses` parameter.

  #. The overall score of the molecule, used to rank the molecule against
     other molecules in the docking database, is set to the best scoring
     pose's score.

   


.. _hybrid_theory:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


*************************
HYBRID Theory
*************************

.. program:: hybrid

:ref:`chapter_hybrid` docks multiconformer molecules into one or more 
:ref:`receptors<receptor_theory>` with bound ligands using an exhaustive search
that systematically searches rotations and translations of each conformer of the
ligand within the active site.  Following the exhaustive search the top scoring
poses are optimized and assigned a final score.  These two steps are described
in more detail below

*Receptor Selection*

.. note::

   If there is only one receptor this these steps are skipped and all ligands
   are docked to the receptor.

#. For each ligand in the docking :option:`database<-dbase>` the similarity
   of the ligand to each of the receptor's bound ligands is calculated based
   on the 3D shape and chemical similarity of the docking ligand and bound
   ligand.

#. Each ligand is then docked to the single receptor that has the most
   similar bound ligand as described in the following steps.

*Exhaustive Search*

  #. Enumerates, to given resolution, every possible rotation and translation
     of each conformer of the ligand being docked within a box enclosing the
     active site. The resolution of the exhaustive search is determined by
     the overall resolution setting of :option:`-dock_resolution` flag.

  #. Discard poses that either clash with the protein or extend to far
     from the binding site using the receptor's negative image outer contour
     (see :ref:`receptor_theory_negative_image` section).  

  #. If the negative image inner contour is enabled discard any poses that
     do not have at least one heavy atom that falls within the inner contour.
     (see :ref:`receptor_theory_negative_image` section).  

  #. Discard any poses that do no match any user specified constraints.
     (see :ref:`receptor_theory_constraints` section).

  #. Score all remaining poses using :ref:`theory_algorithm_cgo`.

  #. Sort poses by score and pass the top scoring poses to optimization.

*Optimization*

  #. Enumerate nearby positions of each pose by having the initial pose
     take one positive and one negative step for each translational and
     rotational degree of freedom (729 poses total).  The resolution of
     these steps is half that of the exhaustive search, and is determined
     by the setting of the :option:`-dock_resolution` flag.

  #. Each pose is scored with :ref:`theory_algorithm_chemgauss4`.

  #. The best scoring poses are retained.  The number of poses retained is
     determined by the setting of the :option:`-num_poses` parameter.

  #. The overall score of the molecule, used to rank the molecule against
     other molecules in the docking database, is set to the best scoring
     pose's score.


.. _dock_scoring:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


*************************
Scoring Functions
*************************

.. _theory_algorithm_chemgauss3:

Chemgauss3
^^^^^^^^^^

The Chemgauss3 scoring function uses Gaussian smoothed potentials to measure the
complementarity of ligand poses within the active site.  Chemgauss3 recognizes
the following types of interactions.

   * Shape 

   * Hydrogen bonding between ligand and protein

   * Hydrogen bonding interactions with implicit solvent

   * Metal-chelator interactions.  

All interaction potentials in Chemgauss are initially constructed using step
functions to describe the interaction of atom pairs (or other chemical points)
as a function of distance.  These interactions are mapped onto a grid that is
then convoluted with a spherical Gaussian function, which smoothes the potential
making it less sensitive to small changes in the ligand position.  Smoothing
the score in this way serves two purposes.  First docking can be run at lower
resolution than would be required if the score were not smooth since small
changes in position to do not cause large changes in score.  Second it reduces
the error associated with the rigid protein approximation by effectively
accounting for the ability of the protein to make small structural
re-arrangements to accommodate the ligand.

Shape interactions in Chemgauss are based on a united atom model (*i.e.* only
heavy atoms are relevant to the shape calculation).  Each ligand heavy atom is
assigned a fixed clash penalty score if the distance between it and a protein
heavy atom is less than the sum of the VdW radii, otherwise it is assigned a
score proportional to the count of the number of protein heavy atoms within
1.25 and 2.5 times the sum of the VdW radii (atoms within 2.5 count one tenth
as much as those within 1.25).  From this score a penalty equal to two close
protein atom contacts is subtracted to represent the VdW interactions with
solvent water that are lost when the ligand docks.  This score is pre-computed
at grid points throughout the active site and the resulting grid is then
smoothed.

Hydrogen bonding groups are modeled with one or more lone-pair or polar-hydrogen
position(s) that describe the directionality of potential hydrogen bonds (with
respect to the hydrogen bonding group's heavy atom).  Donor groups have lone
pair positions representing the possible location of the donor hydrogen
atoms relative to the donating molecule, while acceptors have lone-pair
positions representing the possible locations of the donated hydrogen relative
to the acceptor.  A hydrogen bond is detected and assigned a constant score
when a hydrogen bonding position on the ligand is within 1.0 Angstrom of a
complementary hydrogen bonding position on the protein (*i.e.* when the
polar-hydrogen position of a donor overlaps the lone-pair position of an
acceptor).  If the ligand hydrogen bonding group has multiple polar-hydrogens
and/or lone-pair positions (groups can be both donors and acceptors) then this
calculation is performed for each position and the result is summed.  As with
all Chemgauss terms the hydrogen bond potential is pre-computed at grid points
throughout the site and then smoothed. 
 
Hydrogen bonds to solvent molecule that break when the ligand docks into the
active site are penalized by the Chemgauss scoring function.  Broken 
protein-solvent hydrogen bonds are accounted for by calculating how many
hydrogen bonds water can make with the protein at the position of each heavy
atom of the docked ligand, and a penalty score is assigned which is proportional
to the number of hydrogen bonds.  Broken ligand-solvent hydrogen bonds are
accounted for by calculating desolvation positions around each hydrogen-bonding
group on the ligand that represent the positions water could occupy when making
a hydrogen bonding interaction with the protein.  A penalty is then assessed
that is proportional to the number of desolvation positions that can no longer
be occupied by water because the water in these positions would clash with the
protein.  As before, this potential is placed on a grid and smoothed.  

Chelating interactions between protein metals and ligand chelating groups are
accounted for by Chemgauss (protein-chelator and ligand-metal chelating
interactions are not).  For each chelator on the ligand one or more 
chelating-positions are calculated.  If a protein metal is within 1.0 Angstrom
of any chelating-position of a chelating group then a fixed score is assigned, 
otherwise a zero score is assigned.  As before this potential is placed on a
grid and smoothed.

.. _theory_algorithm_chemgauss4:

Chemgauss4
^^^^^^^^^^

The Chemgauss4 is a modification of the Chemgauss3 scoring function that has
improved hydrogen bonding and metal chelator terms (The shape and implicit solvent
interaction terms are identical to those in Chemgauss3).  The new hydrogen
bonding and metal chelator terms have better perception of the directionality
of these interactions and also account for hydrogen bond networking effects.

To calculate the hydrogen bonding score for a ligand-protein hydrogen bond 
two distances are measured.

  #. How far the donor heavy atom is from the position the acceptor atom would
     consider to be an ideal for a hydrogen bonding to form.

  #. How far the acceptor heavy atom is from the position the donor atom would
     consider to be ideal for a hydrogen bonding interaction to occur.

The score for the hydrogen bond interaction is a product of two Gaussian
functions of these distances scaled by the strength of the hydrogen
bonding groups involved in the interaction.

  HBscore = strength*g(distance1)*g(distance2)

To compute the total hydrogen bonding score for the ligand-protein complex
the individual pairwise scores are calculated for all protein-ligand 
donor-acceptor pairs.  Individual HB interaction are then eliminated if either 
the donor or acceptor exceeds the maximum number of interactions allowed
(e.g., a hydroxyl with one hydrogen is not allowed to make more than one
donor interaction), with the lowest scoring interactions eliminated first.
The final hydrogen bond score is then calculated by summing the scores of
the remaining individual acceptor-donor interactions.

.. _theory_algorithm_cgo:

Chemical Gaussian Overlay
^^^^^^^^^^^^^^^^^^^^^^^^^

The Chemical Gaussian Overlay function (or CGO) is primarily a ligand-based
scoring function although some information from the protein structure is used
as well.  The similarities computed are based on the overall shape of the
molecules as well as the position of hydrogen bonding and metal chelating
groups.  This scoring function requires a bound ligand pose along with the
structure of the target protein.  Typically the ligand structure is obtained
from X-ray crystallography along with the structure of the target protein, 
although a docked ligand could also, in principal, be used.

CGO represents molecules as a set of spherical Gaussian functions describing
the shape and chemistry (acceptors, donors and chelators) of the molecule.  The
Gaussians representing the shape of the molecule are centered at the heavy atom
positions, those for donors are centered on polar-hydrogen positions (*i.e.* 
positions where the donating hydrogen could be when it is involved in a hydrogen
bond), those for acceptors are centered on lone-pair positions (*i.e.* positions
where a donating hydrogen could be when a hydrogen bond is formed) and those
for chelators are centered at chelating positions (*i.e.* locations where a metal
could have a chelating interaction).  The overlap of the Gaussians on the docked
ligand to those on the bound ligand are computed for each type of Gaussian 
(*e.g.* shape, donor, acceptor and chelator) by summing the overlap of individual
pairs of Gaussian. The overlap of each individual pair is calculated by
integrating the product of the two.  To prevent chemistry not relevant to
binding from contributing to the overall score, when calculating the chemistry
overlaps (*i.e.* acceptor, donor and chelator) only groups that make the
interaction with the protein are accounted for (*e.g.* a chelator that does not
interact with a metal on the protein is ignored in the overlap calculation).
The sum of all four types of overlaps is the CGO score.

.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*



.. _chapter_poseprediction:

********************************************************************************
POSIT Theory
********************************************************************************

**POSIT** is a pose-prediction tool primarily based on the assumption that similar
ligands bind similarly.  Pose prediction is the process of determining the structure 
of a ligand bound in the active site of a target protein. Pose prediction with
*POSIT* assumes that the incoming ligand binds to the given protein and makes the 
best effort in correctly placing it in the active site. In conjunction to the
predicted pose, **POSIT** also provides an estimate of confidence, in terms of an
estimated probability, that the docked pose is within 2.0 |Angstroms| of the actual 
binding pose.

.. note::

 Note that this probability
 is not the probability of binding, rather, the probability that the
 pose is correct given the ligand actually binds to the receptor.


*POSIT* consists of multiple *Docking* or *Pose Prediction* methods intentionally
and automatically chooses the best method to use for any particular ligand based 
on the 2D (graph) and 3D (structure) similarity of the docked ligand to the bound 
ligand. The methods *POSIT* uses to dock are:

 #. :ref:`ShapeFit<shapefit_method>` - Shape-guided ligand minimization into the receptor site

 #. :ref:`Hybrid<section_docking_hybrid>` - hybrid method that uses
    ligand and protein information

 #. :ref:`Fred<section_docking_algorithm>` - Standard docking method that uses no ligand information

If there is no bound ligand in the receptor, the *Fred* method is used by default
since it does not rely upon the pressence of the bound ligand.


-------------------------------------------
Handling of isomerisms and chirality
-------------------------------------------

Stereo, and notably nitrogen aniline stereo centers, are currently
somewhat problematic for *POSIT*.  Many crystal structures have
flat geometries for some stereo centers due to time-averaging
during data collection.  This makes stereo centers appear to
have flat geometries in the 3D coordinates.

Because the POSIT algorithm internally expands conformations during
the flexible fitting procedure, the full molecule must be
labeled with stereo - either in the 3D coordinate sense or the
2D coordinate sense.  This means that some pdb ligand structures
will unfortunately be failed by the POSIT algorithm.

To get around this, posit can be told to ignore nitrogen stereo
during the conformer generation phase.

.. note::

 Output structures of *Posit* are not guaranteed to have the same
 conformations of the input molecule.  This is due to the fact that
 force-field minimization is occasionally performed during pose
 prediction.

.. _posit_algorithm:

---------------------------
Estimated Pose Probability
---------------------------

During a drug discovery campaign, thousands of small molecule
inhibitors are made in the course of optimizing molecular properties.
For projects that have X-Ray crystallographic (XRC) coordinates,
structure-based designs help guide the medicinal chemistry efforts.
In many cases XRC provides a detailed picture of the binding of a
small-molecule inhibitor into the binding site.

Many techniques exist for pose-prediction and are well documented
[Erickson-2004]_ .  However,
very few provide a probability that the generated pose is correct where
correct is typically considered to be less than 2.0 |Angstroms| RMSD
(root mean square distance) from experimental crystal structure.
In fact, many docking scores such as Chemscore, Chemgauss3,
PLP [Tuccinardi-2010]_ are not very correlated with correct ligand
pose, and worse are not transferable between systems. The best
docking score in one system may not even be close to the best
docking score in another.

*POSIT* overcomes these issues by comparing predicted poses to observed 
bound ligands in related co-crystals.  As the observed ligand becomes more 
similar to the the predicted pose, both the binding mode and the shape of 
the receptor pocket itself tends to become more similar.

The similarity measures being used are 2D path-based fingerprints and
the 3D *TanimotoCombo* [Hawkins-2010]_ that compares shape and the Mills-Dean
approximation of electrostatics [Mills-Dean-1996]_ . These similarity 
measures choose the most appropriate system to dock against (when multiple
receptors are available) and provide a prediction of the quality of the result.
The *TanimotoCombo* measure is agnostic of how the poses in question are
generated; it can be used to validate and provide a pose prediction
probability regardless of how the pose was generated.

*POSIT* probabilities were generated using a large test set containing
many pose predictions and verified against an independent set of predictions 
that were then validated with X-Ray crystallography.  It is important to note 
that *POSIT* does not give a probability of binding. Rather it gives a probability 
that **if the ligand does actually bind**, what is the likelihood of the *POSIT* 
pose being the actual pose.

Figure :ref:`POSIT Probability MAP<posit_heat_map>` shows how the
beliefs given by the 2D and 3D measures are combined into a
probability of having a good pose.  Remember that this probability has
been generated from ligands that actually bind, hence, it is not a
probability of binding.

.. _posit_heat_map:

.. figure:: /_images/POSIT-prob.png
   :width: 60%
   :align: center
   :alt: POSIT probability of finding poses within 2.0 |A|

   **POSIT Probability Map:** Given a 2D similarity (in this case the :term:`MACCS` 166 descriptor set [Durant-2002]_)
   and a 3D similarity (*TanimotoCombo*) *posit* computes a
   probability of finding the correct pose based on an analysis of
   historical and experimental data.


This result is different from the result shown in [Tuccinardi-2010]_ ,
where they reported that having a high *TanimotoCombo* to the known bound
ligand did not dramatically increase the quality of the resulting pose (even for
*FRED*).  The reason is subtle: Tuccinardi *et al* were computing the
highest *TanimotoCombo* that the two molecules could obtain, while *Posit*
computes the actual, docked, in-place *TanimotoCombo* of the fitted
pose.   That is, if the docking algorithm produces an alignment
of fit molecule to known bound ligand that overlaps with a given
*TanimotoCombo*, one can look up the probability the docking was successful.
In point of fact, *Posit* is specifically
designed so that the docked pose obtains the highest
*TanimotoCombo* score possible while simultaneously minimizing induced
strain and maintaining interactions with the protein.


Categorically the data shown in :ref:`POSIT Probability MAP<posit_heat_map>`,
for each pose can be binned into the following results:

   ============   =======================================================================
   Result         Meaning
   ============   =======================================================================
   GREAT          Computed pose is likely (75%-100% probability) to be within 2.0 |A| of
                  experimentally-derived pose.
   ------------   -----------------------------------------------------------------------
   GOOD           Computed pose may be (50%-75% probability) to be within 2.0 |A| of
                  experimentally-derived pose.
   ------------   -----------------------------------------------------------------------
   MEDIOCRE       Take with a grain of salt (33%-50% probability)
   ------------   -----------------------------------------------------------------------
   POOR           Take with a huge grain of salt (<33% probability)
   ============   =======================================================================

------------------------------
Additional MCS Constraints
------------------------------

Walter's *et al* noted that a large portion of ligands bound to the
same protein kinase share a large maximum common substructure (MCS).  This
was the basis for their **CORES** algorithm [Hare-2004]_ .  *Posit* can  optionally
identify matching regions and use them as additional constraints during
conformer generation. *Posit* performs the MCS match to the bound ligand
by default.

-----------
On Clashes
-----------

The definition of *clashes* is somewhat problematic for purposes of pose
prediction.  In general, serious clashes where interpenetration with the
protein should be avoided at all costs.  However, when docking into
a rigid protein that does not have the appropriate conformation, rigid
docking ignores that fact that the active site may adopt a conformation suitable
to the posed ligand.

*Posit* uses the definitions from :ref:`OEClashInteractionHint<OEBio_OEClashInteractionHint>`
to identify clashes. *Posit* allows the users to specify three
allowable clash levels.

   ================================== ============================================
   Allowed Clash                      Description
   ================================== ============================================
   noclashes (none)                   No clashes are allowed.
   ---------------------------------- --------------------------------------------
   hydrogen (mild clashes)            Only hydrogen clashes are allowed.
   ---------------------------------- --------------------------------------------
   allclashes                         All clashes are allowed.
   ================================== ============================================

.. _section_example_oedocking_PoseMolsMultiReceptor:

--------------------------
Using Multiple Receptors
--------------------------

Using multiple receptors to dock or pose molecules has been shown to
greatly increase the reliability of docking. 

When multiple receptors are provided *Posit* chooses the appropriate reference 
system based on the 2D/3D similarity to the bound ligand. The best reference, 
in general, has the highest 2D/3D similarity of the input molecule to the chosen 
bound ligand.  The similarity measure used here are similar to those used
in determining the best docking method in *Posit*.

.. _section_example_oedocking_PoseMolsProteinFlex:

----------------------
Receptor Flexibility
----------------------

Incorporating multiple receptors is the simplest way to account for receptor
flexibility during pose prediction. With multiple receptors, *Posit* would
pick the best suitable conformer of the receptor for a particular docked ligand.

Pose generated from *Posit* with provided receptor conformers can still sometimes 
contain clashes. Option is available to trigger post pose prediction relaxation,
that relaxes both the posed ligand and protein residues around it.

Note that optimization of a protein-ligand complex can sometimes be time consuming, 
especially if the target protein and associated components are large.

--------------
TanimotoCombo
--------------

*Posit* uses the *TanimotoCombo* measure to compare (and optimize)
predicted and bound ligands.  The *TanimotoCombo* measure is simply two
separate Tanimoto measures added together.  While most uses of Tanimoto have
been to compare fingerprints together, there is a direct relation
between the 1D fingerprint bit vector and 3D space:

The basic equation for a field Tanimoto between two fields A and B is:

.. math::

   Tanimoto_{A,B} = \frac{\int A(\vec{r})*B(\vec{r})}{\int A(\vec{r})*A(\vec{r}) + \int B(\vec{r})*B(\vec{r}) - \int A(\vec{r})*B(\vec{r})}


In the case of *Posit*, the field in question can be thought of as field of
voxel space.  For :math:`Tanimoto_{shape}`, where A and B are now
molecules:  if two objects fill the same voxels, then the Tanimoto
value is 1.0.  If two objects overlap by half, the Tanimoto value
is 0.5 and so on.  (The term voxel is used for purposes edification, in
actuality the volumes estimated using a fast approximate method)

.. _voxel:

.. figure:: /_images/voxel.png
   :width: 75%
   :align: center
   :alt: Voxel representation of space


   **Voxel Representation of Shape:** Similar to fingerprint bits in
   1D, voxels can be used to represent 3D
   space and compared with the Tanimoto measure.  The numerator
   *Overlap(q,t)* is essentially the volume of
   the **intersection** of *q* and *t* and the denominator
   *Overlap(q,q) + Overlap(t,t) - Overlap(q,t)* is essentially
   the volume of the **union** of *q* and *t*.

The field can also contain colored representations of chemistry.  For
example, if two voxels are colored as hydrogen bond donors and
overlap, the :math:`Tanimoto_{color}` increases.

Hence, *TanimotoCombo* is:

.. math::

  TanimotoCombo = Tanimoto_{shape} + Tanimoto_{color}

*TanimotoCombo* values range from 0 (no overlap) to 2.0 (full shape overlap and full
color or chemistry overlap).

.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


********************************************************************************
Posit How to
********************************************************************************

Ignore Nitrogen stereo
-------------------------------------------

Nitrogen stereo can be ignored in *Posit* by setting the `-ignore_nitrogen_stereo`
parameter to ``true``.

Prepare molecules for Posit
-------------------------------------------

With default settings, *Posit* internally generates the required input conformers
and *Posit* can be used with 2D input molecules.  However, if it is desired to
pass a pre-generated set of conformers to *Posit*, following are the recommended 
ways to supply or prepare molecules for POSIT.

  1. Use *OMEGA* or the *OMEGA toolkit* to prepare molecules or
     expand the stereo chemistry using *OEFlipper*.  *POSIT*
     is guaranteed to work correctly if the input molecules
     have been generated by *OMEGA*.

  2. Pass the *OMEGA* generated 3D conformers through the `-dbase` parameter.
     This method of running *POSIT* is not recommended as a large portion of the
     flexible methodology will be deactivated.

Use multiple receptors
-------------------------------------------

Multiple receptors can be passed to *Posit* through the `-receptor` command-line
parameter.

Obtain clash-free pose
----------------------------------

Pose generated from **Posit** with the default options can sometimes contain
clashes. Users have the option to perform pose relaxation, either on the
clashed poses or on all generated poses, with the `-relax` command-line
parameter


.. _chapter_fred:

FRED
====

.. toctree::
   :maxdepth: 2

   fred_overview
   fred_input
   fred_example
   fred_help
   fred_req_params
   fred_opt_params




.. _fred_overview:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: fred 

======================
Overview
======================

:ref:`chapter_fred` is a docking program that docks molecules from a multiconformer
database into a :ref:`receptor<receptor_theory>` site using an exhaustive search
algorithm.
 

.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _fred_input:

.. program:: fred

=================
Input Preparation
=================

.. note ::

   It is not required to calculate the ligand charges and protein charges explicitly. The
   scoring functions do not utilize partial charges.

.. _fred_ligand_preparation:

Ligand Preparation
------------------

The most common use of :ref:`chapter_fred` is to dock a large collection of molecules into the
active site of a target protein.  For the purposes of this document, we'll call
the file(s) of molecules the database file(s), or dbase file(s).  The most
common format for database file(s) is a multi-conformer OEBinary file created
by OpenEye's **OMEGA** program, however, this file can be one of several 3D formats.
These formats include SDF, MOL2 and PDB. :ref:`chapter_fred` determines the database file
format from the file extension, :file:`.sdf` or :file:`.mol` for SDF,
:file:`.mol2` for MOL2, :file:`.pdb` or :file:`.ent` for PDB. Gzip compressed
files of these same formats are allowed as well. :ref:`chapter_fred` will interpret
:file:`infile.sdf.gz` as a gzip'ed SDF file.

.. note::

   Note that even though all these formats are supported, using SDF, PDB or MOL2
   can result in a loss of speed due to the I/O penalty of these formats.

:ref:`chapter_fred` has no provision for conversion of 1D/2D molecules to 3D. **The database
file(s) must be in a conformationally expanded 3D format**.  Within the OpenEye
tool chain the program OMEGA can be used to generate conformers.

By default :ref:`chapter_fred` will interpret conformers in the database file(s) as part of a
single multi-conformer molecule as long as they:

* Are contiguous in the input file.
* Have the same numbers of atoms and bonds in the same order
* Have identical atom and bond properties with their order
  correspondent in the subsequent connection table
* Have the same atom and bond stereochemistry

While this may appear to be a restrictive list, many programs write
multi-conformer molecules into SDF or MOL2 files such that the above rules
will be satisfied. If the conformers are named differently, (*i.e.* they
have a conformer number appended to the base name like acetsali_1,
acetsali_2), :ref:`chapter_fred` will still consider them part of a single multi-conformer
molecule if the criteria above are met.

.. _fred_receptor_preparation:

Receptor Preparation
--------------------

.. note::

  Beginning with :ref:`chapter_fred` 4.0.0,  :ref:`chapter_fred` now only accepts an OEDU with receptor as the
  receptor input file.

:ref:`chapter_fred` requires a single :ref:`receptor<receptor_theory>` to dock ligands
into.  The contents of a receptor are described in the
:ref:`receptor theory<receptor_theory>` section.  Receptors can be created with
the following programs

.. tabularcolumns:: |l|l|p{10cm}|

=======================================  ============  ==========================================
Program                                  Type          Description
=======================================  ============  ==========================================
:ref:`chapter_makereceptor`              GUI           Interactive GUI for creating a receptor.
---------------------------------------  ------------  ------------------------------------------
:ref:`ReceptorInDU`                      Command Line  Generates a receptor inside a prepared
                                                       OEDesignUnit in an OEDU file.
---------------------------------------  ------------  ------------------------------------------
:ref:`OEB2DUReceptor`                    Command Line  Converts a molecule based receptor OEB or
                                                       OEB.GZ file into a receptor inside
                                                       an OEDesignUnit, in an OEDU file
=======================================  ============  ==========================================

.. note::

   Receptors can also be created using the Docking Toolkit (see the Docking Toolkit
   documentation).


.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _fred_example:

.. program:: fred 

======================
Example Commands
======================

Basic docking example
---------------------

This example docks molecules on a single processor using default parameters.

Input files for 1DWD

   * **receptor.oedu** :
     A receptor file containing the structure of the
     prepared target protein.  (see :ref:`fred_receptor_preparation` section). 

   * **multiconformer_ligands.oeb.gz** :
     Conformationally expanded ligands to dock.
     (see :ref:`fred_ligand_preparation` section).

Command line

   .. code-block:: bash

      prompt> fred -receptor receptor.oedu -dbase multiconformer_ligands.oeb.gz

Output files

   * **fred_docked.oeb.gz** :
     Top 500 scoring molecules of 
     *multiconformer_ligands.oeb.gz* docked into *receptor.oedu*.

   * **fred_undocked.oeb.gz** :
     Molecules of *multiconformer_ligands.oeb.gz* that could
     not be docked into the active site (generally occurs if the molecules are too
     big for the site).  This file will not be present if all molecules were 
     successfully docked to the active site.

   * **fred_score.txt** :
      A tab separated text file containing the name and score of
      each of the top 500 ligands.

   * **fred_report.txt** :
     A text report of the docking process.

   * **fred_settings.param** :
     A text file containing the parameters used for this run.

   * **fred_status.txt** :
     A text file that is written periodically during the run 
     with the status of the run.

MPI docking example
-------------------

This example docks molecules on 4 processors of the host machine.

Input files

   * **receptor.oedu** :
     A receptor file containing the structure of the 
     prepared target protein.  (see :ref:`fred_receptor_preparation` section). 

   * **multiconformer_ligands.oeb.gz** :
     Conformationally expanded ligands to dock.  (see :ref:`fred_ligand_preparation`
     section).

Command line

      .. code-block:: bash

         prompt>fred -mpi_np 4  -receptor receptor.oedu \
                                     -dbase multiconformer_ligands.oeb.gz

Output files

   * **fred_docked.oeb.gz** :
     Top 500 scoring molecules of 
     *multiconformer_ligands.oeb.gz* docked into *receptor.oedu*.

   * **fred_undocked.oeb.gz** :
     Molecules of *multiconformer_ligands.oeb.gz* that could
     not be docked into the active site (generally occurs if the molecules are too
     big for the site).  This file will not be present if all molecules were 
     successfully docked to the active site.

   * **fred_score.txt** :
     A tab separated text file containing the name and score of each of
     the top 500 ligands.

   * **fred_report.txt** :
     A text report of the docking process.

   * **fred_settings.param** :
     A text file containing the parameters used for this run.

   * **fred_status.txt** :
     A text file that is overwritten periodically during the run 
     with the status of the run.

.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _fred_help:

.. program:: fred 

======================
Command Line Help
======================

A description of the command line interface can be obtained by executing **FRED**
with the `--help` option.

.. code-block:: console
   
   > fred --help

will generate the following output:

::

   Help functions:
     fred --help simple      : Get a list of simple parameters
     fred --help all         : Get a complete list of parameters
     fred --help defaults    : List the defaults for all parameters
     fred --help <parameter> : Get detailed help on a parameter
     fred --help html        : Create an html help file for this program
     fred --help versions    : List the toolkits and versions used in the application



.. _fred_req_params:

.. program:: fred

======================
Required Parameters
======================

.. option:: -receptor <receptor file>

   All molecules will be docked to this receptor. The receptor file must be in
   OEDocking receptor format (``.oedu``).

   [Aliases=**-rec**]

.. option:: -dbase <input filename1> [<input filename2> ... ]

   File(s) containing ligands to dock (see section :ref:`fred_ligand_preparation`).
   
   The following file formats are supported.

   ============ ===========================
   File type    Extension                  
   ============ ===========================
   OEBinary     .oeb .oeb.gz               
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz  
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz             
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz  
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz             
   ============ ===========================

   More than one file can be specified.

   [Aliases=**-database**,**-in**]


.. _fred_opt_params:

.. program:: fred

======================
Optional Parameters
======================

Input Options
--------------

.. option:: -param <parameter filename>    [No Default]

   A parameter file is a text file that lists parameter settings to be used
   during a run.   If a parameter is specified both on the command line and in
   the parameter file, the value specified on the command line is used.

   The format of the parameter file is as follows:

   * One parameter per line

   * For non-list parameters one key-value pair per line. (*e.g., -receptor rec.oedu*).

   * For list parameters a key followed by all the values (*e.g., -dbase lig1.oeb.gz ligs2.oeb.gz*)

   * Boolean parameters must be listed as a key followed by true or false (*e.g. -annotate_poses true*).

   * The parameter file may not contain the :option:`-param` parameter.

   * Lines beginning with # are considered comments



.. option:: -molnames <input filename>    [No Default]

   This parameter specifies a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set then only molecules in the
   database file(s) (see parameter :option:`-dbase`) with names that match those
   in the text files will be read in.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecule(s) that are contained in a large database, without
   having to extract those molecules by hand from the database.



Dock Options
------------

.. option:: -dock_resolution <setting> [Default: Standard]

   The parameter controls the resolution of the docking both during the exhaustive
   search and the optimization.  The resolution of the exhaustive search at each setting
   is as follows.

   =========   ================  ===================
   Setting     Translational     Rotational         
               Stepsize          Stepsize           
   =========   ================  ===================
   High        1.0 Ångström      1.0 Ångström      
   ---------   ----------------  -------------------
   Standard    1.0 Ångström      1.5 Ångströms      
   ---------   ----------------  -------------------
   Low         1.5 Ångströms     2.0 Ångströms      
   =========   ================  ===================
   
   During the optimization step the resolution is half that of the exhaustive search.

   [ Aliases = **-res** ]

   .. seealso::

      * :ref:`OEDocking::OEDockOptions::SetResolution <OEDocking_OEDockOptions_SetResolution>` in the **OEDocking TK** manual.


Output File
-----------

.. option:: -docked_molecule_file <filename> [Default=docked.oeb.gz]

   File docked molecules will be written to.  The file format is
   controlled by the extension of the filename.  The following output
   formats are supported.

   ================ ===========================
   Format           Extension
   ================ ===========================
   OEBinary         .oeb
   ---------------- ---------------------------
   SDF              .sdf
   ---------------- ---------------------------
   Gzipped OEBinary .oeb.gz
   ---------------- ---------------------------
   Gzipped SDF      .sdf.gz
   ================ ===========================

   Scores will be attached as SD data to each pose with the tag
   *FRED Chemgauss4 Score*, unless the :option:`-score_tag` option is used
   to specify another tag.

   The number of top scoring molecules outputted is controlled by the
   :option:`-hitlist_size` option (which has a default value of 500).

   .. note::

      If this flag is not set by the user the default filename (i.e., docked.oeb.gz)
      will be automatically prefixed with the setting of the
      :option:`-prefix` flag.

   [Aliases=**-docked_mol_file**,**-docked_file**,**-docked**,**-out**]

.. option:: -undocked_molecule_file <filename> [Default: undocked.oeb.gz]

   Specifies an output file in which to place molecules that could not be
   docked into the active site (this generally occurs when a molecule is
   too large to fit in the site, or unable to match user specified docking
   constraints).  The format of this file is determined by the filename
   extension.  The following output formats are supported.

   ======================= ===========================
   Format                  Extension                  
   ======================= ===========================
   OEBinary                .oeb                       
   ----------------------- ---------------------------
   SDF                     .sdf                       
   ----------------------- ---------------------------
   Isomeric SMILES         .ism                       
   ----------------------- ---------------------------
   Gzipped OEBinary        .oeb.gz                    
   ----------------------- ---------------------------
   Gzipped SDF             .sdf.gz                    
   ----------------------- ---------------------------
   Gzipped Isomeric Smiles .ism.gz                    
   ======================= ===========================

   .. note::

      If this flag is not set by the user the default filename (i.e., undocked.oeb.gz) 
      will be automatically prefixed with the setting of the
      :option:`-prefix` flag.

   [ Aliases = **-undocked_mol_file**, **-undocked_file**, **-undocked** ]



.. option:: -score_file <filename>   [Default: score.txt]

   Specifies a tab separated text file with the name and scores of the molecules.

   .. note::

      If this flag is not set by the user the default filename (i.e., score.txt) 
      will be automatically prefixed with the setting of the
      :option:`-prefix` flag.

   [ Aliases : **-score** ]



.. option:: -report_file <filename> [Default: report.txt]

   Specifies a file that a text report of the run will be written to.

   .. note::

      If this flag is not set by the user the default filename (i.e., report.txt)
      will be automatically prefixed with the setting of the
      :option:`-prefix` flag.

   [ Aliases : **-report** ]



.. option:: -settings_file <filename> [Default: settings.param]

   Writes the settings of all parameters of the run to the specified output
   file.  The settings will be listed in plain text with one parameter name
   follow by its value(s).  This format is compatible with the format of
   parameter files, and therefore a settings file from a previous run can be
   passed to the :option:`-param` flag to re-run the program with the same settings.

   .. note::

      If this flag is not set by the user the default filename (i.e., settings.param) 
      will be automatically prefixed with the setting of the 
      :option:`-prefix` flag.

   [ Aliases = **-settings** ]


.. option:: -status_file <filename> [Default: status.txt]

   If this parameter is set then the status of the run will be written to the given output
   file every few seconds (the previous contents of the file will be overwritten)
   during the run.

   .. note::

      If this flag is not set by the user the default filename (i.e., status.txt) 
      will be automatically prefixed with the setting of the 
      :option:`-prefix` flag.

   [ Aliases = **-status** ]



Output Options
--------------

.. option:: -hitlist_size <num>  [Default: 500]

   This parameter controls the number of top scoring molecules that will be 
   outputted at the end of the run (sorted by score), or can be used to 
   specify that all molecules should be outputted as they are processed (unsorted).

   If -hitlist_size is non-zero a sorted hitlist of the best scoring 
   molecules is produced that will be maintained and output at the end of the
   run.  The maximum size of the hitlist is :option:`-hitlist_size`.  If more
   than this number of molecules are in the input database only the top
   scoring molecules will be outputted and the rest will be discarded.

   If :option:`-hitlist_size` is zero the run will be in serial mode, *i.e.* each molecule
   will be outputted as it is processed (unsorted).  For single processor runs this
   will be the order the molecules appear in the database file(s).  For
   MPI runs the order will not be strictly the order the molecules appear in the
   database file(s).

   There is no formal limit on the number of molecules that can be sorted
   and outputted at the end of the run.  However, retaining a large
   number of molecules significantly increases the memory requirements.
   A good rule of thumb is that the setting :option:`-hitlist_size` times the
   setting of :option:`-num_poses` should not be larger than 10,000.

   [ Aliases = **-hitlist_size**, **-hitlist** ]



.. option:: -num_poses <num> [Default: 1]

   Specifies the maximum number of docked poses to output for each docked
   molecule.

   There is no formal limit on the number of poses per molecule that can be
   outputted, however, retaining a large number of alternate poses
   significantly increases the size of the molecules in memory and when
   outputted to disk.  A good rule of thumb is that the setting
   :option:`-hitlist_size` times the setting of :option:`-num_poses` should
   not be larger than 10,000.

   [ Aliases = **-numposes** ]



.. option:: -score_tag <score tag> [No Default]

   This parameter overrides the default SD data tag used to store molecule
   scores.

   [Aliases=**-scoretag**]

.. option:: -annotate_scores [Default: false]

   If the value of this flag is set to true VIDA score annotations will be added
   to the processed molecules.  These annotations are visible in VIDA (OpenEye's
   molecular visualization program) and show a per atom breakdown of the score.  

   .. note::

      The docked molecule output file format (see
      :option:`fred -docked_molecule_file`) must be OEBinary when using score
      annotations.

   [ Aliases = **-annotate** ]



.. option:: -save_component_scores    [Default: false]

   If the value of this flag is set to true individual components of the total
   score will be saved to SD data on each pose and appear in the score file (see
   :option:`-score_file`).

   [ Aliases = **-component_scores**, **-component** ]



.. option:: -no_extra_output_files [Default=false]

    When this flag is set to true the only default output to the program will be
    the docked structure file (see :option:`-docked_molecule_file`).

    Using this flag suppresses the default output of the following

    ====================== =============== ===================================
    Output                 Default         Parameter
    filename
    ====================== =============== ===================================
    Undocked molecule file undocked.oeb.gz :option:`-undocked_molecule_file`
    ---------------------- --------------- -----------------------------------
    Text score file        score.txt       :option:`-score_file`
    ---------------------- --------------- -----------------------------------
    Report file            report.txt      :option:`-report_file`
    ---------------------- --------------- -----------------------------------
    Settings file          fred.param      :option:`-settings_file`
    ---------------------- --------------- -----------------------------------
    Status file            status.txt      :option:`-status_file`
    ====================== =============== ===================================

    Only default output is suppressed.  If any of these output parameters are
    explicitly set by the users the relevant output file will still be written
    even if this switch is turned on.

   [Aliases=**-no_extra**,**-noextra**,**-noextraoutputfiles**,**-no_extra_output**,**-noextraoutput**]

.. option:: -no_dots [Default: false]

    When this flag is set to true, a dot is being written to standard 
    error for each docking molecule (or x in the case of a failure).
    Setting this flag to false to suppress dot/x writing.

   [ Aliases = **-nodots** ]



.. option:: -prefix <value> [Default=fred]

   This flag prefixes all default output filenames with the specified value.

   .. note::

      This flag does not affect output filenames explicitly set by the user.

.. option:: -nostructs [Default=false]

   When this flag is set to true, both the docked and undocked structure files
   will be suppressed. The flag overrides :option:`-docked_molecule_file` and
   :option:`-undocked_molecule_file`.


.. _chapter_hybrid:

HYBRID
======

.. toctree::
   :maxdepth: 2

   hybrid_overview
   hybrid_input
   hybrid_example
   hybrid_help
   hybrid_req_params
   hybrid_opt_params




.. _hybrid_overview:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: hybrid

======================
Overview
======================

:ref:`chapter_hybrid` is a docking program that also uses elements of ligand based
design to enhance performance.  Typically, the protein structure is
determined with X-ray crystallography in the presence of a known binding ligand
(or bound ligand).  The :ref:`chapter_hybrid` program uses the information present
in both the structure of the protein and the bound ligand to enhance docking
performance.   :ref:`chapter_hybrid` **requires that the structure of a bound ligand be
known**, if it is not known :ref:`chapter_fred` can then be used to do traditional docking.

:ref:`chapter_hybrid` also allows multiple structures/conformations of the target
protein to be used.  In this case :ref:`chapter_hybrid` will determined the best 
structure/conformation to use for each ligand in the docking database.


.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _hybrid_ligand_preparation:

===================
Input Preparation
===================

.. note ::

   It is not required to calculate the ligand charges and protein charges explicitly. The
   scoring functions do not utilize partial charges.

Ligand Preparation
------------------

The most common use of :ref:`chapter_hybrid` is to dock a large collection of molecules into the
active site of a target protein.  For the purposes of this document, we'll call
the file(s) of molecules the database file(s), or dbase file(s).  The most
common format for database file(s) is a multi-conformer OEBinary file created
by OpenEye's **OMEGA** program, however, this file can be one of several 3D formats.
These formats include SDF, MOL2 and PDB. :ref:`chapter_hybrid` determines the database file
format from the file extension, :file:`.sdf` or :file:`.mol` for SDF,
:file:`.mol2` for MOL2, :file:`.pdb` or :file:`.ent` for PDB. Gzip compressed
files of these same formats are allowed as well. :ref:`chapter_hybrid` will interpret
:file:`infile.sdf.gz` as a gzip'ed SDF file.

.. note::

   Note that even though all these formats are supported, using SDF, PDB or MOL2
   can result in a loss of speed due to the I/O penalty of these formats.

:ref:`chapter_hybrid` has no provision for conversion of 1D/2D molecules to 3D. **The database
file(s) must be in a conformationally expanded 3D format**.  Within the OpenEye
tool chain the program **OMEGA** can be used to convert 1D/2D to 3D and generate conformers.

By default :ref:`chapter_hybrid` will interpret conformers in the database file(s) as part of a
single multi-conformer molecule as long as they:

* Are contiguous in the input file.
* Have the same numbers of atoms and bonds in the same order
* Have identical atom and bond properties with their order
  correspondent in the subsequent connection table
* Have the same atom and bond stereochemistry

While this may appear to be a restrictive list, many programs write
multi-conformer molecules into SDF or MOL2 files such that the above rules
will be satisfied. If the conformers are named differently, (*i.e.* they
have a conformer number appended to the base name like acetsali_1,
acetsali_2), :ref:`chapter_hybrid` will still consider them part of a single multi-conformer
molecule if the criteria above are met.

Receptor Preparation
--------------------

.. note::

  Beginning with :ref:`chapter_hybrid` 4.0.0,  :ref:`chapter_hybrid` now only accepts an OEDU with receptor as the
  receptor input file.

:ref:`chapter_hybrid` can use either a single :ref:`receptor<receptor_theory>` or
multiple :ref:`receptors<receptor_theory>` each of which contains a different
structure/conformation of the target protein.  Each
:ref:`receptor<receptor_theory>` must also have a bound ligand.  Receptors
with bound ligands can be created with the following programs.

.. tabularcolumns:: |l|l|p{11cm}|

=======================================  ============  ==========================================
Program                                  Type          Description
=======================================  ============  ==========================================
:ref:`chapter_makereceptor`              GUI           Interactive GUI for creating a receptor.
---------------------------------------  ------------  ------------------------------------------
:ref:`ReceptorInDU`                      Command Line  Generates a receptor inside a prepared
                                                       OEDesignUnit in an OEDU file.
---------------------------------------  ------------  ------------------------------------------
:ref:`OEB2DUReceptor`                    Command Line  Converts a molecule based receptor OEB or
                                                       OEB.GZ file into a receptor inside
                                                       an OEDesignUnit, in an OEDU file
=======================================  ============  ==========================================

.. note::

   Receptors can also be created using the Docking Toolkit (see the Docking Toolkit
   documentation).


.. _hybrid_example:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: hybrid 

======================
Example Commands
======================

Basic Hybrid Docking Example
----------------------------

This example hybrid docks molecules using a single processor.

Input files for 1DWD

   * **receptor.oedu** : 
        A receptor file containing the structure of the target
        protein and a bound ligand.  (see :ref:`fred_receptor_preparation`
        section).

   * **multiconformer_ligands.oeb.gz** : 
        Conformationally expanded 3D ligands to dock.
        (see :ref:`fred_ligand_preparation` section).

Command line

      .. code-block:: bash

         prompt> hybrid -receptor receptor.oedu -dbase multiconformer_ligands.oeb.gz

Output files

   * **hybrid_docked.oeb.gz** :
     Top 500 scoring molecules of
     *multiconformer_ligands.oeb.gz* docked into *receptor.oedu*.

   * **hybrid_undocked.oeb.gz** : 
     Molecules of *multiconformer_ligands.oeb.gz* that could
     not be docked into the active site (generally occurs if the molecules are too
     big for the site).  This file will not be present if all molecules were
     successfully docked to the active site.

   * **hybrid_score.txt** : 
     A tab separated text file containing the name and score of each of
     the top 500 ligands.

   * **hybrid_report.txt** : 
     A text report of the docking process.

   * **hybrid_settings.param** : 
     A text file containing the parameters used for this run.

   * **hybrid_status.txt** : 
     A text file that is overwritten periodically during the run
     with the status of the run.

..  _hybrid_docking_with_multiple_crystal_structures:

Hybrid Docking with Multiple Crystal Structures
-----------------------------------------------

In this example :ref:`chapter_hybrid` docks molecules using multiple structures of the target
protein.

Input files for 2AA2 and 2AA7

   * **receptor1.oedu** : 
        A receptor file containing the structure of the target
        protein and a bound ligand.  (see :ref:`fred_receptor_preparation`
        section).

   * **receptor2.oedu** : 
        A receptor file containing the structure of the second target
        protein and a bound ligand.  This receptor file should have a different
        structure of the same target protein in *receptor1.oedu*, generally
        with a different bound ligand.  (see :ref:`fred_receptor_preparation`
        section).

   * **multiconformer_ligands.oeb.gz** : 
        Conformationally expanded 3D ligands to dock.
        (see :ref:`fred_ligand_preparation` section).

Command line

      .. code-block:: bash

         prompt> hybrid -receptor receptor1.oedu \
                        -receptor receptor2.oedu \
                        -dbase multiconformer_ligands.oeb.gz

Output files

   * **hybrid_docked.oeb.gz** : 
     Top 500 scoring molecules of
     *multiconformer_ligands.oeb.gz* docked into either *receptor1.oedu* or
     *receptor2.oedu*.  The title and filename of the receptor docked to will
     be tagged to the SD data of each docked ligand (see the *report.txt* file).

   * **hybrid_undocked.oeb.gz** : 
     Molecules of *multiconformer_ligands.oeb.gz* that could
     not be docked into the active site (generally occurs if the molecules are too
     big for the site).  This file will not be present if all molecules were
     successfully docked to the active site.

   * **hybrid_score.txt** : 
     A tab separated text file containing the following information for each of the
     top 500 ligands.

     * Name of the ligand
 
     * Score of the ligand
 
     * Title of the receptor site the ligand docked to.

     * Filename of the receptor site the ligand docked to.

   * **hybrid_report.txt** : 
     A text report of the docking process.

   * **hybrid_settings.param** : 
     A text file containing the parameters used for this run.

   * **hybrid_status.txt** : 
     A text file that is written periodically during the run
     with the status of the run.

MPI docking example
-------------------

In this example :ref:`chapter_hybrid` docks molecules to a single receptor on 4 processors of the host machine.

Input files

   * **receptor.oedu** : 
        A receptor file containing the structure of the target
        protein and a bound ligand.  (see :ref:`fred_receptor_preparation`
        section).

   * **multiconformer_ligands.oeb.gz** : 
        Conformationally expanded ligands to dock.
        (see :ref:`fred_ligand_preparation` section).

Command line

      .. code-block:: bash

         prompt> hybrid -mpi_np 4 -receptor receptor.oedu \
                                       -dbase multiconformer_ligands.oeb.gz

Output files

   * **hybrid_docked.oeb.gz** : 
     Top 500 scoring molecules of
     *multiconformer_ligands.oeb.gz* docked into *receptor.oedu*.

   * **hybrid_undocked.oeb.gz** : 
     Molecules of *multiconformer_ligands.oeb.gz* that could
     not be docked into the active site (generally occurs if the molecules are too
     big for the site).  This file will not be present if all molecules were
     successfully docked to the active site.

   * **hybrid_score.txt** : 
     A tab separated text file containing the name and score of each of
     the top 500 ligands.

   * **hybrid_report.txt** : 
     A text report of the docking process.

   * **hybrid_settings.param** : 
     A text file containing the parameters used for this run.

   * **hybrid_status.txt** : 
     A text file that is overwritten periodically during the run
     with the status of the run.

.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _hybrid_help:

.. program:: hybrid 

======================
Command Line Help 
======================

A description of the command line interface can be obtained by executing **HYBRID**
with the `--help` option.

.. code-block:: console
   
   > hybrid --help

will generate the following output:

::

   Help functions:
     hybrid --help simple      : Get a list of simple parameters
     hybrid --help all         : Get a complete list of parameters
     hybrid --help defaults    : List the defaults for all parameters
     hybrid --help <parameter> : Get detailed help on a parameter
     hybrid --help html        : Create an html help file for this program
     hybrid --help versions    : List the toolkits and versions used in the application


.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _hybrid_req_params:

.. program:: hybrid 

======================
Required Parameters
======================

.. option:: -receptor <receptor file1> [<receptor file2> ...]

   Receptor file(s) to dock to. Each receptor must have a bound ligand and must
   be in OEDocking receptor format (``.oedu``).

   If multiple receptors are specified each docking ligand will be docked into the
   single receptor with the bound ligand most similar to it, as measured by 3D
   shape and chemical similarity.

   [Aliases=**-rec**]

.. option:: -dbase <input filename1> [<input filename2> ...]

   File(s) containing conformationally expanded ligands to dock (see section 
   :ref:`hybrid_ligand_preparation`).
   
   The following file formats are supported.

   ============ ===========================
   File type    Extension                  
   ============ ===========================
   OEBinary     .oeb .oeb.gz               
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz  
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz             
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz  
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz             
   ============ ===========================

   More than one file can be specified.

   [Aliases=**-database**,**-in**]


.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _hybrid_opt_params:

.. program:: hybrid

======================
Optional Parameters
======================

Input Options
--------------

.. option:: -param <parameter filename>    [No Default]

   A parameter file is a text file that lists parameter settings to be used
   during a run.   If a parameter is specified both on the command line and in
   the parameter file, the value specified on the command line is used.

   The format of the parameter file is as follows:

   * One parameter per line

   * For non-list parameters one key-value pair per line. (*e.g., -receptor rec.oedu*).

   * For list parameters a key followed by all the values (*e.g., -dbase lig1.oeb.gz ligs2.oeb.gz*)

   * Boolean parameters must be listed as a key followed by true or false (*e.g. -annotate_poses true*).

   * The parameter file may not contain the :option:`-param` parameter.

   * Lines beginning with # are considered comments



.. option:: -molnames <input filename>    [No Default]

   This parameter specifies a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set then only molecules in the
   database file(s) (see parameter :option:`-dbase`) with names that match those
   in the text files will be read in.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecule(s) that are contained in a large database, without
   having to extract those molecules by hand from the database.



Dock Options
------------

.. option:: -dock_resolution <setting> [Default: Standard]

   The parameter controls the resolution of the docking both during the exhaustive
   search and the optimization.  The resolution of the exhaustive search at each setting
   is as follows.

   =========   ================  ===================
   Setting     Translational     Rotational         
               Stepsize          Stepsize           
   =========   ================  ===================
   High        1.0 Ångström      1.0 Ångström      
   ---------   ----------------  -------------------
   Standard    1.0 Ångström      1.5 Ångströms      
   ---------   ----------------  -------------------
   Low         1.5 Ångströms     2.0 Ångströms      
   =========   ================  ===================
   
   During the optimization step the resolution is half that of the exhaustive search.

   [ Aliases = **-res** ]

   .. seealso::

      * :ref:`OEDocking::OEDockOptions::SetResolution <OEDocking_OEDockOptions_SetResolution>` in the **OEDocking TK** manual.


Output Files
--------------

.. option:: -docked_molecule_file <filename>   [Default=docked.oeb.gz]

   File docked molecules will be written to.  The file format is
   controlled by the extension of the filename.  The following output
   formats are supported.

   ================ ===========================
   Format           Extension
   ================ ===========================
   OEBinary         .oeb
   ---------------- ---------------------------
   SDF              .sdf
   ---------------- ---------------------------
   Gzipped OEBinary .oeb.gz
   ---------------- ---------------------------
   Gzipped SDF      .sdf.gz
   ================ ===========================

   Scores will be attached as SD data to each pose with the tag
   **HYBRID Chemgauss4 Score**, unless the :option:`-score_tag` option is used
   to specify another tag.

   By default all docked molecules will be outputted in the order in which they
   were docked.  Molecules can also be outputted in sorted order by using the
   :option:`-hitlist_size` option.

   .. note::

      If this flag is not set by the user the default filename (i.e., docked.oeb.gz)
      will be automatically prefixed with the setting of the
      :option:`-prefix` flag.

   [Aliases=**-docked_mol_file**,**-docked_file**,**-docked**,**-out**]

.. option:: -undocked_molecule_file <filename> [Default: undocked.oeb.gz]

   Specifies an output file in which to place molecules that could not be
   docked into the active site (this generally occurs when a molecule is
   too large to fit in the site, or unable to match user specified docking
   constraints).  The format of this file is determined by the filename
   extension.  The following output formats are supported.

   ======================= ===========================
   Format                  Extension                  
   ======================= ===========================
   OEBinary                .oeb                       
   ----------------------- ---------------------------
   SDF                     .sdf                       
   ----------------------- ---------------------------
   Isomeric SMILES         .ism                       
   ----------------------- ---------------------------
   Gzipped OEBinary        .oeb.gz                    
   ----------------------- ---------------------------
   Gzipped SDF             .sdf.gz                    
   ----------------------- ---------------------------
   Gzipped Isomeric Smiles .ism.gz                    
   ======================= ===========================

   .. note::

      If this flag is not set by the user the default filename (i.e., undocked.oeb.gz) 
      will be automatically prefixed with the setting of the
      :option:`-prefix` flag.

   [ Aliases = **-undocked_mol_file**, **-undocked_file**, **-undocked** ]



.. option:: -score_file <filename>   [Default: score.txt]

   Specifies a tab separated text file with the name and scores of the molecules.

   .. note::

      If this flag is not set by the user the default filename (i.e., score.txt) 
      will be automatically prefixed with the setting of the
      :option:`-prefix` flag.

   [ Aliases : **-score** ]



.. option:: -report_file <filename> [Default: report.txt]

   Specifies a file that a text report of the run will be written to.

   .. note::

      If this flag is not set by the user the default filename (i.e., report.txt)
      will be automatically prefixed with the setting of the
      :option:`-prefix` flag.

   [ Aliases : **-report** ]



.. option:: -settings_file <filename> [Default: settings.param]

   Writes the settings of all parameters of the run to the specified output
   file.  The settings will be listed in plain text with one parameter name
   follow by its value(s).  This format is compatible with the format of
   parameter files, and therefore a settings file from a previous run can be
   passed to the :option:`-param` flag to re-run the program with the same settings.

   .. note::

      If this flag is not set by the user the default filename (i.e., settings.param) 
      will be automatically prefixed with the setting of the 
      :option:`-prefix` flag.

   [ Aliases = **-settings** ]


.. option:: -status_file <filename> [Default: status.txt]

   If this parameter is set then the status of the run will be written to the given output
   file every few seconds (the previous contents of the file will be overwritten)
   during the run.

   .. note::

      If this flag is not set by the user the default filename (i.e., status.txt) 
      will be automatically prefixed with the setting of the 
      :option:`-prefix` flag.

   [ Aliases = **-status** ]



Output Options
--------------

.. option:: -hitlist_size <num>  [Default: 500]

   This parameter controls the number of top scoring molecules that will be 
   outputted at the end of the run (sorted by score), or can be used to 
   specify that all molecules should be outputted as they are processed (unsorted).

   If -hitlist_size is non-zero a sorted hitlist of the best scoring 
   molecules is produced that will be maintained and output at the end of the
   run.  The maximum size of the hitlist is :option:`-hitlist_size`.  If more
   than this number of molecules are in the input database only the top
   scoring molecules will be outputted and the rest will be discarded.

   If :option:`-hitlist_size` is zero the run will be in serial mode, *i.e.* each molecule
   will be outputted as it is processed (unsorted).  For single processor runs this
   will be the order the molecules appear in the database file(s).  For
   MPI runs the order will not be strictly the order the molecules appear in the
   database file(s).

   There is no formal limit on the number of molecules that can be sorted
   and outputted at the end of the run.  However, retaining a large
   number of molecules significantly increases the memory requirements.
   A good rule of thumb is that the setting :option:`-hitlist_size` times the
   setting of :option:`-num_poses` should not be larger than 10,000.

   [ Aliases = **-hitlist_size**, **-hitlist** ]



.. option:: -num_poses <num> [Default: 1]

   Specifies the maximum number of docked poses to output for each docked
   molecule.

   There is no formal limit on the number of poses per molecule that can be
   outputted, however, retaining a large number of alternate poses
   significantly increases the size of the molecules in memory and when
   outputted to disk.  A good rule of thumb is that the setting
   :option:`-hitlist_size` times the setting of :option:`-num_poses` should
   not be larger than 10,000.

   [ Aliases = **-numposes** ]



.. option:: -score_tag <tag> [No Default]

   This parameter overrides the default SD Data Tag used to store molecule
   scores (the default is **HYBRID Chemgauss4 Score**).

   [Aliases=**-scoretag**]

.. option:: -annotate_scores [Default: false]

   If the value of this flag is set to true VIDA score annotations will be added
   to the processed molecules.  These annotations are visible in VIDA (OpenEye's
   molecular visualization program) and show a per atom breakdown of the score.  

   .. note::

      The docked molecule output file format (see
      :option:`fred -docked_molecule_file`) must be OEBinary when using score
      annotations.

   [ Aliases = **-annotate** ]



.. option:: -save_component_scores    [Default: false]

   If the value of this flag is set to true individual components of the total
   score will be saved to SD data on each pose and appear in the score file (see
   :option:`-score_file`).

   [ Aliases = **-component_scores**, **-component** ]



.. option:: -no_extra_output_files    [Default=false]

    When this flag is set to true the only default output to the program will be
    the docked structure file (see :option:`-docked_molecule_file`).

    Using this flag suppresses the default output of the following

    ====================== =============== ===================================
    Output                 Default         Parameter
                           filename
    ====================== =============== ===================================
    Undocked molecule file undocked.oeb.gz :option:`-undocked_molecule_file`
    ---------------------- --------------- -----------------------------------
    Text score file        score.txt       :option:`-score_file`
    ---------------------- --------------- -----------------------------------
    Report file            report.txt      :option:`-report_file`
    ---------------------- --------------- -----------------------------------
    Settings file          hybrid.param    :option:`-settings_file`
    ---------------------- --------------- -----------------------------------
    Status file            status.txt      :option:`-status_file`
    ====================== =============== ===================================

    Only default output is suppressed.  If any of these output parameters are
    explicitly set by the users the relevant output file will still be written
    even if this switch is turned on.

   [Aliases=**-no_extra**,**-noextra**,**-noextraoutputfiles**,**-no_extra_output**,**-noextraoutput**]

.. option:: -no_dots [Default: false]

    When this flag is set to true, a dot is being written to standard 
    error for each docking molecule (or x in the case of a failure).
    Setting this flag to false to suppress dot/x writing.

   [ Aliases = **-nodots** ]



.. option:: -prefix <value>    [Default=hybrid]

   This flag prefixes all default output filenames with the specified value.

   .. note::

      This flag does not affect output filenames explicitly set by the user.

.. option:: -nostructs [Default=false]

   When this flag is set to true, both the docked and undocked structure files
   will be suppressed. The flag overrides :option:`-docked_molecule_file` and
   :option:`-undocked_molecule_file`.



.. _chapter_posit:

POSIT
=====

.. toctree::
   :maxdepth: 2

   posit_overview
   posit_input
   posit_example
   posit_help
   posit_req_params
   posit_opt_params


.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _posit_overview:

.. program:: posit

======================
Overview
======================

**POSIT** works best when fitting to a collection of co-crystal
ligands, however, it can be used for a single ligand targets.  Each
pose that **POSIT** generates is analyzed with a simple heuristic and
marked with a probability (seen below).

The structures output by **POSIT** are annotated with information about
the best-fit receptor and with various metrics describing the details
of the pose.  These details are stored in SDDATA and can be viewed
with most molecular structure viewers.  

The details are as follows:

   ======================= ======================================================
   Name                    Description
   ======================= ======================================================
   Docking Input Order     The input order from the original file
   ----------------------- ------------------------------------------------------
   Result                  GREAT, GOOD, MEDIOCRE or POOR detailing the quality 
                           of the result
   ----------------------- ------------------------------------------------------
   POSIT receptor title    the name of the receptor (taken from the original 
                           protein)
   ----------------------- ------------------------------------------------------
   POSIT receptor filename the filename of the original receptor
   ----------------------- ------------------------------------------------------
   POSIT::Probability      Estimated probability of being within 2 |Angstrom| 
                           RMSD of the real structure (assuming binding)
   ----------------------- ------------------------------------------------------
   POSIT::Method           The underlying method used (SHAPEFIT, HYBRID, FRED)
   ----------------------- ------------------------------------------------------
   Dock Type               The docking type used (which is *POSIT* in this case)
   ======================= ======================================================

These values are also written to the report file in a tab separated format, see :option:`-prefix` 
for details.

The probability that the computed pose is a correct pose is generated
as described in :ref:`the section about estimated pose probability <posit_algorithm>`.

The values in the Result field are as follows:

   ============   =======================================================================
   Result         Meaning 
   ============   =======================================================================
   GREAT          Computed pose is likely (75%-100%) probability) to be within 2.0 |A| of
                  experimentally-derived pose.
   ------------   -----------------------------------------------------------------------
   GOOD           Computed pose may be (50%-75%) probability) to be within 2.0 |A| of
                  experimentally-derived pose.
   ------------   -----------------------------------------------------------------------
   MEDIOCRE       Take with a grain of salt (33%-50%) probability)
   ------------   -----------------------------------------------------------------------
   POOR           Take with a huge grain of salt (<33% probability)
   ============   =======================================================================

By default, **POOR** poses are not written out, they are rejected as unsuitable.
The number of rejected molecules is recorded in the status file.


.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _posit_ligand_preparation:

===================
Input Preparation
===================

Ligand Preparation
------------------

The most common use of :ref:`chapter_posit` is to dock molecules into the
active site of a target protein.  For the purposes of this document, we'll call
the file(s) of molecules the database file(s), or dbase file(s).  The most
common format for database file(s) is a multi-conformer OEBinary file created
by OpenEye's **OMEGA** program, however, this file can be one of several 3D formats.
These formats include SDF, MOL2 and PDB. :ref:`chapter_posit` determines the database file
format from the file extension, :file:`.sdf` or :file:`.mol` for SDF,
:file:`.mol2` for MOL2, :file:`.pdb` or :file:`.ent` for PDB. Gzip compressed
files of these same formats are allowed as well. :ref:`chapter_posit` will interpret
:file:`infile.sdf.gz` as a gzip'ed SDF file.

.. note::

   Note that even though all these formats are supported, using SDF, PDB or MOL2
   can result in a loss of speed due to the I/O penalty of these formats.

:ref:`chapter_posit` internally generates 3D conformations **OMEGA**  if a 1D/2D molecule is supplied.

By default :ref:`chapter_posit` will interpret conformers in the database file(s) as part of a
single multi-conformer molecule as long as they:

* Are contiguous in the input file.
* Have the same numbers of atoms and bonds in the same order
* Have identical atom and bond properties with their order
  correspondent in the subsequent connection table
* Have the same atom and bond stereochemistry

While this may appear to be a restrictive list, many programs write
multi-conformer molecules into SDF or MOL2 files such that the above rules
will be satisfied. If the conformers are named differently, (*i.e.* they
have a conformer number appended to the base name like acetsali_1,
acetsali_2), :ref:`chapter_posit` will still consider them part of a single multi-conformer
molecule if the criteria above are met.

Receptor Preparation
--------------------

.. note::

  Beginning with :ref:`chapter_posit` 4.0.0,  :ref:`chapter_posit` now only accepts an OEDU with receptor as the
  receptor input file.

:ref:`chapter_posit` can use either a single :ref:`receptor<receptor_theory>` or
multiple :ref:`receptors<receptor_theory>` each of which contains a different
structure/conformation of the target protein.  Each
:ref:`receptor<receptor_theory>` must also have a bound ligand.  Receptors
with bound ligands can be created with the following programs.

.. tabularcolumns:: |l|l|p{11cm}|

=======================================  ============  ==========================================
Program                                  Type          Description
=======================================  ============  ==========================================
:ref:`chapter_makereceptor`              GUI           Interactive GUI for creating a receptor.
---------------------------------------  ------------  ------------------------------------------
:ref:`ReceptorInDU`                      Command Line  Generates a receptor inside a prepared
                                                       OEDesignUnit in an OEDU file.
---------------------------------------  ------------  ------------------------------------------
:ref:`OEB2DUReceptor`                    Command Line  Converts a molecule based receptor OEB or
                                                       OEB.GZ file into a receptor inside
                                                       an OEDesignUnit, in an OEDU file
=======================================  ============  ==========================================

.. note::

   Receptors can also be created using the Docking Toolkit (see the :ref:`Docking Toolkit<oedocking_chapter_intro>`
   documentation). Since **POSIT** can generate poses using various methods, constraints present 
   in the receptor may or may not play any role for the specific pose generation. Constraints 
   only affect the generated pose when ``FRED`` or ``HYBRID`` is the underlying method.


.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _posit_example:

.. program:: posit

======================
Example Commands
======================

**POSIT** always requires a bound-ligand in a receptor to fit against and
an output file.  The ligand (or ligands) to fit is specified with the :option:`-dbase`
option or the :option:`-in` option, and the structures to fit are specified with
:option:`combine_receptors -receptors`.  Multiple receptors can be input at a time, in fact this is the
preferred mode of running **POSIT**.

.. note::

   :option:`-dbase` accepts only 3D molecules, normally generated by **OMEGA**.

   :option:`-in`  accepts most formats and generates 3D conformations when
   applicable.  When in doubt, use the :option:`-in` option.

Basic Usage
-----------

The basic form of running **POSIT** is to fit against multiple receptors.  The
best fit receptor will be chosen for the final pose.  Assuming that you have made
receptors and combined them as shown above:

.. code-block:: console

   > posit -receptors renin/receptors/*.oedu renin/merged/*.oedu -in renin/all.smi \
            -docked_molecule_file results.oedu

.. note::

 On *Microsoft Windows* systems, you need to expand the wildcard:

  .. code-block:: console

     > posit -receptor renin\receptors\2IL2_b.rec.oedu renin\receptors\2IL2_a.rec.oedu \
           renin\receptors\2IL2_c.rec.oedu renin\receptors\2IKO.rec.oedu \
           renin\receptors\2IKU_a.rec.oedu renin\receptors\2IKU_b.rec.oedu \
           renin\merged\2IKU_a.rec._merge_2IKO.rec.oedu renin\merged\2IKO.rec._merge_2IKU_a.rec.oedu \
           -in renin\all.smi -docked_molecule_file results.oedu

All results are written to the specified output file.

Any predicted ligand that has a good probability but clashes with the
protein will either be ignored or, if the :option:`-clashed_molecule_file` output is
specified on the command line, it will be output to the specified file.

.. code-block:: console

   > posit -receptors renin/receptors/*.oedu renin/merged/*.oedu -in renin/all.smi \
            -docked_molecule_file results.oedu -clashed_molecule_file clashed.smi

Ignoring Nitrogen Stereo
------------------------

By default, :program:`POSIT` ignores nitrogen stereo to make it easier to dock input x-ray models
which may be time-averaged resulting in planar nitrogens.

If desired, this flag can be set to false in order to only fit explicit nitrogen stereo:

.. code-block:: console

  > posit -receptors renin/receptors/*.oedu renin/merged/*.oedu -in all.smi \
            -docked_molecule_file results.oedu -ignore_nitrogen_stereo false

.. note::

  *POSIT 1.0* defaulted to not ignoring nitrogen stereo.  This was changed
  due to the nature of crystallographic structures tending to produce
  time-averaged planar nitrogens.

Sometimes you may see warnings like the following:

::

 Warning: Input stereochemistry different from output after fitting
 in: CCc1c(c(nc([nH+]1)N)N)c2ccc3c(c2)N(CCC3)CCCOC
 out: CCc1c(c(nc([nH+]1)N)N)c2ccc3c(c2)[N@](CCC3)CCCOC
 Warning: Input stereochemistry different from output after fitting
 in: CCc1c(c(nc([nH+]1)N)N)c2ccc3c(c2)N(CCC3)CCCOC
 out: CCc1c(c(nc([nH+]1)N)N)c2ccc3c(c2)[N@@](CCC3)CCCOC

These simply serve as a warning that stereochemistry was added or
modified during the fitting/optimization process.

Advanced Usage
--------------

To run **POSIT** on absolutely everything and not worry about clashes or
probabilities:

.. code-block:: console

   > posit -receptors renin/receptors/*.oedu -in renin/all.smi \
    -docked_molecule_file results.oedu  -outputall

This runs **POSIT** and outputs all docked molecules regardless of score in the
order they exist in the input file.


.. _posit_help:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: posit

======================
Command Line Help 
======================

A description of the command line interface can be obtained by executing :program:`POSIT`
with the `--help` option.

.. code-block:: console
   
   > posit --help

will generate the following output:

::

   Help functions:
     posit --help simple      : Get a list of simple parameters
     posit --help all         : Get a complete list of parameters
     posit --help defaults    : List the defaults for all parameters
     posit --help <parameter> : Get detailed help on a parameter
     posit --help html        : Create an html help file for this program
     posit --help versions    : List the toolkits and versions used in the application

.. _posit_req_params:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: posit

======================
Required Parameters
======================

.. option:: -receptor <filenames>

   List of receptors used to predict the pose of the input molecules.
   Receptors must include a bound ligand.

   Multiple receptors can be input:

   .. code-block:: console

      > posit -receptor rec*.oedu

   Will use all files that start with rec and end with ``.oedu``.

   .. code-block:: console

      > posit -receptor  receptors.lst

   Will use all receptors files specified in the receptors.lst file.
   If any entry in the specified file is not a valid receptor, :program:`POSIT`
   will halt.

   Supported :option:`-receptor` file formats are:

   ============   ===========================
   File type      Extension 
   ============   ===========================
   OEDesignUnit    .oedu
   ------------   ---------------------------
   list            .lst
   ============   ===========================

   Multiple receptor files and list files can be used simultaneously.

   [Aliases=**-rec**,**-receptors**]

.. option:: -in <filename>

   Input molecules to pose-predict.  If 3D molecules are input, the 
   original conformations are retained for optimization as well
   as the expanded conformational ensemble. 

   [Aliases=**-lig**]

   **POSIT** uses an internal conformation sampling to generate
   high-quality conformations.  However, input ring structures (chair/boat)
   may not be reproduced as **POSIT** may choose a lower energy ring template
   during the sampling process.

   Supported input file formats are:

    ============   ===========================
    File type      Extension 
    ============   ===========================
    OEBinary       .oeb .oeb.gz
    ------------   ---------------------------
    SDF            .sdf .mol .sdf.gz .mol.gz
    ------------   ---------------------------
    MOL2           .mol2 .mol2.gz
    ------------   ---------------------------
    PDB            .pdb .ent .pdb.gz .ent.gz     
    ------------   ---------------------------
    MacroModel     .mmod .mmod.gz
    ------------   ---------------------------
    Smiles         .smi .smi.gz .ism.gz
    ============   ===========================


.. _posit_opt_params:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: posit

======================
Optional Parameters
======================

Input Options
-------------

.. option:: -dbase <filename>

   Input molecules to pose-predict.  3D molecules must be input as
   conformational expansion is not performed prior to fitting.

   :option:`-dbase` is the fastest way to
   run **POSIT** on large datasets. The expected input is a
   pre-generated database of **OMEGA**
   generated conformers.

   .. code-block:: console

     > omega2 -in renin/all.smi -out all.oeb.gz -rangeIncrement 1 \
        -maxConfRange 200,200,300,400,500,600,700,800,900,1000,1100,1200,1300,1400,1500,1600

     > posit -receptor receptor.oedu -dbase all.oeb.gz

   Supported input file formats are:

    ============   ===========================
    File type      Extension
    ============   ===========================
    OEBinary       .oeb .oeb.gz
    ------------   ---------------------------
    SDF            .sdf .mol .sdf.gz .mol.gz
    ------------   ---------------------------
    MOL2           .mol2 .mol2.gz
    ------------   ---------------------------
    PDB            .pdb .ent .pdb.gz .ent.gz
    ============   ===========================

   [Aliases=**-db**,**-database**]

.. option:: -molnames

      This flag specifies a text file with the names of one or more molecules in
      supplied to the :option:`-dbase` flag.  If specified, only molecules with matching
      names will be read by the :option:`-dbase` flag.  If this flag is not specified all
      molecules will be read normally.  Molecules names should be listed one per line.

      The general purpose of this flag is to provide an easy mechanism for reading
      a few specific molecules that are contained in a large database, without
      having to extract those molecules by hand from the database.

Multiprocessing Options
-----------------------

Execute Options
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -param

   The argument for this flag is the name of a
   file containing control parameters.  The control parameter file acts
   to either replace or augment the command line interface.  All
   parameters necessary for program execution may be provided in the
   control parameter file, although any command given explicitly on the
   command line will supersede options found in the parameter file.
   The application generates a new parameter file containing the full set of
   execution parameters upon every execution.  The name of the
   parameter file is created by combining the prefix
   base name with the *'.param'* extension.

.. option:: -mpi_np <n>

   Specifies the number of processors ``n`` when the application is run in MPI mode.

.. option:: -mpi_hostfile <filename>

   Specifies the name of the file containing processors configuration. For every host
   this file should contain a line ``host_name slots=n`` where ``n`` is the number of
   processors on the host.



Dock Options
------------

.. option:: -ignore_nitrogen_stereo

   When examining the ligands to pose predict for stereo, ignore any
   missing nitrogen chirality.  (This is normally caused by time
   averaging of crystal structures).

   When expanding stereo, nitrogen stereo centers will not be assigned.

   **POSIT** now always expands missing stereo.

   .. note::

      **POSIT** may complain about stereo centers being changed by the
      optimization, this is more likely when ignoring nitrogen stereo
      centers since the optimization may decide a different stereo
      configuration is optimal.

   [Default=true]

   [Aliases=**-ignoreNitrogenStereo**]

   .. seealso::

      * :ref:`OEDocking::OEPositOptions::SetIgnoreNitrogenStereo <OEDocking_OEPositOptions_SetIgnoreNitrogenStereo>` in the **OEDocking TK** manual.

.. option:: -minimum_probability

   Minimum probability for poses of interest. **POSIT** only outputs poses
   that has the minimum required probability.  To output all poses,
   set :option:`-minimum_probability` to 0.

   [Default=0.33]

   [Aliases=**-minProbability**]

   .. seealso::

      * :ref:`OEDocking::OEPositOptions::SetMinProbability <OEDocking_OEPositOptions_SetMinProbability>` in the **OEDocking TK** manual.

.. option:: -allowed_clashes

   Clashes allowed in the generated poses. There are three levels:

   =============   ===========================================
   Allowed Clash   Description
   =============   ===========================================
   noclashes       No clashes are allowed.
                   Actually there is a little wiggle room here
                   less than 0.2 |A| penetration is not
                   considered a clash.
   -------------   -------------------------------------------
   mildclashes     Clashes involving hydrogen are allowed, but
   hclashes        those between heavy atoms are disallowed.
   -------------   -------------------------------------------
   allclashes      All clashes are allowed.
   =============   ===========================================

   All poses that are accepted by the probability calculation yet clash with
   the protein are written to the fail file (if specified).

   [Default=mildclashes]

   [Aliases=**-allowedClashes**]

   .. seealso::

      * :ref:`OEDocking::OEPositOptions::SetAllowedClashType <OEDocking_OEPositOptions_SetAllowedClashType>` in the **OEDocking TK** manual.

.. option:: -relax

   Flag indicating if post pose prediction relaxation should be performed. The
   relaxation is performed by allowing flexibility to the ligand and parts of
   the receptor. Turning on relaxation can significantly slow down the calculations.
   There are three options:

   =============   ===========================================
   Relax Mode      Description
   =============   ===========================================
   none            No relaxation is performed.
   -------------   -------------------------------------------
   clashed         Relaxation is performed on poses that
                   contains clashes.
   -------------   -------------------------------------------
   all             Relaxation is performed on all poses.
   =============   ===========================================

   [Default=none]

   .. seealso::

      * :ref:`OEDocking::OEPositOptions::SetPoseRelaxMode <OEDocking_OEPositOptions_SetPoseRelaxMode>` in the **OEDocking TK** manual.

.. option:: -num_poses

   Number of alternative poses to be generated for each docked molecule.  The default
   is to only generate a single most probable pose.

   [Default=1]

   [Aliases=**-numposes**]

.. option:: -best_Receptor_Pose_Only

   If this flag set to ``false`` the pose prediction is performed using all of the
   receptors and the best set of poses from all of the receptors combined is provided
   as the results. With the default setting of ``true`` pose prediction is only performed
   on the ``best receptor`` for any given ligand. Note that, setting the flag to ``false``
   could increse the runtime significantly depending on the number of receptors used
   for the calculation.

   [Default=true]

   [Aliases=**-bestReceptorPoseOnly**]

   .. seealso::

      * :ref:`OEDocking::OEPositOptions::SetBestReceptorPoseOnly <OEDocking_OEPositOptions_SetBestReceptorPoseOnly>` in the **OEDocking TK** manual.

Output File Options
-------------------

**POSIT** writes docked structure results to a single file,
:option:`-docked_molecule_file` -- Ligand only output in one file.

By default, not all poses may be written to the output, to see
where ligands were placed, consult the log file for more details.
To control this behavior use the :option:`-outputall` flag, which
writes all output to the file specified by :option:`-docked_molecule_file` in order
of input molecule.

.. option:: -docked_molecule_file <filename>

   If specified, this flag overrides the default name of the docked molecule
   output file.  Only .oedu, .oeb, and .oeb.gz formats are allowed. An .oedu
   file is generated by default, and is the preferred output format.

   .. note::

      The default file is posit_docked.oedu, or
      <-prefix>_docked.oedu if the :option:`-prefix` flag is specified.

   Ligands are written to the output file based on the desired
   sort order (see the :option:`flynn -sortBy` flag).

   [Aliases=**-docked_mol_file**,**-docked_file**,**-docked**,**-out**]

.. option:: -undocked_molecule_file

    If specified this flag overrides the default name for the undocked molecule
    file.

    .. note::

       The default filename is posit_undocked.oeb.gz, or
       <-prefix>_undocked.oeb.gz if :option:`-prefix` is specified.

   [Aliases=**-undocked_mol_file**,**-undocked_file**,**-undocked**]

.. option:: -score_file

    If specified overrides the default name of the output text file containing
    the scores of the docked molecules.

    .. note::

       The default filename is posit_score.txt or <-prefix>_score.txt if the
       :option:`-prefix` flag is specified.

   [Aliases=**-scorefile**,**-score**]

.. option:: -report_file

    If specified  overrides the default output filename for the report file.

    .. note::

       The default filename for the report file is posit_report.txt or
       <-prefix>_report.txt if the :option:`-prefix` flag is specified.

   [Aliases=**-report**]

.. option:: -status_file

    If specified overrides the default filename for the status file.

    .. note::

       The default status file name is posit_status.txt or
       <-prefix>_status.txt if the :option:`-prefix` flag is specified.

   [Aliases=**-statusfile**,**-status**]

.. option:: -rejected_file

    If specified overrides the default filename for the reject file.

    The reject file is a tab separated file containing the
    input ligand number, the ligand title and the reason for
    the ligand being undocked.

    Example output:

    .. code-block:: none

       Ligand #        Title#Status
       0       lig1    No conformers above minimum probability
       1       lig2    No conformers above minimum probability
       2       lig3    No conformers above minimum probability
       3       lig4    No conformers above minimum probability

    .. note::

       The default status file name is posit_rejected.txt or
       <-prefix>_rejected.txt if the :option:`-prefix` flag is specified.

   [Aliases=**-rejected**]

.. option:: -settings_file

    If specified overrides the default output filename for the setting file.

    .. note::

       The default settings filename is posit_settings.param or
       <-prefix>_settings.param if the :option:`-prefix` flag is specified.

   [Aliases=**-settingsfile**,**-settings**]

.. _clash_file:

.. option:: -clashed_molecule_file <filename>

   Occasionally **POSIT** rejects ligands that probably have the correct binding mode
   but also display uncorrectable clashes.  If this
   flag is set, clashed molecules will be written to this file in no specific
   output order.

   It is important to be aware that because these are likely binding
   modes there is a chance that the clashed poses are still correct but the
   protein has reconfigured to accept the clashed pose.

   [Aliases=**-clashed_mol_file**,**-clashed_file**,**-clashed**,**-clash**]

Output Options
--------------

.. option:: -score_tag

   Overrides the default tag used to attach the score to the
   output molecules

   [Aliases=**-scoretag**]

.. option:: -no_extra_output_files

   Suppress the default output of the score, status,
   settings, report and undocked files.

   [Aliases=**-no_extra**,**-noextra**,**-noextraoutputfiles**,**-no_extra_output**,**-noextraoutput**]

.. option:: -no_dots

   Suppress writing a dot (.) to standard error for each docking
   molecule (or *x* in the case of a failure).

   [Aliases=**-nodots**]

.. option:: -prefix

   The text passed to this parameter will be preappended to all
   default output filenames (it does not affect output filenames explicitly
   set by the users).

   [Default=posit]

.. option:: -outputall

   Shorthand to write all output including clashed or nonprobable molecules.

.. option:: -verbose

   Set verbose output for logging.

   [Default=false]


.. _chapter_makereceptor:

Make Receptor
==============

.. toctree::
   :maxdepth: 2

   make_receptor_overview
   make_receptor_gui_layout
   make_receptor_setup



.. _make_receptor_overview:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: make_receptor

Overview
=============

**Make Receptor** is a graphical utility for creating or modifying a
:ref:`receptor<receptor_theory>`.  :ref:`Receptors<receptor_theory>` are
specialized design unit (OEDU) files used by :ref:`chapter_fred` and 
:ref:`chapter_hybrid` that contain the location and shape of the active site,
and optionally the docking constraints.

Receptors can also be created using the :ref:`SPRUCE <chapter_spruce>` and 
:ref:`ReceptorInDU` command line utilities.  These utilities create
receptors with default settings with fairly minimal user input and are generally
very effective.

.. note::

   Receptors created with the command line utilities can be edited with the
   **Make Receptor** GUI.

**Make Receptor** provides the users with more control over the receptor
creation process than the command line utilities, as well as a way to visualize
all the information contained in a receptor.  The following capabilities
of the **Make Receptor** program are either unavailable or difficult to execute
from the command line tools.

* Creating a receptor with crystallographic water that ligands will interact with.

* Creating a receptor with constraints or adding constraints to an existing
  receptor.

* Visualizing and editing the size of the inner and outer contour shapes
  (see :ref:`Receptor Theory<receptor_theory_negative_image>`).

To start **Make Receptor**, type "make_receptor" on the command line or click
on the **Make Receptor** icon from Dock on OSX; type "make_receptor" on the DOS prompt
or click on the **Make Receptor** shortcut from Desktop on Windows; or type
"make_receptor" on the command line on Linux.

.. _make_receptor_gui_layout:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: make_receptor

GUI Layout
===================

.. _make_receptor_layout_figure:

.. list-table::  
   :widths: 100
   :header-rows: 0  

   * - .. image:: ../images/make_receptor_launch4.png
   * - **Make Receptor Layout**

The layout of the **Make Receptor** GUI, shown above, is divided into
five general areas.

*  **Menu**

   *  **File**

      *  **New**
          Open molecule file(s) to create a new design unit receptor.

      *  **Open Design Unit/Receptor**: Open an existing design unit or receptor.

      *  **Open Recents**: Opens a recently opened OEDU file.
 
      *  **Save Receptor**: Saves the receptor to a file.  The receptor shape must be defined
         before this option can be used.

      *  **Save DU**: Saves the design unit(s) to a file. A design unit must exist
         before this option can be used.

      *  **Clear** :Deletes all receptor data and molecules and opens the molecules
         edit mode.

      *  **Quit**: Quits **Make Receptor**.

   *  **Extract**

      *  **Target**

         Extract the receptor target into a molecule file.

      *  **Protein**

         Extracts the protein structure from the design unit into a molecule file.

      *  **Ligand**

         Extracts the bound ligand from the design unit into a molecule file.

      *  **Box**

         Extracts the box enclosing the receptor site into a molecule file.  The
         molecule file will have eight carbon atoms, one at each vertex of the box.

   *  **Display**

      These options all relate to the 3D display window.

      *  **Hydrogens**

         Turn on and off display of hydrogens in the 3D window.

      *  **Protein**

         Sets the protein display mode.

      *  **Ligand**

         Sets the ligand display mode.

      *  **Box**

         Sets the box display mode.

      *  **Outer Contour**

         Sets the display mode of the outer contour.

      *  **Inner Contour**

         Sets the display mode of the inner contour.

      *  **Constraints**

         Sets the display mode of the constraints.

      *  **Disable Hardware Rendering**

         Disables OpenGL hardware rendering. Useful for Windows machines experiencing
         driver-related 3D graphical issues.

   *  **Help**

      *  **About**

         Reports the version of the program.

      *  **Documentation**

         Opens a browser window to OpenEye's web documentation.

*  **Workflow Stage Selector**

   These buttons control the overall workflow to set up a receptor.  Most stages of
   the workflow must be finished before progressing to the next stage.  When the
   next stage of the workflow is available, its button will highlight here and the
   next button (described below) will become available.  The workflow for setting up
   a receptor is described in detail in the 
   :ref:`setting up a receptor section<make_receptor_setup>`.
   
*  **Workflow Stage Controls**

   The controls for each stage of the workflow setup are located in this area.
   As you progress through the stages of the setup process, controls for each
   stage will appear here. The workflow for setting up a receptor is described
   in detail in the :ref:`setting up a receptor section<make_receptor_setup>`.

*  **3D Display**

   A 3D display of the current state of the receptor and its associated data.

*  **Next Mode Button**

   Selects the next stage of the setup receptor workflow once the current stage has
   been properly setup.


.. _make_receptor_setup:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


Setting up a Receptor
========================

New DU/Receptor
----------------

Use the ``File->New...`` menu option to create a new design unit or receptor. 
This provides two separate paths to creating a new design unit. Choose the ``PDB/MMCIF``
option to create a design unit starting from a PDB or MMCIF file (with or without an
associated MTZ file). The ``Molecules`` option should be used when various molecule 
components of the design unit contains in separate files.

Existing DU/Receptor
---------------------

Use the ``File->Open Design Unit/Receptor...`` menu option to open an existing design 
unit or receptor. This option allows opening both an OEDU file or a receptor containing
in an OEB or OEB.GZ file.

The :ref:`chapter_hybrid` program requires that a 
receptor have a bound ligand, while :ref:`chapter_fred` does not.  Waters and other
crystallographic solvents, that are a aprt of the design unit, are ignored
during the docking process of both :ref:`chapter_hybrid` and :ref:`chapter_fred`, unless the 
user designates them as part of the receptor target.  (See the following
:ref:`molecules<make_receptor_molecules_figure>` section).  

.. note::

   If a receptor is chosen using File->Open menu option :ref:`chapter_makereceptor`
   will switch to :ref:`finish mode<make_receptor_finish_figure>` to show
   a summary of the information on the receptor.  You can then select any
   of the setup steps to modify the receptor as desired.

Molecules
---------

.. _make_receptor_molecules_figure:

.. list-table::  
   :widths: 100
   :header-rows: 0  

   * - .. image:: ../images/make_receptor_molecules2.png
   * - **Molecules controls**

The purpose of the molecules workflow stage is to classify molecules.  A
molecule is a covalently connected set of atoms that is not covalently bound
to any other molecule.

.. note::

   Covalently bound ligands are not supported.

Each molecule can have one of three classifications.  

*  **Target**

   These molecules make up the structure of the target (protein) that docking ligands
   interact with.  The structure is treated as rigid during the docking 
   process, except for rotatable hydrogens (e.g., hydroxyls) which are 
   rotated to form optimal hydrogen bonding interactions during the docking
   process (this rotation is an internal calculation that is reflected in 
   the docked scores, but not in any output structure).

*  **Bound Ligand**

   This molecule is a ligand bound into the active of the protein.  Generally
   the bound ligand structure is determined by x-ray crystallography, although
   a docked molecule structure could also be used instead if there is high 
   confidence in the correctness of the docked structure.

   This molecule is required by :ref:`chapter_hybrid` during the docking process to guide
   docking molecules into a docking mode similar to the bound ligand.  It is not
   required by :ref:`chapter_fred` and is ignored by :ref:`chapter_fred` if present.

*  **Excess Molecules**

   Excess molecule are those that should not be included as part of the design
   unit. Once a set of molecules are marked to be removed (``X``), and design unit
   is prepared, those molecules are removed from the system.

Molecule classification is done using the *Mark as bound ligand*, *Mark as receptor target*,
and *Mark to remove* checkboxes (see the :ref:`molecule controls figure<make_receptor_molecules_figure>`).

Listed molecules can be identified in the 3D window by clicking their names in the
list.  Selected molecules are depicted in CPK rather than wireframe mode.  
Molecule selection can also be done on a molecule in the 3D window to identify
which molecule it is in the molecule list.

At least one molecule must be classified as a receptor target molecule before moving
on to the next stage of the workflow.

Box
---

.. _make_receptor_box_figure:

.. list-table::  
   :widths: 100
   :header-rows: 0  

   * - .. image:: ../images/make_receptor_box2.png
   * - **Box controls**

The goal in this stage of the receptor setup workflow is to define a box 
enclosing the active site.  The box should enclose the entire region active site
where heavy atoms of the docking ligand can be placed.  Any docked pose with
any heavy atom that lies outside the box will be rejected.

If a bound ligand was specified in the previous stage a default box will 
automatically be setup around the bound ligand, otherwise an initial box
can be created by clicking on a protein residue in the 3D window.  

Once created a box and be adjusted using the Create/Adjust box controls.
Clicking on a protein residue will also automatically extend the box to
enclose the clicked reside.  

Two cavity detection routines are also provided.  Both the Atomic and
Molecular cavity detection routines create blobs in the 3D windows in
the grooves and pockets around the protein that could potentially be active
sites.  The box can then be extended or created around a blob by clicking
on it.  The Molecular cavity detection uses a better algorithm, but takes
much longer to run than the Atomic detection algorithm. The sensitivity 
slider adjusts the contour level of created blobs.

The sequence viewer can be used to locate specific residues on the protein.
When a residue is clicked in the sequence viewer a label on the corresponding
residue is shown in the 3D window.

Shape
-----

.. _make_receptor_shape_figure:

.. list-table::  
   :widths: 100
   :header-rows: 0  

   * - .. image:: ../images/make_receptor_shape2.png
   * - **Shape controls**

The Shape stage of the receptor setup workflow defines the 
:ref:`inner and outer contours<receptor_theory_negative_image>` of the
receptor.  Both contours are always enclosed by the box setup in the
previous stage of the setup workflow. 

The "Create Shape" button sets up a shape potential and automatically selects
reasonable inner and outer contours (the former is disabled by default, see
below).  The slider below the "Create Shape" can be used to select the type of
shape potential that will be generated when the "Create Shape" button is pushed.
If "Favors Protein" is selected the contours will tend to extend closer to the
protein before extending out into solvent, while "Favors Solvent" will cause the
reverse to happen.  Balanced, the default, is reasonable in most cases.  

Once the contours are created, their size can be adjusted using the inner and
outer contour sliders.  The sliders control the inner and outer
contour levels (while the slider below the "Create Shape" button controls the
underlying potential being contoured).  Either contour can be disabled to
increase the space of poses searched for each docking ligand. 

Disabled is the recommended, and default setting, for the inner contour.  The
inner contour should be enabled only if the active site is extremely large.  In
these cases using the inner contour can increase docking speed by ~25% at the
cost of reduced docking accuracy.

The outer contour should only be disabled in cases where the active site is 
flat with no well defined shape.  **Docking without the outer contour can
increase docking time by as much as 100 fold**.

.. note::

   In general the outer contour should be between 500 and 2000 cubic Ångströms
   and the inner contour between 25 and 100 cubic Ångströms.

Constraints
-----------

.. _make_receptor_constraints_figure:

.. list-table::  
   :widths: 100
   :header-rows: 0  

   * - .. image:: ../images/make_receptor_constraint2.png
   * - **Constraints controls**

Constraints are a way of ensuring that receptor-ligand interactions known
to be associated with activity are present in a docked pose.
This inclusion of prior knowledge has been shown to be effective in 
improving the performance for pose prediction and virtual screening
of docking programs including :ref:`chapter_fred` [Warren-2006]_. While the use of
constraints can improve performance it can also degrade performance 
if the constraints used are not chosen wisely. The current recommended
practice is to use the smallest number of constraints possible that describe
the interaction associated with activity and to validate that the results
generated (poses and virtual screening performance) are an improvement
versus using no constraints. For this release, validation must be done
using either :ref:`chapter_fred` or :ref:`chapter_hybrid` using a saved receptor file.

Adding constraints to a receptor is optional.  Constraints are user specified
interactions that docked poses are required to make with the protein.  Once
created a constraint can be enabled or disabled. A disabled constraint has
no effect on the docking process of either :ref:`chapter_fred` or :ref:`chapter_hybrid`.  Any
docked pose that does not satisfy an enabled constraint will be rejected.  
If multiple enabled constraints are specified poses must satisfy
every one.  It is not possible for instance to only require that only 3 out
of 4 constraints be satisfied.

There are two types of constraint that can be specified; Protein and Custom
constraints.  Protein constraints are easy to use constraints that are 
associated with a particular protein atom and are satisfied when a docked
poses makes a specified type of interaction with it (hydrogen bond, 
metal-chelator or contact).  Custom constraints are defined
by spheres within the active site and optionally one or more SMARTS patterns.
Custom constraints are satisfied when a heavy atom of
a docked pose falls with one of the spheres if no SMARTS pattern is 
satisfied, or when an atom on the docked pose matching one of the SMARTS 
patterns falls with a sphere.

To edit, view or create protein constraints click on the proteins tab at the
top of the window.  If the receptor contains a bound ligand,
**Make Receptor** may automatically detect potential constraints.
Auto-detected constraints appear in the constraint list like any other 
protein constraint and are disabled by defaults.  To enable them click the
*Use* field next to the constraint you wish to enable in the protein
constraint list.  To see where the constraint is located in the 3D window
and view the constraint setting  click on the name of the constraint in the
protein constraint list.  To create a new protein constraint simple click 
on a protein atom in the receptor site and use the protein constraint 
setting to select the type of constraint desired.

To edit, view or create custom constraints select the custom tab at the top
of the window.  Select and edit custom constraints by clicking on their name
in the custom constraint list.  To create a new constraint click on an atom
in the 3D window, which will create an initial sphere around the clicked atom
and prompt you to name the constraint.  To add SMARTS patterns click on the 
+ button in the "SMARTS Pattern of Selected Constraint" list.  As with protein
constraints they can be enabled and disabled by clicking the *Use* column next
to the constraint name.

Finish
------

.. _make_receptor_finish_figure:

.. list-table::  
   :widths: 100
   :header-rows: 0  

   * - .. image:: ../images/make_receptor_finish.png
   * - **Finish controls**

This stage of the workflow provides a summary of the information stored on 
the receptor.  You should now save your receptor using either the button at
the bottom of the screen or the File->Save menu option.  

If you load a receptor using the File->Open menu option, the
**Make Receptor** will automatically load all the receptor information at
set the workflow to this stage.  

To edit any part of the receptor click on the appropriate workflow mode button
on the left (e.g., Molecules, Box, Shape or Constraints).



Utilities
=========

.. toctree::
   :maxdepth: 2

   ReceptorInDU
   OEB2DUReceptor
   DockingReport
   scorepose
   ReceptorToolbox
   CombineReceptors
   DU2OEBReceptor



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _ReceptorInDU:

******************
ReceptorInDU
******************

.. program:: ReceptorInDU

Overview
===================

:ref:`ReceptorInDU` is a utility program to make a receptor inside a prepared OEDesignUnit.

.. note::

   While :ref:`ReceptorInDU` is good at automatically setting up receptors, it
   is recommended that the :ref:`chapter_makereceptor` GUI be used to examine/modify
   the receptor created by :ref:`ReceptorInDU` prior to using it with
   :ref:`chapter_fred`, :ref:`chapter_hybrid` or :ref:`POSIT<chapter_posit>`. Particularly, if
   a user wants to define constraints or include specific water molecules in the receptor.
   This step is not required, however.

.. seealso::

   * The :ref:`SPRUCE <chapter_spruce>` chapter

Example Commands
===================

Make receptor version of OEDU file for 5MM6
--------------------------------------------

Converts the prepared OEDU file into a receptor containing OEDU file.

Input files

   * **5MM6_HIL__DU__32U_H-311.oedu** : OEDU file to convert into a receptor.

Command line

      .. code-block:: bash

         prompt> receptorindu 5MM6_HIL__DU__32U_H-311.oedu rec_5MM6_HIL__DU__32U_H-311.oedu

Output files

   * **rec_5MM6_HIL__DU__32U_H-311.oedu** : Receptor version of 5MM6 design unit.

Command Line Help
===================

A description of the command line interface can be obtained by executing **ReceptorInDU**
with the `--help` option.

.. code-block:: console

   > receptorindu --help

will generate the following output:

::

   Help functions:
     receptorindu --help simple      : Get a list of simple parameters
     receptorindu --help all         : Get a complete list of parameters
     receptorindu --help defaults    : List the defaults for all parameters
     receptorindu --help <parameter> : Get detailed help on a parameter
     receptorindu --help html        : Create an html help file for this program
     receptorindu --help versions    : List the toolkits and versions used in the application

Required Parameters
===================

.. option:: -in <filename>

   An OEDesignUnit file generated by Spruce.

   [keyless parameter 1]

Optional Parameters
===================

Input Options
---------------

.. option:: -molnames

   This parameter specifies a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set then only molecule in the
   input file(s) (see parameter :option:`-in`) with names that match those
   in the text files will be read in.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecule(s) that are contained in a large database, without
   having to extract those molecules by hand from the database.

Output Options
---------------

.. option:: -out <filename>

   An OEDesignUnit file containing the receptor.

   [keyless parameter 2]

.. option:: -prefix

   Prefix used to name output files.

.. option:: -progress

   Show progress on screen.  Options are 'none', 'dots', 'log' and 'percent'.
   The 'dots' options will displays dots on screen to show molecules
   completed.  The 'log' option will duplicate the log file on screen.
   The 'percent' option will track progress through the input file.  [Default=none]

Receptor Options
----------------

.. option:: -targetMask    [Default=targetComplexNoSolvent]

   Design unit components mask defining the subset of design unit components to
   be used as targets for the receptor. Multiple components can also be combined as
   a comma separated string to create the input.

   Possible values:

    * cofactors, counter_ions, excipients, lipids, metals, nucleic, other_cofactors,
      other_ligands, other_nucleics, other_proteins, packing_residues, polymers,
      post_translational, protein, solvent, sugars

   Multi component choices:

     * targetComplex (protein,nucleic,cofactors,solvent,metals,counter_ions,lipids,other_proteins,
       other_nucleics,other_ligands,other_cofactors)
     * targetComplexNoSolvent (protein,nucleic,cofactors,metals,lipids,other_proteins,
       other_nucleics,other_ligands,other_cofactors)
     * macroMolComponents (protein,nucleic,other_proteins,other_nucleics)
   
.. option:: -targetPred

   Residue-based selection predicate to subset components of the design unit targetMask.
   The predicate is only enforced on a component of the targetMask if it matches something in
   that component from the design unit.
   Input like: "HOH:1024: :A|HOH:567: :A|" with a targetMask that includes the solvent from the designunit, 
   will subset the solvent component to only include these specific water molecules in the receptor 
   generation, however, since this does not match anything in the Protein component of the design unit
   it will leave that component as is.   

.. option:: -negImageType    [Default=standard]

   The type of negative image to create in generating the receptor grid.
   Choices: large, standard, small

.. option:: -box <box file> [No Default]

   A file describing a box enclosing the active site.  All docked poses will be
   required to fit within this box.

   The box must be in a 3D molecular format.  SDF, MOL2, OEBinary
   and several other common molecular formats are supported.

   The box will always be aligned along the X, Y and Z axis of the coordinate
   system and the edges of the box will be the maximum and minimum X, Y and Z
   value of any atom in the box file.

   .. note::

      The bound ligand is ignored for active site detection, when this flag is specified.

.. option:: -addbox <distance> [No Default]

   This flag adjusts the box created by the :option:`-box` flag by extending each
   edge of the box by the specified number of Angstroms.  Thus each dimension of
   the box will be enlarged by twice the setting of this parameter.

   If :option:`-box` is not specified this flag has no effect.



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _OEB2DUReceptor:

******************
OEB2DUReceptor
******************

.. program:: OEB2DUReceptor

Overview
===================

:ref:`OEB2DUReceptor` is a utility program to convert a molecule based receptor 
OEB or OEB.GZ file into a receptor inside OEDesignUnit, in OEDU file.

.. note::

   The :ref:`OEB2DUReceptor` is not an utility to make a receptor. This is merely a
   converter for old receptor files, in OEB or OEB.GZ format, into a new OEDU format
   receptor.

   To make a receptor, use the :ref:`ReceptorInDU` or the :ref:`chapter_makereceptor`.

Example Commands
===================

Convert a receptor OEB.GZ file into an OEDU receptor
------------------------------------------------------

Converts the OEB.GZ receptor file into an OEDU receptor.

Input files

   * **receptor.oeb.gz** : OEB.GZ file to convert into an OEDU receptor.

Command line

      .. code-block:: bash

         prompt> oeb2dureceptor receptor.oeb.gz receptor.oedu

Output files

   * **receptor.oedu** : OEDU version of the receptor.

Command Line Help
===================

A description of the command line interface can be obtained by executing **OEB2DUReceptor**
with the `--help` option.

.. code-block:: console

   > oeb2dureceptor --help

will generate the following output:

::

   Help functions:
     oeb2dureceptor --help simple      : Get a list of simple parameters
     oeb2dureceptor --help all         : Get a complete list of parameters
     oeb2dureceptor --help defaults    : List the defaults for all parameters
     oeb2dureceptor --help <parameter> : Get detailed help on a parameter
     oeb2dureceptor --help html        : Create an html help file for this program
     oeb2dureceptor --help versions    : List the toolkits and versions used in the application

Required Parameters
===================

.. option:: -in <filename>

   An OEB or OEB.GZ file containing a receptor.

   [keyless parameter 1]

Optional Parameters
===================

Input Options
---------------

.. option:: -molnames

   This parameter specifies a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set then only molecule in the
   input file(s) (see parameter :option:`-in`) with names that match those
   in the text files will be read in.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecule(s) that are contained in a large database, without
   having to extract those molecules by hand from the database.

Output Options
---------------

.. option:: -out <filename>

   An OEDesignUnit file containing the receptor.

   [keyless parameter 2]

.. option:: -prefix

   Prefix used to name output files.

.. option:: -progress

   Show progress on screen.  Options are 'none', 'dots', 'log' and 'percent'.  
   The 'dots' options will displays dots on screen to show molecules 
   completed.  The 'log' option will duplicate the log file on screen.
   The 'percent' option will track progress through the input file.  [Default=none]



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _docking_report:

******************
DockingReport
******************

.. program:: docking_report

Overview
===================

:ref:`DOCKING_REPORT` is a utility program that creates a PDF report for one or
more molecules docked by :ref:`chapter_fred` or :ref:`chapter_hybrid`.  The PDF report lists
includes a 2D depiction of each molecule, a breakdown of the score by atom,
a breakdown of the score components by atom, a comparison of the molecule's
score compared to the other docked molecules, SD data tagged to the molecule
and other general molecule properties (e.g., molecular weight).
:ref:`DOCKING_REPORT` also includes a 'Residue Fingerprint' which highlights
which residues in the receptor site the ligand is interacting with (greyed out
residues are residues in the site that other ligands interact with, but the
current ligand does not).

.. _docking_report_figure:

.. list-table::
   :widths: 100
   :header-rows: 0

   * - .. image:: images/docking_report.png
   * - **Example dock report**

Example Commands
===================

Creating a report for named molecules
-------------------------------------

Creates a report for 2 molecules *blockbuster1* and *blockbuster2* that
were docked by :ref:`chapter_fred`.

Input files

   * **fred_docked.oeb.gz**

      Molecules docked by :ref:`chapter_fred` including two molecules named
      *blockbuster1* and *blockbuster2* respectively.

   * **receptor.oedu**

      The receptor file the molecules in **docked.oeb.gz** were docked to.

Command line

      .. code-block:: bash

         prompt> docking_report -docked_poses fred_docked.oeb.gz \
                             -receptor receptor.oedu \
                             -names blockbuster1 blockbuster2

Output files

   * **docking_report.pdf**

      PDF dock report for *blockbuster1* and *blockbuster2*.

Creating a report for molecules identified by SMILES
----------------------------------------------------

Creates a report for molecules, docked by :ref:`chapter_hybrid`, that have the same
canonical smiles as molecules in a specified file.

Input files

   * **hybrid_docked.oeb.gz**

      Molecules docked by :ref:`chapter_hybrid`.

   * **receptor1.oedu** and **receptor2.oedu**

      The receptor files :ref:`chapter_hybrid` used to dock the molecules in **docked.oeb.gz**.

   * **interesting_ligands.sdf**

      Set molecules to create reports for.  The molecules in this file will be
      converted into canonical SMILES, and a report will be generated for each
      molecule in **docked.oeb.gz** that has the same canonical SMILES as any
      one of the molecules in **interesting_ligands.sdf**

Command line

      .. code-block:: bash

         prompt> docking_report -docked_poses hybrid_docked.oeb.gz \
                             -receptor receptor1.oedu receptor2.oedu \
                             -smiles_file interesting_ligands.sdf

Output files

   * **docking_report.pdf**

      PDF dock report for all molecules in **docked.oeb.gz** that have the same
      canonical SMILES as one of the molecules in **interesting_ligands.sdf**.

Command Line Help
===================

A description of the command line interface can be obtained by executing **DockingReport**
with the `--help` option.

.. code-block:: console

   > docking_report --help

will generate the following output:

::

   Help functions:
     docking_report --help simple      : Get a list of simple parameters
     docking_report --help all         : Get a complete list of parameters
     docking_report --help defaults    : List the defaults for all parameters
     docking_report --help <parameter> : Get detailed help on a parameter
     docking_report --help html        : Create an html help file for this program
     docking_report --help versions    : List the toolkits and versions used in the application

Required Parameters
===================

Input
-------------------

.. option:: -docked_poses <filename>

   A file with poses that were docked by either :ref:`chapter_fred` or :ref:`chapter_hybrid`.

   [Aliases=**-poses**]

.. option:: -receptor <filename> [<filename> ...]

   Receptor file the poses passed to :option:`-docked_poses` were docked too.
   If the poses were docked with hybrid :ref:`chapter_hybrid` using multiple receptor
   structures then the same set of receptor structures should be passed to
   this flag.

   [Aliases=**-rec**]

Optional Parameters
===================

Input Options
----------------

.. option:: -names <molecule name> [<molecule name> ...] [No Default]

   This option identifies one or more molecules passed to the :option:`-docked_poses`
   option by name.  Molecules specified with this flag will have a report generated
   for them.

   .. note::

      Either this flag or :option:`-smiles_file` must be specified.

   [Aliases=**-title**]

.. option:: -smiles_file <filename> [No Default]

   This option identified molecules passed to the :option:`-docked_poses` option by
   canonical SMILES.  Molecules identified with this flag will have a report
   generated for them.

   .. note::

      Either this flag or :option:`-names` must be specified.

   [Aliases=**-smiles**]

.. option:: -sd_tags <Tag> [<Tag> ...] [No Default]

   This flag specifies a specific set of SD tagged data to include in the dock
   report.  If this flag is not specified all the SD data will be include in the
   dock report.

   .. note::

      The dock report has a limited amount of space for SD data and can only include
      10 pieces of SD data for each docked molecule (additional SD data will not
      appear in this report).

   [Aliases=**-sdtags**]

Output Options
----------------

.. option:: -report_file <filename>   [Default=docking_report.pdf]

   Name of the docked report file to generate.

   The file must be a PDF file (i.e., have a .pdf extension).

   [Aliases=**-report**]




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _scorepose:

***************
ScorePose
***************

.. program:: scorepose

Overview
===================

:ref:`SCOREPOSE` scores poses in a :option:`-dbase` database in the context
of a single :ref:`receptor <receptor_theory>`, using the
:ref:`theory_algorithm_chemgauss4` scoring function.  Poses may also optionally
be optimized with the :option:`-optimize` option vs. :ref:`theory_algorithm_chemgauss4`.

.. note::

  :ref:`SCOREPOSE` does not dock molecules, it only rescores and optionally
  optimizes molecules within the context of a :ref:`receptor <receptor_theory>` site.

.. _scorepose_ligand_preparation:

Input Preparation
===================

Ligand Preparation
------------------

The ligand input to :ref:`SCOREPOSE` should already be docked into the
:ref:`receptor <receptor_theory>` site.  For the purposes of this document, we'll
call the file(s) of poses to be scored the database file(s), or dbase file(s).
Supported formats of the database file include SDF, MOL2 and PDB.
:ref:`SCOREPOSE` determines the database file format from the file extension,
:file:`.sdf` or :file:`.mol` for SDF, :file:`.mol2` for MOL2, :file:`.pdb` or
:file:`.ent` for PDB. Gzip compressed files of these same formats are allowed
as well. :ref:`SCOREPOSE` will interpret :file:`infile.sdf.gz` as a gzip'ed
SDF file.

.. note::

   Note that even though all these formats are supported, using SDF, PDB or MOL2
   can result in a loss of speed due to the I/O penalty of these formats.  We
   recommend using Gzipped OEB format for maximum speed.

By default :ref:`SCOREPOSE` will interpret conformers in the database file(s)
as part of a single multi-conformer molecule as long as they:

* Are contiguous in the input file.
* Have the same numbers of atoms and bonds in the same order
* Have identical atom and bond properties with their order
  correspondent in the subsequent connection table
* Have the same atom and bond stereochemistry

While this may appear to be a restrictive list, many programs write
multi-conformer molecules into SDF or MOL2 files such that the above rules
will be satisfied. If the conformers are named differently, (*i.e.* they
have a conformer number appended to the base name like acetsali_1,
acetsali_2), :ref:`SCOREPOSE` will still consider them part of a single
multi-conformer molecule if the criteria above are met.

Receptor Preparation
--------------------

.. note::

  Beginning with :ref:`SCOREPOSE` 4.0.0,  :ref:`SCOREPOSE` now only accepts an OEDU with receptor as the
  receptor input file.

:ref:`SCOREPOSE` requires the :ref:`receptor<receptor_theory>` file that the
ligands in the database were docked to.  This should generally already be available
if the ligands were docked with :ref:`chapter_fred` or :ref:`chapter_hybrid`.  If the ligands were
docked with another program a receptor can be created using one of the following
programs.

.. tabularcolumns:: |l|l|p{10cm}|

=======================================  ============  ==========================================
Program                                  Type          Description
=======================================  ============  ==========================================
:ref:`chapter_makereceptor`              GUI           Interactive GUI for creating a receptor.
---------------------------------------  ------------  ------------------------------------------
:ref:`ReceptorInDU`                      Command Line  Generates a receptor inside a prepared
                                                       OEDesignUnit in an OEDU file.
---------------------------------------  ------------  ------------------------------------------
:ref:`OEB2DUReceptor`                    Command Line  Converts a molecule based receptor OEB or
                                                       OEB.GZ file into a receptor inside
                                                       an OEDesignUnit, in an OEDU file
=======================================  ============  ==========================================

.. note::

   Receptors can also be created using the OpenEye Docking Toolkit (see the
   Docking Toolkit documentation).

Command Line Help
===================

A description of the command line interface can be obtained by executing **ScorePose**
with the `--help` option.

.. code-block:: console

   > scorepose --help

will generate the following output:

::

   Help functions:
     scorepose --help simple      : Get a list of simple parameters
     scorepose --help all         : Get a complete list of parameters
     scorepose --help defaults    : List the defaults for all parameters
     scorepose --help <parameter> : Get detailed help on a parameter
     scorepose --help html        : Create an html help file for this program
     scorepose --help versions    : List the toolkits and versions used in the application

Required Parameters
===================

.. option:: -receptor <receptor file>

   Receptor file to rescore poses with.

   [Aliases=**-rec**]

.. option:: -dbase <input filename1> [<input filename2> ...]

   File(s) containing ligand poses to rescore
   (see section :ref:`scorepose_ligand_preparation`).

   The following file formats are supported.

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ============ ===========================

   More than one file can be specified.

   [Aliases=**-database**,**-in**]

Optional Parameters
===================

Input Options
-------------------

.. option:: -param <parameter filename>    [No Default]

   A parameter file is a text file that lists parameter settings to be used
   during a run.   If a parameter is specified both on the command line and in
   the parameter file, the value specified on the command line is used.

   The format of the parameter file is as follows:

   * One parameter per line

   * For non-list parameters one key-value pair per line. (*e.g., -receptor rec.oedu*).

   * For list parameters a key followed by all the values (*e.g., -dbase lig1.oeb.gz ligs2.oeb.gz*)

   * Boolean parameters must be listed as a key followed by true or false (*e.g. -annotate_poses true*).

   * The parameter file may not contain the :option:`-param` parameter.

   * Lines beginning with # are considered comments



.. option:: -molnames <input filename>    [No Default]

   This parameter specifies a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set then only molecules in the
   database file(s) (see parameter :option:`-dbase`) with names that match those
   in the text files will be read in.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecule(s) that are contained in a large database, without
   having to extract those molecules by hand from the database.



Score Options
-------------

.. option:: -optimize <level> [No Default]

   If this parameter is specified each pose will be optimized with a systematic solid
   body optimization with a resolution given by the table below.

   ========= ====================== ===================
   Level     Translational Stepsize Rotational Stepsize
   ========= ====================== ===================
   High      0.5 Ångström           0.5 Ångström
   Standard  0.5 Ångström           0.75 Ångström
   Low       0.75 Ångström          1.0 Ångström
   ========= ====================== ===================

   If this parameter is not specified poses will not be optimized prior to scoring.

   [Aliases=**-opt**]

   .. seealso::

      * :ref:`OEDocking::OEDockOptions::SetResolution <OEDocking_OEDockOptions_SetResolution>` in the **OEDocking TK** manual.

Output Files
------------

.. option:: -prefix <value> [Default=rescore]

   This flag prefixes all default output filenames with the specified value.

   .. note::

      This flag does not affect output filenames explicitly set by the user.

.. note::

   Values in parenthesis are default values.

.. option:: -rescored_molecule_file <output filename> [Default=scored.oeb.gz]

   File rescored molecules will be written to.  The file format is
   controlled by the extension of the filename.  The following output
   formats are supported.

   ================ ===========================
   Format           Extension
   ================ ===========================
   OEBinary         .oeb
   ---------------- ---------------------------
   SDF              .sdf
   ---------------- ---------------------------
   Gzipped OEBinary .oeb.gz
   ---------------- ---------------------------
   Gzipped SDF      .sdf.gz
   ================ ===========================

   Scores will be attached as SD data to each pose with the tag
   **FRED Chemgauss4 Score**, unless the :option:`-score_tag` option is used
   to specify another tag.

   By default the top 500 scoring molecules will be outputted to this
   file (see :option:`-hitlist_size` flag).

   .. note::

      If this flag is not set by the user the default filename (i.e., scored.oeb.gz)
      will be automatically prefixed with the setting of the
      :option:`-prefix` flag.

   [Aliases=**-rescored_mol_file**,**-rescored_file**,**-rescored**,**-out**]

.. option:: -score_file <filename>   [Default: score.txt]

   Specifies a tab separated text file with the name and scores of the molecules.

   .. note::

      If this flag is not set by the user the default filename (i.e., score.txt) 
      will be automatically prefixed with the setting of the
      :option:`-prefix` flag.

   [ Aliases : **-score** ]



.. option:: -report_file <filename> [Default: report.txt]

   Specifies a file that a text report of the run will be written to.

   .. note::

      If this flag is not set by the user the default filename (i.e., report.txt)
      will be automatically prefixed with the setting of the
      :option:`-prefix` flag.

   [ Aliases : **-report** ]



.. option:: -settings_file <filename> [Default: settings.param]

   Writes the settings of all parameters of the run to the specified output
   file.  The settings will be listed in plain text with one parameter name
   follow by its value(s).  This format is compatible with the format of
   parameter files, and therefore a settings file from a previous run can be
   passed to the :option:`-param` flag to re-run the program with the same settings.

   .. note::

      If this flag is not set by the user the default filename (i.e., settings.param) 
      will be automatically prefixed with the setting of the 
      :option:`-prefix` flag.

   [ Aliases = **-settings** ]


.. option:: -status_file <filename> [Default: status.txt]

   If this parameter is set then the status of the run will be written to the given output
   file every few seconds (the previous contents of the file will be overwritten)
   during the run.

   .. note::

      If this flag is not set by the user the default filename (i.e., status.txt) 
      will be automatically prefixed with the setting of the 
      :option:`-prefix` flag.

   [ Aliases = **-status** ]



Output Options
--------------

.. option:: -hitlist_size <num>    [Default=500]

   This parameter controls whether docked molecules are outputted as they are
   docked or in an internal hitlist and outputted at the end of the run.

   If -hitlist_size is zero the run will be in serial mode, i.e. each molecule
   will be outputted as it is docked (unsorted).  For single processor runs this
   will be the order the molecules appear in the database file(s).  For
   MPI runs the order will not be strictly the order the molecules appear in the
   database file(s).

   If -hitlist_size is non-zero a sorted internal hitlist of docked molecules
   that will be maintained and outputted at the end of the run.  The maximum
   size of the hitlist is -hitlist_size.  If more than this number of molecules
   are docking during the run only the top scoring molecules will be outputted
   and the rest will be discarded.

   There is no formal limit on the number of molecule that can be sorted
   and outputted at the end of the run.  However, retaining a large
   number of molecules significantly increases the memory requirements.
   A good rule of thumb is that the setting total number of poses retained
   should not be larger than 10,000.

   [Aliases=**-hitlist_size**,**-hitlist**]

.. option:: -sort_poses    [Default=false]

   If this option is selected the poses of each molecule will be sorted by score.

   If the molecules in the database do not have multiple poses this flag has no
   effect.

   [Aliases=**-sortposes**]

.. option:: -score_tag <tag>  [No Default]

   This parameter overrides the default SD Data Tag used to store molecule
   scores (the default is **FRED Chemgauss4 Score**).

   [Aliases=**-scoretag**]

.. option:: -annotate_scores [Default: false]

   If the value of this flag is set to true VIDA score annotations will be added
   to the processed molecules.  These annotations are visible in VIDA (OpenEye's
   molecular visualization program) and show a per atom breakdown of the score.  

   .. note::

      The docked molecule output file format (see
      :option:`fred -docked_molecule_file`) must be OEBinary when using score
      annotations.

   [ Aliases = **-annotate** ]



.. option:: -save_component_scores    [Default: false]

   If the value of this flag is set to true individual components of the total
   score will be saved to SD data on each pose and appear in the score file (see
   :option:`-score_file`).

   [ Aliases = **-component_scores**, **-component** ]



.. option:: -no_extra_output_files    [Default=false]

    When set the only default output to the program will be the docked structure
    file (see :option:`-rescored_molecule_file`).

    Using this flag suppresses the default output of the following

    ====================== ================== ===================================
    Output                 Default file       Parameter
    ====================== ================== ===================================
    text score file        score.txt          :option:`-score_file`
    ---------------------- ------------------ -----------------------------------
    report file            report.txt         :option:`-report_file`
    ---------------------- ------------------ -----------------------------------
    settings file          settings.param     :option:`-settings_file`
    ---------------------- ------------------ -----------------------------------
    status file            status.txt         :option:`-status_file`
    ====================== ================== ===================================

    Only default output is suppressed.  If any of these output parameters are
    explicitly set by the users the relevant output file will still be written
    even if this switch is turned on.

   [Aliases=**-no_extra**,**-noextra**,**-noextraoutputfiles**,**-no_extra_output**,**-noextraoutput**]

.. option:: -no_dots [Default: false]

    When this flag is set to true, a dot is being written to standard 
    error for each docking molecule (or x in the case of a failure).
    Setting this flag to false to suppress dot/x writing.

   [ Aliases = **-nodots** ]





.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _receptor_toolbox:

******************
ReceptorToolbox
******************

.. program:: receptor_toolbox

Overview
===================

:ref:`receptor_toolbox` is a utility program for receptors that can do the
following

* List information about the receptor

* Set the name of the receptor and/or bound ligand

* Extract molecules from the receptor

* Setup a scoring cache for :ref:`chapter_fred`, :ref:`chapter_hybrid` or :ref:`SCOREPOSE`.

* Enable/Disable existing constraints.

Example Commands
===================

Setup a receptor cache for *fred*
----------------------------------

This example illustrates setting up a receptor cache for :ref:`chapter_fred`.

Input files

   * **receptor.oedu** : A file containing a receptor.

Command line

      .. code-block:: bash

         prompt> receptor_toolbox -receptor receptor.oedu -prepare_score_cache fred

Output files

   * **receptor.oedu** :
     Receptor with score cache for :ref:`chapter_fred` (overwrites input file).

Command Line Help
===================

A description of the command line interface can be obtained by executing **ReceptorToolbox**
with the `--help` option.

.. code-block:: console

   > receptor_toolbox --help

will generate the following output:

::

   Help functions:
     receptor_toolbox --help simple      : Get a list of simple parameters
     receptor_toolbox --help all         : Get a complete list of parameters
     receptor_toolbox --help defaults    : List the defaults for all parameters
     receptor_toolbox --help <parameter> : Get detailed help on a parameter
     receptor_toolbox --help html        : Create an html help file for this program
     receptor_toolbox --help versions    : List the toolkits and versions used in the application

Required Parameters
====================

Receptor File to Operate On

.. option:: -receptor <receptor file>

   :ref:`RECEPTOR_TOOLBOX` reads this receptor file, and if the receptor is
   edited in any way the modified receptor will be output to this file
   (overwriting the original).

   [Aliases=**-rec**]

Optional Parameters
====================

Score Caching
-------------

.. option:: -prepare_score_cache <fred, scorepose or hybrid>    [No Default]

  Caches scoring setup for the specified program on the receptor.  This is not
  required, however doing so will improve the initial speed of the program by
  not requiring it to do as much scoring setup.

  A receptor can only have a score cache for one program at a time (previous
  score caches will be erased when this flag is used).

  .. note::

     Creating a score cache will substantially increase the size of the receptor
     file, typically on the order of 100 MBytes.

   [Aliases=**-prepare**]

.. option:: -clear_score_cache [Default=false]

   If this flag is set to true any scoring cache on the receptor will be removed.

   [Aliases=**-clear_cache**]

Inner Contour
-------------

.. option:: -turn_inner_contour <on or off>   [No Default]

   If this flag is set the inner contour will be turned on or off, as specified.
   See :ref:`Receptor Theory Section<receptor_theory_negative_image>` for an
   explanation of the inner contour.

   [Aliases=**-inner_contour**,**-inner**]

Protein Constraints
-------------------

.. option:: -enable_protein_constraint <name> [<name> ...]   [No Default]

   Enables the specified protein constraints.  The name can be either the name
   of the constraint or the name of the atom that the constraint is associated with.

   [Aliases=**-enable_protein_constraints**]

.. option:: -disable_protein_constraint <name> [<name> ...]   [No Default]

   Disables the specified protein constraints.  The name can be either the name
   of the constraint or the name of the atom that the constraint is associated with.

   [Aliases=**-disable_protein_constraints**]

.. option:: -enable_all_protein_constraints [Default=false]

   Enables all protein constraints.

   [Aliases=**-enableallproteinconstraints**]

.. option:: -disable_all_protein_constraints [Default=false]

   Disables all protein constraints.

   [Aliases=**-disableallproteinconstraints**]

Custom Constraints
------------------

.. option:: -extract_custom_constraints <filename>   [No Default]

   Extracts the receptors custom constraints to this specified file.

.. option:: -set_custom_constraints <filename>   [No Default]

   Sets the receptors custom constraints to be those in the specified file.

   The format of the constraint file is a text file with lines of one of the two
   following forms

   .. code-block:: bash

      SPHERE <ID> <RAD> <X> <Y> <Z>
      SMARTS <ID> <SMARTS Pattern>

   * **SPHERE** creates a sphere associated with a given constraint

      * ID is an integer that uniquely identifies a constraint

      * RAD is the radius of the sphere

      * X, Y and Z is the sphere center

   * **SMARTS** Creates a SMARTS pattern associated with the specified sphere.

      * ID is an integer that uniquely identifies a constraint

      * SMARTS Pattern is the SMARTS pattern to associate with the constraint.

   The following example file

   .. code-block:: bash

      SPHERE 1 4.0 1.0 1.0 1.0
      SMARTS 1 F
      SPHERE 2 4.5 3.0 2.5 -1.0

   Creates two constraints.  Constraint 1 has one sphere centered at
   (1.0, 1.0, 1.0) with radius 4.0 and can only be satisfied by a fluorine atom
   on the ligand.  Constraint 2 has one sphere centered at (3.0, 2.5, -1,0)
   with radius 4.5 and can be satisfied by any heavy atom on the ligand since
   the constraint as no associated smarts patterns.

   See :ref:`Receptor Theory Section<receptor_theory_constraints>` for more
   information about constraints.

.. option:: -enable_custom_constraint <constraint> [<constraint> ...]   [No Default]

   Enables the specified custom constraints.

   [Aliases=**-enable_custom_constraint**,**-enable_custom_constraints**]

.. option:: -disable_custom_constraint <constraint> [<constraint> ...]   [No Default]

   Disables the specified custom constraints.

   [Aliases=**-disable_custom_constraints**]

.. option:: -enable_all_custom_constraints [Default=false]

   If this flag is set to true all custom constraints on the receptor are enabled.

.. option:: -disable_all_custom_constraints [Default=false]

   If this flag is set to true all custom constraints on the receptor are disabled.



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _combine_receptors_usage:

***********************
combine_receptors
***********************

Overview
===================

.. program:: combine_receptors

In many cases ligands from different receptors may be combined to
yield more productive posing targets.  For example, if, when the two
proteins are aligned, two ligands overlap but occupy different spaces
in the binding pocket, **combine_receptors** will make a single receptor
using both ligands that may be a better target for predicting some
ligands.

When given multiple receptors, **combine_receptors** will find the best
matched pair for each input receptor.  The best matched pair is the
combination of two ligands that overlap but have a large difference in
shape.

For each set of combined ligands, two receptors are output, one for
each input protein.  This also helps when analyzing clashes.

Output names are automatically generated so that if two receptors are
merged, say ``A_receptor.oeb.gz`` and ``B_receptor.oeb.gz``, two outputs are
formed:

  * ``combine_receptors_A_receptor_merged_B_receptor.oeb.gz``
  * ``combine_receptors_B_receptor_merged_A_receptor.oeb.gz``

For example, consider the merged receptors shown in figures
:ref:`Merged receptors<merge1>` and :ref:`Matched to merged receptor<merge2>`.

.. _merge1:

.. figure:: /_images/merge1.png
   :scale: 75
   :align: center
   :alt: Merged receptors

   **Merged Receptors:** Merging the receptors 2IKO and 2IKU capture more potential
   interaction constraints than either does alone

.. _merge2:

.. figure:: /_images/merge2.png
   :scale: 75
   :align: center
   :alt: Merged receptors

   **Matched to Merged Receptors:** REN9 is correctly predicted by the merged receptor

If a combined ligand has significant clashes with the protein
a warning will also be output with the recommended setting when
running :ref:`posit<chapter_posit>`.
Serious clashes will not be output unless the user specifies the
:option:`-allowedClashes` option.

Example Commands
===================

To run **combine_receptors**, simply provide a list of known receptors:

First, make some receptors:

.. code-block:: console

   > spruce -in renin/2IKO.pdb.gz
   > spruce -in renin/2IKU.pdb.gz

To convert output ``OEDesignUnit`` files into ``OEBinary`` files:

.. code-block:: console

   > du2oebreceptor -in rec_2IKO_ABCDEFsym1__DU__7IG_A-601.oedu -out rec_2IKO_ABCDEFsym1__DU__7IG_A-601.oeb.gz
   > du2oebreceptor -in rec_2IKO_ABCDEFsym2__DU__7IG_A-601.oedu -out rec_2IKO_ABCDEFsym2__DU__7IG_A-601.oeb.gz
   ...
   > du2oebreceptor -in rec_2IKU_ABCDEF__DU__LIY_A-336.oedu -out rec_2IKU_ABCDEF__DU__LIY_A-336.oeb.gz
   > du2oebreceptor -in rec_2IKU_ABCDEF__DU__LIY_B-336.oedu -out rec_2IKU_ABCDEF__DU__LIY_B-336.oeb.gz
   ...

.. code-block:: console

   > combine_receptors -receptors rec_*.oeb.gz

.. note::

 On *Microsoft Windows* systems, you need to expand the wildcard:

.. code-block:: console

   > combine_receptors -receptors rec_2IKO_ABCDEFsym1__DU__7IG_A-601.oeb.gz  rec_2IKO_ABCDEFsym2__DU__7IG_A-601.oeb.gz rec_2IKO_ABCDEFsym3__DU__7IG_A-601.oeb.gz  rec_2IKU_ABCDEF__DU__LIY_A-336.oeb.gz rec_2IKU_ABCDEF__DU__LIY_B-336.oeb.gz rec_2IKU_ABCDEF__DU__LIY_C-336.oeb.gz rec_2IKU_ABCDEF__DU__LIY_D-336.oeb.gz rec_2IKU_ABCDEF__DU__LIY_E-336.oeb.gz rec_2IKU_ABCDEF__DU__LIY_F-336.oeb.gz

The merged receptor files will be named ``combine_receptors_rec_*``:

::

  Wrote combined receptor:combine_receptors_rec_2IKU_ABCDEF__DU__LIY_E-336_merged_rec_2IKO_ABCDEFsym1__DU__7IG_A-601.oeb.gz
  Wrote combined receptor:combine_receptors_rec_2IKO_ABCDEFsym2__DU__7IG_A-601_merged_rec_2IKU_ABCDEF__DU__LIY_E-336.oeb.gz ShapeTanimoto of merged ligands:0.690121
  ...

It is often useful to first collect the receptors ready for combining into a directory, and place the merged receptors
into another directory which must already exist, to do this, simply use the :option:`-outputdir` option.

.. code-block:: console

   > combine_receptors -receptors receptors/*.oeb.gz -outputdir merged

.. note::

   Again, on *Microsoft Windows* systems, you need to expand the wildcard
   (this will be omitted for all
   future examples).

If a merged ligand has
an unallowable clash with a protein, it will not result in a receptor.

Command Line Help
===================

A description of the command line interface can be obtained by executing **CombineReceptors**
with the `--help` option.

.. code-block:: console

   > combine_receptors --help

will generate the following output (omitting the OpenEye banner for
space)

::

   Help functions:
     combine_receptors --help simple      : Get a list of simple parameters
     combine_receptors --help all         : Get a complete list of parameters
     combine_receptors --help defaults    : List the defaults for all parameters
     combine_receptors --help <parameter> : Get detailed help on a parameter
     combine_receptors --help html        : Create an html help file for this program
     combine_receptors --help versions    : List the toolkits and versions used in the application

Required Parameters
===================

.. option:: -receptors <filenames>

   List of receptors to combine.  If a file is not a receptor, :program:`combine_receptors` will halt.

Optional Parameters
===================

.. option:: -allowedClashes

   Clashes allowed between the ligand and protein of a receptor.
   There are three levels:

   =================== ===========================================
   Allowed Clash       Description
   =================== ===========================================
   noclashes           No clashes are allowed.
                       Actually there is a little wiggle room here
                       less than 0.2 |Angstrom| penetration is not
                       considered a clash.
   ------------------- -------------------------------------------
   mildclashes         Mild clashes are allowed (greater than 0.2
                       |Angstrom| and less than 0.65 |Angstrom|)
   ------------------- -------------------------------------------
   allclashes          All clashes are allowed.
   =================== ===========================================

   The clash ranges have been tuned to account for average coordinate error
   in a sampling of PDB files, they are intended to be used as guidelines
   and may not be indicative of some clash states.

   By default, receptors are not output if serious clashes exist between
   the specified ligand and protein.  By specifying ``-allowedClashes allclashes``
   all clashing receptors will be output.

   [Default=mildclashes]

.. option:: -param <filename>

   Defines the control parameter file.  This file can contain a
   collection of parameters which can be used instead of writing each
   parameter to the command-line.  In addition, the parameter file
   written by any :ref:`posit<chapter_posit>` run (see :option:`-prefix` below),
   can be used with the :option:`-param` flag in subsequent
   :ref:`posit_<chapter_posit>` executions.  Any command
   given explicitly on the command line will supersede any command
   found in a file specified with the :option:`-param` parameter.

.. option:: -prefix

   Controls the name of the default param file.

   [Default=combine_receptors]

.. option:: -outputdir

   Write the merged receptors to the directory specified (the directory must
   already exist).

.. option:: -verbose

   Show that matching status of every receptor pair (whether it is merged or not)

   [Default=false]




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _DU2OEBReceptor:

******************
DU2OEBReceptor
******************

.. program:: DU2OEBReceptor

Overview
===================

:ref:`DU2OEBReceptor` is a utility program to convert a design unit, OEDU file,
containing a receptor into a molecule based receptor, in OEB or OEB.GZ file.

.. note::

   The molecule based OEB or OEB.GZ receptors are no longer the preferred form
   of receptor, and instead receptors inside design unit in OEDU are desired.
   The :ref:`DU2OEBReceptor` is provided for a handful of cases where receptors
   inside design units in OEDU format cannot still be used.

   To make a receptor, use the :ref:`ReceptorInDU` or the :ref:`chapter_makereceptor`.

Example Commands
===================

Convert a receptor OEDU file into an OEB.GZ receptor
------------------------------------------------------

Converts the OEDU receptor file into an OEB.GZ receptor.

Input files

   * **receptor.oedu** : OEDU file to convert into an OEB.GZ receptor.

Command line

      .. code-block:: bash

         prompt> DU2OEBReceptor receptor.oedu receptor.oeb.gz

Output files

   * **receptor.oeb.gz** : OEB.GZ version of the receptor.

Command Line Help
===================

A description of the command line interface can be obtained by executing **DU2OEBReceptor**
with the `--help` option.

.. code-block:: console

   > du2oebreceptor --help

will generate the following output:

::

   Help functions:
     du2oebreceptor --help simple      : Get a list of simple parameters
     du2oebreceptor --help all         : Get a complete list of parameters
     du2oebreceptor --help defaults    : List the defaults for all parameters
     du2oebreceptor --help <parameter> : Get detailed help on a parameter
     du2oebreceptor --help html        : Create an html help file for this program
     du2oebreceptor --help versions    : List the toolkits and versions used in the application

Required Parameters
===================

.. option:: -in <filename>

   An OEDU file containing a receptor.

   [keyless parameter 1]

Optional Parameters
===================

Input Options
---------------

.. option:: -molnames

   This parameter specifies a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set then only molecule in the
   input file(s) (see parameter :option:`-in`) with names that match those
   in the text files will be read in.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecule(s) that are contained in a large database, without
   having to extract those molecules by hand from the database.

Output Options
---------------

.. option:: -out <filename>

   An OEB or OEB.GZ file containing receptor.

   [keyless parameter 2]

.. option:: -prefix

   Prefix used to name output files.

.. option:: -progress

   Show progress on screen.  Options are 'none', 'dots', 'log' and 'percent'.  
   The 'dots' options will displays dots on screen to show molecules 
   completed.  The 'log' option will duplicate the log file on screen.
   The 'percent' option will track progress through the input file.  [Default=none]


.. _oedocking_releasenotes:

Release History
===============

.. toctree::
   :maxdepth: 2

   version4_3_5
   version4_3_4
   version4_3_3
   version4_3_2
   version4_3_1
   version4_3_0
   version4_2_1
   version4_2_0
   version4_1_2
   version4_1_1
   version4_1_0
   version4_0_0
   version3_5_0
   version3_4_0
   version3_3_1
   version3_3_0
   OEDocking_version3.2.0
   OEDocking_version3.0.1
   OEDocking_version3.0.0
   POSIT_version3.1.0
   POSIT_version1.0.3
   POSIT_version1.0.2
   POSIT_version1.0.1
   POSIT_version1.0.0
   FRED_version2.2.5
   FRED_version2.2.4
   FRED_version2.2.3
   FRED_version2.2.2
   FRED_version2.2.1
   FRED_version2.2


#################
OEDocking 4.3.4
#################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************



OEDocking TK 4.3.4
================================================================================

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

*  An issue has been fixed where a receptor grid could not be constructed
   for covalently bonded ligands. 



###############################
OEDocking 4.3.3
###############################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


OEDocking TK 4.3.3
================================================================================

Minor internal improvements have been made.





OEDocking  4.3.2
================================================================================

Minor internal improvements have been made.



OEDocking TK 4.3.2
================================================================================

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

* The method :ref:`Optimize<OEDocking_OEPoseOptimizer_Optimize>` in
  :ref:`OEPoseOptimizer<OEDocking_OEPoseOptimizer>` now returns an ``unsigned``
  code corresponding to any possible failure, instead of a ``bool``. The
  method also takes additional arguments for protein and ligand masks in
  the :ref:`OEDesignUnit<OEBio_OEDesignUnit>`.

* The following methods have been added to the :ref:`OESinglePoseResult<OEDocking_OESinglePoseResult>`:

  * :ref:`GetRelaxAttempted<OEDocking_OESinglePoseResult_GetRelaxAttempted>`
  * :ref:`GetRelaxStatus<OEDocking_OESinglePoseResult_GetRelaxStatus>`
  * :ref:`GetRelaxStatusStr<OEDocking_OESinglePoseResult_GetRelaxStatusStr>`

* A new method, :ref:`MethodChoice<OEDocking_OEPosit_MethodChoice>`, has been added
  to :ref:`OEPosit<OEDocking_OEPosit>` that provides information on the method
  that would be used for the pose prediction of a given ligand against a given receptor.

* The new methods :ref:`GetTorLib<OEDocking_OEPositOptions_GetTorLib>` and
  :ref:`SetTorLib<OEDocking_OEPositOptions_SetTorLib>` have been added to
  :ref:`OEPositOptions<OEDocking_OEPositOptions>` to provide a choice for the
  torsion library that would be used for conformer generation during pose prediction.

* The following methods have been added to the :ref:`OEShapeFitOptions<OEDocking_OEShapeFitOptions>`:

  * :ref:`GetMaxLocalStrain <OEDocking_OEShapeFitOptions_GetMaxLocalStrain>`
  * :ref:`SetMaxLocalStrain <OEDocking_OEShapeFitOptions_SetMaxLocalStrain>`
  * :ref:`GetTorLib<OEDocking_OEShapeFitOptions_GetTorLib>`
  * :ref:`SetTorLib<OEDocking_OEShapeFitOptions_SetTorLib>`

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

* The method :ref:`Optimize<OEDocking_OEPoseOptimizer_Optimize>` in
  :ref:`OEPoseOptimizer<OEDocking_OEPoseOptimizer>` is now more robust in
  optimizing a docked pose.  Accordingly, :ref:`Docking<OEDocking_OEPosit_Dock>`
  with relaxation in :ref:`OEPosit<OEDocking_OEPosit>` is also now
  more robust.

* The function :ref:`OEHasClash<OEDocking_OEHasClash>` now properly
  recognizes all clashes between a ligand and a protein that were previously
  mistaken because of some misidentification of covalent bonds.

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

* Selection of the best receptor has been improved in :ref:`OEPosit<OEDocking_OEPosit_Dock>`,
  ensuring that the correct receptor will always be picked in case of a self-docking.

* The internal algorithm has been optimized to improve time requirements for
  :ref:`OEPosit<OEDocking_OEPosit_Dock>` when working with many receptors and a
  few ligands.





OEDocking  4.3.1
================================================================================

Minor internal improvements have been made.


.. _section_oedockingtk_releasenotes_4313:

OEDocking TK 4.3.1.3
================================================================================

* An issue has been fixed in :ref:`OEHasClash<OEDocking_OEHasClash>` such that
  strong atom clashes are no longer mistakenly marked as covalent bonds causing 
  failure to recognize those as actual clashes.


.. _section_oedockingtk_releasenotes_4310:

OEDocking TK 4.3.1.0
================================================================================

* An issue has been fixed that would occasionally cause segmentation faults
  when :ref:`OEPosit<OEDocking_OEPosit>` would internally fail to generate
  conformers.

* New methods, :ref:`GetPoseRelaxOptions<OEDocking_OEPositOptions_GetPoseRelaxOptions>`
  and :ref:`SetPoseRelaxOptions <OEDocking_OEPositOptions_SetPoseRelaxOptions>`,
  have been added to :ref:`OEPositOptions<OEDocking_OEPositOptions>` to allow more
  flexibility in relaxing the :ref:`OEPosit<OEDocking_OEPosit>` generated poses.

* Internal algorithms have been improved in :ref:`OEShapeFit<OEDocking_OEShapeFit>`
  to improve strain in generated poses.





OEDOCKING  4.3.0
================================================================================

Minor bug fixes
--------------------------------------------------------------------------------
* **POSIT** now correctly outputs the status of relaxation, indicating if
  flexible optimization was performed on the generated pose.

* Closing out of the ``save`` dialog in **MakeReceptor** no longer causes a
  "Failed Save" message.

* Constraint spheres now appear with appropriate colors when viewed in
  the *Finish* tab of **MakeReceptor**.



OEDocking TK 4.3.0
================================================================================

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

* Flexible **Posit** now uses ``FF14SB-SAGE`` force field for the
  protein/ligand complex optimization. 

* A new overload of :ref:`SetupRef <OEDocking_OEShapeFit_SetupRef>` has
  been added that allows using  :ref:`OEShapeFit <OEDocking_OEShapeFit>` with
  a bound ligand as the reference.

* The following new methods have been added to enable internal conformation generation 
  in :ref:`OEShapeFitOptions <OEDocking_OEShapeFitOptions>`:

   * :ref:`SetFullConformationSearch <OEDocking_OEShapeFitOptions_SetFullConformationSearch>`
   * :ref:`GetFullConformationSearch <OEDocking_OEShapeFitOptions_GetFullConformationSearch>`

* A new class, :ref:`OEShapeFitOptions <OEDocking_OEShapeFitOptions>`, has been added
  that allows estimating pose prediction confidence against different reference systems.
  This new class is complementary to the existing function
  :ref:`OEGetEstimatedPositProbability <OEDocking_OEGetEstimatedPositProbability>`.

Major bug fixes
--------------------------------------------------------------------------------
* An issue has been fixed where relaxation failed
  in :ref:`OEPosit <OEDocking_OEPosit_Dock>` when the pose 
  relaxation mode was set to either :ref:`ALL <OEDocking_OEPoseRelaxMode_ALL>`
  or :ref:`CLASHED <OEDocking_OEPoseRelaxMode_CLASHED>`.

* An issue causing generation of bent ring structures 
  and high strain poses when performing :ref:`OEPosit <OEDocking_OEPosit_Dock>` 
  has been fixed.

* An issue has been fixed that caused flexible
  :ref:`OEPosit <OEDocking_OEPosit_Dock>` 
  with :ref:`ALL <OEDocking_OEPoseRelaxMode_ALL>` relaxation mode to fail while
  generating nonclashing poses when
  :ref:`NONE <OEDocking_OEPoseRelaxMode_NONE>` was successful.

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

* An issue where :ref:`Dock <OEDocking_OEPosit_Dock>` passed too many conformers 
  for flexible optimization with relaxation in
  :ref:`OEPosit <OEDocking_OEPosit>` has been fixed. Now, :ref:`OEShapeFit <OEDocking_OEShapeFit>`
  no longer passes too many conformers for flexible optimization that could
  occasionally cause a less accurate conformer to become the top predicted pose.

* The :ref:`Dock <OEDocking_OEPosit_Dock>` method with relaxation has been modified to
  be more aligned with
  other modes of failure when ligand charge assignments fail.




.. _section_oedocking_releasenotes_4211:

OEDOCKING  4.2.1.1
================================================================================

* An issue where the shape contour could extend out of the user-defined box has been fixed.
  The grid will fill the initial box adjusting for grid spacing, and the resulting re-drawn
  box will be slightly larger to sit at the edge of the generated grid.

* The generate shape contour button can now only be clicked a subsequent time if
  a different user selection has been made that would cause the contour to change.

.. _section_oedocking_releasenotes_4210:

OEDOCKING  4.2.1.0
================================================================================

Major bug fixes
--------------------------------------------------------------------------------
* **Posit** now correctly provides only the nonclashing poses in the generated
  output file when running with ``-num_poses`` greater than one and results
  in a mix of clashed and nonclashed poses for a particular ligand.

* **Posit** now provides three-dimensional structures in the clashed output file.

* An issue in **Posit** that caused occasional relaxation of nonclashing poses
  when running with the ``-relax`` option set to ``clashed`` has been fixed.

* Possible inconsistent behavior and/or crashes in **MakeReceptor**, while editing custom
  constraints or selecting a constraint from the list of created constraints, have been fixed.



OEDocking TK 4.2.1
================================================================================

New features
--------------------------------------------------------------------------------
* A new preliminary API class, :ref:`OEShapeFitOptions <OEDocking_OEShapeFitOptions>`,
  has been added to allow better control over option parameters for 
  :ref:`OEShapeFit <OEDocking_OEShapeFit>`. The constructor for the
  preliminary class :ref:`OEShapeFit <OEDocking_OEShapeFit>` now takes
  :ref:`OEShapeFitOptions <OEDocking_OEShapeFitOptions>` as an argument instead
  of :ref:`OEFlexiOverlayOptions <OEShape_OEFlexiOverlayOptions>`. Also,
  :ref:`SetFlexiOverlayOptions <OEDocking_OEPositOptions_SetFlexiOverlayOptions>`
  and :ref:`GetFlexiOverlayOptions <OEDocking_OEPositOptions_GetFlexiOverlayOptions>`
  now accept and return :ref:`OEShapeFitOptions <OEDocking_OEShapeFitOptions>`.

Major bug fixes
--------------------------------------------------------------------------------
* The :ref:`Dock <OEDocking_OEPosit_Dock>` method in :ref:`OEPosit <OEDocking_OEPosit>`
  now returns poses instead of a failure, if there is a failure during flexible optimization.

* An issue that caused intermittent crash for specific calculations on specific
  platforms when working with :ref:`OEPosit <OEDocking_OEPosit_Dock>` has been fixed.

* :ref:`OEPosit <OEDocking_OEPosit_Dock>` now accurately returns
  :ref:`NoValidNonClashPoses <OEDocking_OEDockingReturnCode_NoValidNonClashPoses>`
  as status when the predicted pose contains clashes based on the
  :ref:`defined clash allowed type<OEDocking_OEPositOptions_SetAllowedClashType>`.
  Note that the clashed poses can still be retrieved from the resulting
  :ref:`OESinglePoseResult <OEDocking_OESinglePoseResult>` if desired.

Minor bug fixes
--------------------------------------------------------------------------------
* The :ref:`RankDesignUnits <OEDocking_OEPosit_RankDesignUnits>` method is
  now properly wrapped in python.

Documentation changes
--------------------------------------------------------------------------------
* Documentation has been added for 
  :ref:`the function OEGetEstimatedPositProbability <OEDocking_OEGetEstimatedPositProbability>`, which works with
  :ref:`OEDesignUnit <OEBio_OEDesignUnit>`.

* Documentation has been added for :ref:`the function OESetupBox <OEDocking_OESetupBox>`, which supports
  :ref:`OEMolBase <OEChem_OEMolBase>` and :ref:`OEMCMolBase <OEChem_OEMCMolBase>`.






OEDOCKING  4.2.0
================================================================================

*Fall 2022*

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

*   The **Posit** application now uses the new
    :ref:`OEShapeFit <OEDocking_OEShapeFit>`
    API for flexible fitting with
    Shape/Color and Forcefield. The new algorithm replaces the currently existing
    ShapeFit algorithm that uses adiabatic optimization.
    A modified ShapeFit algorithm optimizes the shape and chemical similarity between
    the fit molecule and bound ligand present in the reference design unit,
    along with intra-molecular forcefield energies of the fit molecule. The
    :ref:`SAGE <OEFF_OELigandFFType_SAGE>` ligand force field is used during this
    optimization.

* Spruce Filter was added to **MakeReceptor**, to assist in structure standardization
  prior to structure preparation.

Minor bug fixes
-------------------------------------------------------------------------------
* **Posit** now prints out more concise warning messages.

OEDocking TK 4.2.0
===================

New features
--------------------------------------------------------------------------------
* Two new preliminary API classes, :ref:`OEShapeFit <OEDocking_OEShapeFit>` 
  and :ref:`OEShapeFitResults <OEDocking_OEShapeFitResults>` have been added which 
  provides functionality for pose generation based on flexible fitting with Shape/Color 
  and Forcefield.

* The adiabatic optimization algorithm of ``ShapeFit`` method for pose 
  generation in :ref:`OEPosit <OEDocking_OEPosit>` has been replaced by a new
  simultaneous flexible fitting algorithm, as implemented in :ref:`OEShapeFit <OEDocking_OEShapeFit>`.
  The new algorithm uses :ref:`Sage <OEMolSmirnoff_OESage>` as the default forcefield,
  instead of :ref:`MMFF <OEMolMMFF_OEMMFF>`.

* Two new methods, :ref:`SetFlexiOverlayOptions <OEDocking_OEPositOptions_SetFlexiOverlayOptions>`
  and :ref:`GetFlexiOverlayOptions <OEDocking_OEPositOptions_GetFlexiOverlayOptions>`,
  have been added to :ref:`OEPositOptions <OEDocking_OEPositOptions>` to expose
  parameters related to :ref:`OEShapeFit <OEDocking_OEShapeFit>` in :ref:`OEPosit <OEDocking_OEPosit>`.

Major bug fixes
--------------------------------------------------------------------------------
* An issue that caused a segmentation fault when using 
  :ref:`CacheScoringSetup <OEDocking_OEScore_CacheScoringSetup>` has been fixed.

Documentation changes
--------------------------------------------------------------------------------
* New C++ and Python examples have been added to the :ref:`section_examples_shapefit` 
  section that demonstrate how to flexibly fit input multi-conformer molecules 
  into a design unit that contains a bound ligand.










OEDOCKING  4.1.2
================================================================================

*Spring 2022*

Minor bug fixes
-----------------------------------------------
* Typos in the help text for **ReceptorInDU** have been fixed.

* Typos in the help text for **ReceptorToolbox** have been fixed.

* An issue causing **MakeReceptor** to crash when editing protein constraints has been fixed.
  


OEDocking TK 4.1.2
================================================================================

*Spring 2022*

* Minor internal improvements have been made.





OEDOCKING  4.1.2
================================================================================

*Spring 2022*

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

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

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



OEDocking TK 4.1.2
================================================================================

*Spring 2022*

* Minor internal improvements have been made.





OEDOCKING  4.1.0
================================================================================

*July 2021*

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

* The :ref:`MakeReceptor <chapter_makereceptor>` GUI application has been extended
  to be a fully functional DesignUnit and receptor builder. A new
  design unit can be created from a ``PDB/MMCIF`` file (with or without an associated
  ``MTZ`` file), or by combining molecules from various molecule files of any format.
  :ref:`SPRUCE <chapter_spruce>` options are exposed through a graphical interface giving
  users control over the level of preparation the structure should go through.
  Existing receptors, both in ``OEDU`` or ``OEB`` format, can also be opened and edited 
  in :ref:`MakeReceptor <chapter_makereceptor>`.

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

* Apps will now fail with error message if an invalid database with no molecules is provided.

* ``Spruce4Docking`` has been removed. We recommend using :ref:`SPRUCE <chapter_spruce>` instead.

* :ref:`POSIT <chapter_posit>` output now contains receptor filename as SD data.

* :ref:`ReceptorInDU <ReceptorInDU>` now generates receptors and reports multiple design units
  in a single output ``OEDU`` file.

* :ref:`OEB2DUReceptor <OEB2DUReceptor>` now converts and reports multiple design units within a single
  output ``OEDU`` file.


OEDocking TK 4.1.0
================================================================================

*July 2021*

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

* A predicate string can now be supplied to :ref:`OEMakeReceptorOptions <OEDocking_OEMakeReceptorOptions>`
  using :ref:`SetTargetPred <OEDocking_SetTargetPred>`. This
  povides a way to specify a select set of water molecules in an :ref:`OEDesignUnit <OEBio_OEDesignUnit>` to be part
  of the receptor when the docking grid is constructed and used in subsequent
  docking calculations.

* :ref:`OEMakeReceptor <OEDocking_OEMakeReceptor>` now autogenerates protein constraints.
  The constraints are left disabled by default for the docking calculations. These can be enabled using the toolkits,
  or the Make Receptor GUI application.
  The auto-generation of the constraints can be turned off using the
  :ref:`SetAutoConstraints <OEDocking_SetAutoConstraints>` method in
  :ref:`OEMakeReceptorOptions <OEDocking_OEMakeReceptorOptions>`.

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

* The default value for the :ref:`SetBoxMol <OEDocking_SetBoxMol>`
  has been set to ``0.0`` in the :ref:`OEMakeReceptorOptions <OEDocking_OEMakeReceptorOptions>` class.





.. _section_oedocking_app_releasenotes_4002:

OEDOCKING  4.0.0.2
================================================================================

*March 2021*

* The default value of the ``-targetMask`` parameter in :ref:`ReceptorInDU` has been
  changed to ``targetComplexNoSolvent`` to reflect best practices for receptor
  generation.

* The ``-targetMask`` parameter in :ref:`ReceptorInDU` now provides added
  flexibility to create user defined masks.

* Protein constraints, custom constraints, and extra molecules are now
  properly transferred and serialized when converting OEB format receptors to
  OEDU format receptors using :ref:`OEB2DUReceptor`.

* :ref:`POSIT <chapter_posit>` now properly handles ``.lst`` files containing
  empty lines as input to ``-receptor`` parameters.

* Component names are now consistent when converting between ``OEChem::OEMolBase`` and ``OEBio::OEDesignUnit`` receptors.

* Documentation regarding :ref:`Receptors <receptor_theory>` has been updated.

OEDocking Toolkit Information
-----------------------------

For additional details, see :ref:`OEDocking TK 4.0.0.2 <section_oedocking_releasenotes_4002>`.

.. _section_oedocking_app_releasenotes_4000:

OEDOCKING  4.0.0.0
================================================================================

*Fall 2020*

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

* A new utility, :ref:`ReceptorInDU`, has been added that makes a receptor inside
  a design unit OEDU file.

* A new utility, :ref:`OEB2DUReceptor`, has been added that converts a receptor
  OEB or OEB.GZ file into a OEDU receptor file.

* The GUI application :ref:`MakeReceptor <chapter_makereceptor>` now reads OEDU files
  and outputs OEDU receptor files, with receptors created inside a design unit.

* The following programs in the **OEDocking** applications suite now expect
  OEDU files (with receptors inside a Design Unit), for receptors. These
  programs no longer support receptor input from OEB or OEB.GZ files.

  * :ref:`FRED <chapter_fred>`
  * :ref:`HYBRID <chapter_hybrid>`
  * :ref:`POSIT <chapter_posit>`
  * :ref:`scorepose`
  * :ref:`receptor_toolbox`
  * :ref:`docking_report`

* **POSIT** now produces OEDU files as output containing
  design units consisting of pose ligand structures and protein active site structures.

* A new parameter, ``-nostructs``, has been added to **FRED** and **HYBRID**. When this
  flag is set to ``true``, both the docked and undocked structure files will be suppressed.

* A new utility, :ref:`DU2OEBReceptor`, has been added that converts an OEDU receptor
  file into a receptor OEB or OEB.GZ file.

* The utility ``DU2Receptor`` has been removed from the **OEDocking** application suite.
  The receptors are now created inside a design unit, and can be created using the
  :ref:`ReceptorInDU` utility application.

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

* The Tutorials section has been updated.


.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _fred_releasenotes_22:

FRED 2.2.0
========================

New Features / Improvements
---------------------------

Optional GUI setup and preparation of the active site (the actual docking remains command line). The GUI allows users to

* Separate bound ligands and solvent molecules from the protein structure.

* Detect active sites, and adjust the box defining the active site.

* Manually tweak residue protonation states.

* Visualize and adjust the complimentary shapes **FRED** uses during the exhaustive search.

* Specify constraints.

A new version of the Chemgauss scoring function, version 3, which includes new desolvation terms as well as improved typing.

Ligand based design scoring functions, C.G.O (Chemical Gaussian Overlay) and C.G.T. (Chemical Gaussian Tanimoto). These functions score be measuring how well a molecules shape and chemistry overlay a known bound ligand placed in the active site.

All new algorithm for generating the negative image of the active site using molecular shape probes, as opposed to the atomic probes uses earlier.

On the fly preparation of MASC data for runs using the MASC variant scoring functions is now an option. Pre-calculating MASC data is still available and most efficient when doing multiple runs.

Changes
-------

FRED now uses a special receptor file to describe the active site. This file can be created interactively using the new fred_receptor GUI program, or on the fly with the command line using the same flags as the previous version of **FRED** (2.1.x).

The functionality of the masc_prep and ligand_info programs distributed with the previous version (2.1.x) have been merged into the main fred executable.

Version 1 of Chemgauss has been removed, Version 2 is deprecated but still available.

Individual hitlist -size and -cut flags have be replaced by a single -hitlist_size flag. 

.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _fred_releasenotes_221:

FRED 2.2.1
=====================

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

* Added support for OEB rotor offset compression when writing the MASC tagged version of the input database (provided the initial input database used rotor offset compression).

* Chemscore's, OEChemscores's and Screenscores's hydrogen bonding terms now only allow one hydrogen bond per hydrogen. Also prevented two hydroxyls from making both and acceptor-donor interaction and a donor-acceptor interaction.

Changes
-------

* Modified OEChemscore's hydrogen bonding term to be more forgiving of non-ideal geometries. The range of geometries considered ideal is unchanged.

* Corrected a deficiency in Chemgauss3 metal term and metal constraints. The metal chelator interaction function was picking up on some but not all of the allowable geometries for metal-chelator interactions.

* Improved Chemscore's, OEChemscore's and Screenscore's handling of rotatable hydrogens involved in hydrogen bonding by replacing the brute force torsion driving search for the optimal hydrogen position with an analytic solution for the best position.

* Added a new flag "-no_masc_data_calc" which will prevent Fred from calculating MASC data for ligands. Any ligands that missing needed masc data will not be docked. The purpose of this flag is to prevent it from doing a lengthy MASC calculation when all but a handful of ligands have the required MASC data.

* Extended initial list of atom types know to Chemgauss3. This should improve the startup speed of runs using Chemgauss3, by avoiding costly grid recalculations each time a new atom type is encountered. This change is only for speed, there is no change to the Chemgauss3 score value Fred calculates.

* When using constraints fred now defaults to effectively using a -clash_scale value of 0.6 if the -clash_scale flag has not been set by the user. This helps eliminate unusually close protein-ligand contacts that can occasionally occur when constraints are used. The original behavior can be obtained by explicitly setting -clash_scale to 0. Runs without constraints are unaffected and behave as before.

* Chemgauss2 is no longer used by default in the consensus pose stage of docking. This has no real effect on docking performance and will reduces Fred's startup time. 

Bug Fixes
---------

* Important: Fixed a bug when using -pro and -box to create a receptor that causes the inner contour to be set to an extremely small value. The resulting receptor would produce extremely poor docking results without warning. In this release newly created receptors will now have reasonable inner contours. Additionally Fred now checks if the inner contour volume is extremely small (i.e., one that was produced by this bug), and if one is detected the inner contour is turned off and a warning is issued before proceeding with the run.

* Fixed a when requesting alternate poses during a PVM run, which caused the run to shutdown and not dock any molecules.

* Fixed a bug in screenscore when the receptor/protein it was initialized with did not have explicit hydrogens. The bug causes the initial setup to fail and the run to stop if screenscore was used. The error reported when this bug occurred was "Error! Screenscore::FindAcceptors (OH)".

* Fixed a crash bug when calculating MASC data for ligands on a 64bit machine.

* Fixed minor when reporting how many molecules in a database have MASC data. The percentage reported was erroneously divided by 100.

* Fixed a bug when using both the MASC and Non-MASC variants of a scoring function in the same run. The bug caused a shift in the Non-MASC score related to the precalculated MASC data, while the MASC variant score was correctly calculated. The error was especially damaging to CGT score.

* Fixed spelling error by changing parameter -recalculate_masc_data to -recalculate_masc_data. The original misspelling is now an alias to minimize impact on users with existing parameter files.

* Fixed bug checking for charges when -zapbind and -pro are used together. (Did not affect runs where -zapbind and -rec were being used). The bug caused the run to stop.

* Fixed a bug in -clash_scale flag, that causes the value passed to the flag to be ignored and a value of one to be used. If the -clash_scale flag was not used no bug occurred in this regard.

* Silenced the warning "OEInterface::Get, requesting value of unset parameter -addbox" when using the -box parameter without also specifying -addbox. The warning was spurious, no error occurred when it was issued.

* Slave of a multiprocessor run now longer require a license, only the master process requires a license now.


.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _fred_releasenotes_222:

FRED 2.2.2
=====================

Bug Fixes
---------

* Fixed a bug that causes the -pharm flag to be ignored.

* Cleaned up minor formatting issue when informing the user that a warning log has been opened. 

.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _fred_releasenotes_223:

FRED 2.2.3
=====================

Bug Fixes
---------

* Fixed a bug when using two custom constraints that caused all molecules to fail to dock with a NoConstraintMatch code. 

.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _fred_releasenotes_224:

FRED 2.2.4
=====================

Bug Fixes
----------

* Fixed crash when -refine and -no_dock were used together.

* Fixed crash when -clash_scale and a receptor without an inner contour is used. 

.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _fred_releasenotes_225:

FRED 2.2.5
=====================

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

* On Microsoft Windows platforms, the installer adds the ability to open command prompts that setup the user environment to run specific versions of **FRED** or the latest version of **FRED**.

Changes
-------

* **FRED** and **FRED_RECEPTOR** are now versioned and shipped together. 

Bug Fixes
---------

* **FRED** licenser has been updated to work with licenses that expire past the year 2009.

* The **FRED** licenser supports having the license file located in the users home directory.

* SD files are now written with the 3D flag set.

* Fixed issue where Fred could crash if -nodock is specified and the poses given to Fred to score are not within the receptor site.

.. _oedocking_releasenotes_300:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OEDocking 3.0.0
===============

*April 2012*

Changes
-------

The **OEDocking** 3.0.0 release is the first release of the **OEDocking** package, which
is an upgrade of the previous :ref:`chapter_fred` release packages.  The **OEDocking**
package includes :ref:`chapter_fred` along with a suite of new docking tools.  

As part of this **OEDocking** release the interface to :ref:`chapter_fred` has been 
streamlined.  Several functions of :ref:`chapter_fred` have been split out into separate
programs that are now part of the OEDocking suite, and several older features 
that have not proved to improve docking results (or in the worst case degrade
docking results relative to the defaults) have been removed.  

The features of **FRED** 2.2.5 that have been moved to separate utility programs in
3.0.0 are as follows

* **Receptor Creation**

  Receptors are now created either with the :ref:`chapter_makereceptor` GUI or the
  ``pdb2receptor``, ``apopdb2receptor``, or ``receptor_setup``
  command-line programs.  Existing receptors can now also be edited or modified
  with the :ref:`chapter_makereceptor` GUI or :ref:`RECEPTOR_TOOLBOX` command line 
  program.  These programs are all included in the OEDocking distribution.

  Relevant flags removed from FRED:

  * **-pro**

  * **-strip_water**

  * **-bound_ligand**

  * **-box**

  * **-addbox**

  * **-no_inner_contour**

* **Hybrid Docking**

  Hybrid docking is now available as a separate application, :ref:`chapter_hybrid`, 
  included in the OEDocking distribution.

* **Rescoring of poses**

  The feature to rescore existing poses is now available in a separate application,
  :ref:`SCOREPOSE`, included in the OEDocking distribution. 

The features of FRED 2.2.5 removed in 3.0.0  are as follows

* **Alternate Scoring Functions**

  :ref:`chapter_fred` now uses the improved Chemgauss4 scoring function.  This scoring
  function has better virtual screening and pose prediction performance than 
  any of the scoring functions available in FRED 2.2.5.  

  Relevant flags removed from FRED:

  * **-exhaustive_scoring**

  * **-opt**

  * **-shapegauss**

  * **-plp**
  
  * **-chemgauss2**

  * **-chemgauss3**

  * **-chemscore**

  * **-oechemscore**

  * **-screenscore**

  * **-cgo**

  * **-cgt**

  * **-zapbind**

  * **-consensus**

  * **-shapegauss_masc**

  * **-plp_masc**
  
  * **-chemgauss2_masc**

  * **-chemgauss3_masc**

  * **-chemscore_masc**

  * **-oechemscore_masc**

  * **-screenscore_masc**

  * **-cgo_masc**

  * **-cgt_masc**

  * **-zapbind_masc**

  * **-consensus_masc**
 
  * **-assign_ligand_charges**

* **MASC**

  Multiple Active Site Correction (MASC) was introduced in **FRED** 2.1 as a
  method of compensating for the size bias in scoring functions.  This size
  bias arises in many scoring functions where the interaction terms are all
  favorable interactions, and thus larger molecules score better since they
  can make more interactions.  Chemgauss4 (and Chemgauss3), however, has both
  favorable interactions (i.e., shape, hydrogen bonding and metal-chelator) 
  and unfavorable interactions (i.e., desolvation and clash), and therefore
  does not have a significant size bias that necessitates the use of MASC.

  Relevant flags removed from FRED:

  * **-reference_receptors**

  * **-no_masc_data**

  * **-recalculate_masc_data**

  * **-report_masc_failures**

* **Consensus Pose Selection**

  FRED 2.2.5 had slightly better pose prediction results when the best docked
  pose was selected using a consensus of three scoring function (Chemgauss3,
  Chemscore and PLP) rather than one (Chemgauss3).  The new Chemgauss4
  scoring function in the 3.0 release is not improved by this feature, and
  has therefore been removed.

  Relevant flags removed from **FRED**:

  * **-pose_select_weight_shapegauss**

  * **-pose_select_weight_plp**

  * **-pose_select_weight_chemgauss2**

  * **-pose_select_weight_chemgauss3**

  * **-pose_select_weight_chemscore**

  * **-pose_select_weight_oechemscore**

  * **-pose_select_weight_screenscore**

  * **-pose_select_weight_cgo**

  * **-pose_select_weight_cgt**

* **MMFF Refinement**

  Using this option in **FRED** 2.2.5 degraded the results for both pose prediction
  and virtual screening and significant increases the run time.

  Relevant flags removed from **FRED**:

  * **-refine**

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

* **Chemgauss4 scoring**

  Improved hydrogen bond detection vs. Chemgauss3.  Hydrogen bond network effects are also now accounted for.

* **Hybrid docking**

  Dock using ligand and protein structural information simultaneously

* **MPI**

  MPI is now supported on all platforms except Windows.

* **Docking Report**

  Creates an Adobe PDF docked report for selected docked molecules. 

* **Receptor tools**

  Streamlines the receptor setup GUI, and also added several command line tools for setting up receptors.

Bug Fixes
----------

* Fixed a bug where large hit lists (> ~50,000) would result is very slow runtimes.

* SD tag data on the input ligand is now retained.

* Added an option to toggle hardware rendering in the Make Receptor GUI application to correct Windows driver related 3D graphics issues.



.. _oedocking_releasenotes_301:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OEDocking 3.0.1
===============

*September 2012*

Changes
-------

The program dock_report has been renamed to :ref:`docking_report`.

The formatting of the :ref:`docking_report` has been significantly improved.

Improved the geometry detection for hydrogen bond protein constraints.  These
constraints should now be tighter.

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

The output of :ref:`docking_report` now includes

* Added a protein interaction fingerprint to the docking_report.

* XLogP 

* Polar surface area (PSA)

Bug Fixes
---------

Fix bug where clash detection between hydrogen bonding groups was occasionally to strict.

.. _oedocking_releasenotes_320:
.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OEDocking 3.2.0
===============

*December 2015*
Major Features
---------------

* :ref:`posit<chapter_posit>` is now part of the *OEDocking* suite
  (a *posit* license is still required to run
  :ref:`posit<chapter_posit>`).

* Improved :ref:`posit<chapter_posit>`'s clash detection.
  :ref:`posit<chapter_posit>` now ignores on a per atom basis
  clashes with the protein that the crystallographic ligand also makes.

* OpenMPI version 1.6 is now supported on all platforms. The -mpi_np and
  -mpi_hostfile flags are now used to run :ref:`fred<chapter_fred>`, :ref:`hybrid<chapter_hybrid>` and :ref:`posit<chapter_posit>` in MPI
  mode. These new flags replace the oempirun script.

* ``pdb2receptor`` now incorporates all of *make_pose_receptor*'s functionality.
  *make_pose_receptor* has now been retired.

* ``pdb2receptor`` now supports the identification and selection of a desired
  ligand in a protein-ligand complex.

Minor Features
--------------

* :ref:`chapter_makereceptor`, ``pdb2receptor``,
  ``apopdb2receptor``,
  :ref:`docking_report<docking_report>`,
  ``receptor_setup`` and
  :ref:`receptor_toolbox<receptor_toolbox>` now all accept either a posit or
  fred2 license.

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

* :ref:`chapter_makereceptor` no longer routinely crashed under a
  Japanese version of Windows.

* Fixed a bug where pdf's generated by :ref:`docking_report<docking_report>`
  causes an error under Windows versions of Acrobat.

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

* Fixed an off by one error in :ref:`hybrid<chapter_hybrid>`'s progress reporting
  of how many molecules have been docked.

* Fixed a bug where :ref:`fred<chapter_fred>`, :ref:`hybrid<chapter_hybrid>` or
  :ref:`posit<chapter_posit>` could crash if given a protein structure with
  non-sensical atom states.


.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _posit_releasenotes_100:

POSIT 1.0.0
============

*November 2011*

First release of **POSIT**.

Traditional structure based pose-prediction has not been very accurate
in reproducing crystallographic poses.  This can be rectified by using
all of the information present in a crystal structure - both ligand
and protein structure.  **POSIT** is a flexible docking technique that
uses both the known protein and ligand structure to predict poses.
Furthermore, using this information generates a probability that the
predicted pose is indeed correct.  This has far reaching implications
for real world lead optimization scenarios including measuring
confidence but also the ability to select the existing crystal
structure that best predicts the docked pose for a given molecule. 

Features
--------

* Probability based pose-prediction
* Performs better than structure-based pose-prediction for poses similar
  to known bound ligands.
* All-atom optimization of poses based on known bound-ligands and 
  ligand-protein interactions.
* Fast detection of best known receptor (complex) to determine pose.



.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _posit_releasenotes_101:

POSIT 1.0.1
============

*February 2012*

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

* In some rare cases the -mcs flag could cause a portion of the posed ligand
  to be fixed in space while the rest was optimized correctly, this causes
  very bad geometry molecules that can score very well.  **POSIT** has been
  fixed to optimize the whole molecule in such cases.

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

* The version numbers for make_pose_receptor and combine_receptors were being
  incorrectly output in the OpenEye Banner, this has been updated to reflect
  the correct **POSIT** version.

Minor Features
--------------

* -outputall flag has been added to send all computed output to the file specified
  by **-out**, **-outcomplexes** or **-outreceptors**.  It as a shortcut for:

  .. code-block:: bash

    -minInitialTanimotoCombo 0.0 -minTanimotoCombo 0.0 -minProbability 0.0 \
      -allowedClashes allclashes

* if any of the input receptors has a clashing ligand, a warning will be output
  and POSIT will be set to accept clashes of the same severity as the receptor
  ligand.

* **POSIT** can now stream output specified by the `-out` switch to stdout using the
   command line switch *-out .sdf* or *-out .oeb*

.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _posit_releasenotes_102:

POSIT 1.0.2
============

*July 2012*

Major Features
---------------

* The optimizer has been enhanced to produce better aligned structures
  in certain cases.

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

* A memory leak in the optimizer has been fixed, **POSIT** now properly
  handles large streams of molecules.

* The -mcs flag has been turned off by default.  In some cases, the
  mcs was taking far too long for no real benefit in pose prediction.

.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _posit_releasenotes_103:

POSIT 1.0.3
============

*September 2012*

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

* Stereo isomer detection was not handling bridgeheads properly,
  this caused some non-stereo molecules to be identified as such.

.. |product|        replace:: POSIT
.. |accente|          unicode:: U+00E9
    :trim:
.. |accenta|          unicode:: U+00E0
    :trim:

.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*	

.. |BIOP|     replace:: *Biopolymers*

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _posit_releasenotes_310:

POSIT 3.1.0
============

*June 2014*

Major Features
---------------

* The :ref:`hybrid<chapter_hybrid>` and :ref:`fred<chapter_fred>` algorithms have been incorporated into :ref:`posit<chapter_posit>`, the appropriate
  method is determined by analyzing the ligand to pose against the input receptors.
* Multiprocessing has been enabled through the use of MPI, to speed calculations.
* :ref:`posit<chapter_posit>` now supports a *list of receptors files* or **.lst** file as input.
  This overcomes command-line limitations for the number of receptors that
  can be used simultaneously.
* Added a *MEDIOCRE* result rating for results between 33% and 50% probability.
* Command line parameters have been simplified and updated to be compatible with
  the *OEDocking* Suite of tools.  The following command-line options have been removed, 
  see the documentation for full details.

  * outcomplexes
  * outreceptors
  * clashcomplexes
  * clashreceptors
  * alternatePoses
  * cleanupWithProtein
  * mcs
  * minInitialProbability
  * minInitialTanimotoCombo
  * minTanimotoCombo
  * probabilityStop
  * scatter
  * selectReceptorBy
  * strain

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

* :ref:`posit<chapter_posit>` no longer automatically strips out incoming SDData fields.

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

* The default for the option *-ignore_nitrogen_stereo* has been changed to *true*
  to account for the nature of time-averaged crystallographic structures.


OEDocking 3.3.0
================================================================================

*November 2018*

* This version of **OEDocking** has been built using **OEToolkits 2018.Oct**. The 
  previous version was built using **OEToolkits 2015.Jun**.

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

* **ScorePose** no longer requires an **OEChem TK** license.

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

* The ``-force_planar_aromatic`` flag has been removed from **POSIT**.


OEDocking 3.3.1
================================================================================

*May 2019*

* This version of **OEDocking** has been built using **OEToolkits 2019.Apr**. The previous
  version was built using **OEToolkits 2018.Oct**.

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

* **POSIT** now correctly uses the :ref:`FRED<section_docking_algorithm>` method
  when there is no bound ligand in the receptor.

* **POSIT** now correctly uses the :ref:`FRED<section_docking_algorithm>` method
  when the similarity between the bound ligand and posed ligand is very low.

* A bug that  caused a memory  issue in **FRED** has been fixed

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

* The ``hybrid_Score.txt`` file now starts at 1 instead of 0 when labeling the poses,
  from a **Hybrid** calculation.


OEDocking 3.4.0
================================================================================

*Nov 2019*

* This version of **OEDOCKING** has been built using **OEToolkits 2019.Oct**. The previous
  version was built using **OEToolkits 2019.Apr**.

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

* New utility application, **Spruce4Docking**, has been added to
  properly prepare structures for receptor generation.  The output from **Spruce4Docking**
  is an :ref:`OEDesignUnit <OEBio_OEDesignUnit>` object serialized to a new ``OEDU`` file format.
  Alternatively, users with access to **SPRUCE** can take the **SPRUCE**-generated ``OEDU``
  files directly and bypass **Spruce4Docking**.

* New utility application, **DU2Receptor**, has been added that can be used to create
  a receptor from design units contained in an ``OEDU`` file.  With the addition of
  **DU2Receptor** and **Spruce4Docking**, previously existing utilities ``ApoPdb2Receptor``,
  ``Pdb2Receptor``, and ``ReceptorSetup`` are no longer required and has been removed
  from the **OEDocking** applications suite.

* **POSIT** has been rewritten to take advantage of the newly extended corresponding **POSIT**
  functionality in the **2019.Oct** release of the **OEDocking TK**.  With this update, some of
  the previous application-specific functionality, including working with multiple receptors,
  finding the best receptor for a specific ligand, and clash checking, are now directly
  taken care of by the toolkit functionality. From a performance point of view, **POSIT** is
  now more efficient in finding a pose for a ligand when working with multiple receptors. On the
  downside, there is a slight increase in memory usage and time with use of an increasing number
  of receptors.

* The ability to further refine generated poses has been added to **POSIT**. The optional
  relaxation allows for greater flexibility of the ligand and parts of the receptor.  A new parameter,
  ``-relax``, has been added that defines if and when this post-pose generation relaxation
  should be performed.

* Definition of  "clash" and "clash types" have been redefined to be in sync with the definitions
  in the corresponding functionality in **OEDocking TK**.  The new clash definitions are based on
  perceived protein-ligand interactions. Accordingly new type ``hclashes`` have been introduced in
  ``-allowed_clashes`` that redefines ``mildclashes``.

* The ``-conftest`` parameter has been removed from all **OEDOCKING** applications.

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

* **POSIT** no longer gives up when the pose generated from the single best receptor produces a
  clash, and instead continues to generate poses with subsequent best receptors until a
  clash free pose is generated.

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

* An issue regarding **POSIT** to fail to maintain SD Data from the input molecule has been fixed.

* An issue in **HYBRID** that caused a single molecule with enumerated nitrogen stereo to be treated as multiple
  molecules has been fixed.

* An issue that caused **HYBRID** to fail to output undocked molecules to the undocked molecule file for large
  runs has been fixed.

* An order dependent issue in **POSIT** that affected choosing the best receptor when working with multiple receptors
  has been fixed.  **POSIT** now gives the same result regardless of the
  order in which receptors are provided.

* An issue regarding **POSIT** to fail to report the correct number of molecules process has been fixed.

* **POSIT** no longer crashes when a single atom input molecule is passed.

* **CombineReceptors** now recognizes the ``-prealigned`` flag.



OEDocking 3.5.0
================================================================================

*Spring 2020*

* This version of **OEDocking** has been built using **OEToolkits 2020.0**.

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

* The Windows version of **Make Receptor** now displays the user's home directory
  when `File Open` is first clicked.

* **Make Receptor** file filters have been simplified to only include
  `Molecules`, `Receptors`, and `All Supported Formats`.
  The `Molecules` filter now includes CIF and CIF.gz file extensions.

* Users can now browse to find their license file.

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

* The utilities section has been updated with accurate information on supported applications
  and their usage.


.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _oedocking_citation:

*************
Citation
*************

.. note:: To cite OEDOCKING please use the following:

    OEDOCKING |oedocking_version|. OpenEye, Cadence Molecular Sciences, Inc., Santa Fe, NM. http://www.eyesopen.com.

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W.
POSIT: Flexible Shape-Guided Docking For Pose Prediction.
J. Chem. Inf. Model., 2015, 55, 1771-1780.
DOI: 10.1021/acs.jcim.5b00142

McGann, M.
FRED Pose Prediction and Virtual Screening Accuracy.
J. Chem. Inf. Model., 2011, 51, 578-596.
DOI: 10.1021/ci100436p

McGann, M.
FRED and HYBRID docking performance on standardized datasets.
J. Comput. Aided Mol. Des., 2012, 26, 897-906.
DOI: 10.1007/s10822-012-9584-8


.. omega documentation master file
.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



#################################
OMEGA |omega_version|
#################################
               
.. toctree::
   :maxdepth: 3

   introduction
   filter/filter
   omega/omega
   utilities
   theory/omega_theory
   releasenotes/index
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt





.. _omega_introduction:

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


************
Introduction
************

==============
Overview
==============

**OMEGA** is a tool for generating 3D conformations of molecules.
**OMEGA** provides two different methods for conformation generation: torsion driving and distance geometry. The torsion driving method works best on molecules that do NOT contain large, flexible rings, while the distance geometry method works for all molecules but has been designed for molecules that do contain large, flexible rings (macrocycles).

The minimal input into **OMEGA** is a file of molecules, with all stereocenters defined (see flipper below) in any readable format. The minimal output is a file of molecules with conformations.

==============
Applications
==============

The **OMEGA** distribution comprises two applications:

  :ref:`OMEGA <chapter_omega>`

  * Generates conformations for molecules in the input file.

  :ref:`FILTER <chapter_filter>`

  * Removes molecules in the input file that do not conform to a set of  physicochemical properties.
  * Molecules should be processed through **FILTER** before using **OMEGA**.

==================
Utility Programs
==================

The following utility programs are also included in this distribution:

* :ref:`chapter_flipper`: Enumerates all (unspecified) stereocenters in input molecules,
  ensuring that every stereocenter in a molecule is defined. These stereoisomers are then suitable
  for input to **OMEGA**.

* :ref:`MakeFraglib <chapter_makefraglib>`: Generates 3D fragment geometries for rings and linkers and
  makes a custom library of these fragments for **OMEGA**.

* :ref:`chapter_oebtosdconf`: Converts **OMEGA** conformers
  from OEB format into a form usable by MOE. This is a helper utility for users of the MOE tool.

Conformations from **OMEGA** can be used as input into several other **OpenEye** tools, including **OEDocking**, **ROCS**, and **Freeform**.

.. _chapter_filter:

FILTER
======

.. toctree::
   :maxdepth: 2

   filter_overview
   filter_examples
   filter_help
   filter_req_params
   filter_opt_params
   filter_files

.. _filter_overview:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: filter

======================
Overview
======================

Filtering based on graph and physical properties should
always be carried out prior to generating multiconformer databases
using **OMEGA**.  Eliminating undesirable compounds prior to generating
conformers saves execution time of both **OMEGA** and downstream
applications, as well as storage space.  Large polypeptides or proteins, very
flexible molecules, or molecules that would never be considered
useful for the ultimate modeling application are best eliminated from
a dataset as soon as possible.

The most important graph filter to apply is rotatable bond count.
Although **OMEGA** may be able to generate conformers for molecules with
more than 20 rotatable bonds, the results of such an exercise would be
dubious at best for any conformer generation method. The number of rings,
especially flexible rings, should also be used to exclude irrelevant
molecules. **OMEGA** will handle molecules that have many thousands of
possible ring combinations, although the time expenditure may be
prohibitive and the results equally questionable to molecules with an
unreasonably large number of rotatable bonds.  Simple element filters
may be useful as well, although **OMEGA** will discard compounds for which
no force field parameters exist.  Using element filters beforehand may
aid in tracking the rationale for discarding compounds instead
of searching through **OMEGA** log files for failure modes.

The **FILTER** program from OpenEye, Cadence Molecular Sciences provides
all of the functionality outlined above, and additional physical
property filters.  **FILTER** should be used for input file preparation of
large datasets.


.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _filter_examples:

.. program:: filter

======================
Example Commands
======================

.. note::

   ``filter`` may need to be replaced by ``filter.bat`` on Windows PowerShell.

This section includes several sample **FILTER** command line executions.  Each
example is followed by a brief description of its behavior.

.. code-block:: bash

   prompt> filter drugs.smi drugs.oeb.gz
   prompt> filter -in drugs.smi -out drugs.oeb.gz

These two commands will yield identical results.  These execute **FILTER** with the
default parameters.  The file `drugs.smi` is opened in SMILES format for
input, and the output is written to the file `drugs.oeb.gz` in gzipped
OEBinary version 2 format.

.. code-block:: bash

   prompt> filter -in drugs.smi -out drugs.sdf -filter myfilter

This command is the same as the one above except for the `-filter` flag.
It executes **FILTER** with the parameters found in the `myfilter` file.
The file `drugs.smi` is opened in SMILES format for input, and the output
is written to the file `drugs.sdf`.

.. code-block:: bash

   prompt> filter -param myparameters drugs.smi drugs.oeb.gz
   prompt> filter drugs.smi drugs.oeb.gz -param myparameters

The first of these two commands will yield exactly the same results as the
example above.  The file `drugs.smi` will be mapped to the `-in` flag and
`drugs.oeb.gz` will be mapped to the `-out` flag, being the second to
last and last command line arguments, respectively.  Unfortunately, the second
of these two commands will fail to parse because the implicit input and output
arguments are not the final two arguments in the list.

.. code-block:: bash

   prompt> filter -in drugs.smi -out drugs.oeb.gz -table drugs.table

This executes **FILTER** on the file `drugs.smi` and writes molecules that
pass the filter to the file `drugs.oeb.gz`.  It also writes all of the filter data to the tab-separated value file `drugs.table`.

.. code-block:: bash

   prompt> cat maybridge.05-1.sdf |filter -in .sdf -out .ism|oeomega classic .ism m.oeb.gz

This command presumes that you have an SD format file called
`maybridge.05-1.sdf`.  That file is piped to the **FILTER** program.
The `-in .sdf` flag indicates that **FILTER** should read .sdf format from
std::in.  Since no `-filter` flag is specified, the default filter will be
used.  The `-out .ism` flag indicates **FILTER** will write isomeric smiles
format to std::out.  The output would then be piped into **OMEGA**.

.. code-block:: bash

   prompt> filter -in drugs.smi -out drugs.oeb.gz -select "[N;$(*-a)]"

This command will filter the compounds in `drugs.smi` with the default filter
and write the output to `drugs.oeb.gz`.  It
also requires that molecules contain exactly one instance of the aniline
substructure defined by the SMARTS pattern `"[N;$(*-a)]"`.

.. note::

   ``filter.bat -in drugs.smi -out drugs.oeb.gz "-select [N;\`$(*-a)]"`` must be used
   instead on Windows PowerShell.



.. _filter_interface:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: filter

========================
Command Line Help
========================

A description of the command line interface can be obtained by executing **FILTER**
with the `--help` option.

.. code-block:: bash
   
   prompt> filter --help

will generate the following output:

::

  Help functions:
    filter --help simple      : Get a list of simple parameters
    filter --help all         : Get a complete list of parameters
    filter --help <parameter> : Get detailed help on a parameter
    filter --help html        : Create an HTML help file for this program


.. _filter_req_params:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


========================
Required Parameters
========================

.. option:: -in

   File containing one or more molecular connection tables from
   which you would like to remove the non-medicinal compounds.
   [Aliases=**-i**]

.. option:: -out

   File to fill with the molecules that pass all of the
   specified filters.
   [Aliases=**-o**]


.. _filter_opt_params:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


============================
Optional Parameters
============================

Execute Options
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -param

   The argument for this flag is the name of a
   file containing control parameters.  The control parameter file acts
   to either replace or augment the command line interface.  All
   parameters necessary for program execution may be provided in the
   control parameter file, although any command given explicitly on the
   command line will supersede options found in the parameter file.
   **FILTER** generates a new parameter file containing the full set of
   execution parameters upon every execution.  The name of the
   parameter file written by **FILTER** is created by combining the prefix
   base name with the *'.param'* extension.

.. _filter_api_opt_selection:

Control Options
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -filter

   This optional parameter specifies a filter file to be used in
   place of the default filter.  If only simple additions to the default filters
   are desired, please see the `-newrule` parameter.  The file format for
   this file is described in the :ref:`filter_files` chapter.  There are several
   special reserved values for this parameter.  If the `-filter` parameter
   is:

   * **Blockbuster**  This is the recommended and default filter
   * **Lead**  Corresponds to the [Oprea-2000]_ lead-like filters useful for preparing HTS databases.
   * **Drug**  Corresponds to the [Oprea-2000]_ drug-like filters useful for later stage drug development.This is provided as a backwards compatible option. Experience has shown it to be too restrictive
   * **Macrocycle**  Non-macrocycle molecules will be removed
   * **Nonmacrocycle**  Macrocycle molecules will be removed
   * **Frag**  Filter for extracting small molecules from a database that have attachment points
   * **Pains** Corresponds to the [Baell-2010]_ filter useful for removing common substructures that interfere with bioassays

   The default filter files for these reserved types can be found in the data directory included with the applications bundle.
   [Default=blockbuster]

.. option:: -fail

   This specifies an optional molecular output file where the
   molecules that fail to pass the filter will be written.  If this parameter is
   specified, then every molecule from `-in` will either be written to
   `-out` or to `-fail`. [Default=null]

.. option:: -prefix

   For an execution of the FILTER program, three general purpose
   files are written in addition to the output file specified on the command-line.
   These file are the "info", "log" and "param" files.  Normally, they all
   begin with the prefix "filter".  However, this can be overridden with the
   `-prefix` parameter.  This is particularly useful if you want to run
   multiple FILTER jobs in the same directory without overwriting files.
   [Default=filter]

.. option:: -info

   Normally, **FILTER** writes an info file during the progress of
   any execution.  At regular intervals during the execution, the info file is
   updated to reflect the most recent progress.  If you want to see
   the progress of a run, it is best to either use the `-dots` parameter or
   look at the info file.  Normally, the info file is saved as
   `filename.info` where "filename" is the prefix specified by the
   `-prefix` flag.  However, one may use the `-info` flag to specify an
   info file with a separate name. [Default=null]

.. option:: -interval

   This is the interval at which data is written to the
   `filter.info` file.  The `filter.info` file contains running totals that are
   relevant to a **FILTER** run.  Examining the `filter.info` file is the best means of
   checking on the progress of a **FILTER** execution.  If this flag is 50, then the
   filter.info file is rewritten every 50 molecules. [default = 5000]

.. option:: -log

   This flag determines where the logging information is written.  The
   logging information includes a listing of the filter used, followed by a one-line
   comment about why each molecule failed, or, if it passed, an assessment of
   the probability that the compound lies in drug-like space.

.. option:: -mmff

   This flag corresponds to the predefined force field, which is an exact reproduction of the published Merck Molecular
   Force Field (MMFF94) with additional atom types parameterized using the same algorithm
   ([Halgren-I-1996]_; [Halgren-II-1996]_; [Halgren-III-1996]_; [Halgren-IV-1996]_; [Halgren-V-1996]_).
   If true, remove any compounds that cannot be MMFF atom-typed. [default = false]

.. option:: -newrule

   This optional parameter specifies a file that contains filter
   rules to supplement the default filter or the filter specified with the
   `-filter` parameter.  This parameter can be used to extend the functional
   group list used to filter. New filter rules can also be added directly to the
   filter file specified with `-filter`.  [Default=null]

.. option:: -typecheck

   This boolean flag controls whether the valence states of
   atoms will be checked.  This check identifies molecules that are poorly
   specified, or represent nonsensical chemical states.  For example, an oxygen
   with eight hydrogens attached or a carbon with a +9 formal charge would be
   rejected. [Default=true]

.. option:: -select

   This parameter is a SMARTS string that allows a user to require
   a specific functional group or substructure be present in all molecules that
   pass the filter.  This feature is particularly useful for identification of
   reagents for library design.  Selection items can also be added directly to the
   filter file specified with `-filter`. The command-line argument only
   allows specification of the SMARTS pattern, and exactly one copy of that
   functional group is required.  If a user wants to specify a selection SMARTS
   with minimum and maximum number of occurrences other than 1, then they can use a
   SELECT statement inside the filter file. [Default=null]

.. option:: -log

   This flag determines where the logging information is written.  The
   logging information includes a listing of the filter used, followed by a one
   line comment about why each molecule failed, or if it passed, an assessment of
   the probability that the compound lies in drug-like space.

.. option:: -table

   This flag specifies a file for a tab-separated format table that
   includes all of the filter data.  These data files are ready for import into a
   spreadsheet program for easy examination.  Each column of the table includes
   one of the filter categories (such as "Molecular Weight") and each row of the
   table corresponds to a single molecule.  The table contains complete entries
   for all of the molecules in the input file regardless of whether they pass or
   fail.  NOTE: Setting this flag will cause the program to slow down.  [Default=null]
   [Aliases=**-Table**]

.. option:: -flagTableFailures

   This flag specifies that, if a table is being written,
   any values in the table that would cause a molecule to fail a filter will be
   flagged with an asterisk.  This provides a means of seeing all the filters a
   molecule might fail, as the log file typically only provides the first failure.
   [Default=false]
   [Aliases=**-tableFlag**,**-tableflag**,**-TableFlag**,**-tflag**,**-tFlag**]

.. option:: -interval

   This is the interval at which data is written to the
   `filter.info` file.  The `filter.info` file contains running totals that are
   relevant to a FILTER run.  Examining the `filter.info` file is the best means of
   checking on the progress of a FILTER execution.  If this flag is 50, then the
   filter.info file is re-written every 50 molecules. [Default=5000]

.. option:: -pkanorm

   This boolean flag determines whether compounds will be modified
   to reflect a pH=7.4 model.  Notice, this will modify the molecules permanently.
   [Default=true]
   [Aliases=**-pKanorm**,**-pKaNorm**]

.. option:: -normalize

   This flag indicates an optional SMIRKS file.  This file
   should contain the set of reactions you wish to use to normalize the connection
   table of your molecules.  Please note:  These reactions are applied before the
   filtering process and can significantly slow the filtering process.
   [Default=null]
   [Aliases=**-norm**,**-Norm**]

.. option:: -salt

   This flag specifies a molecule file that you consider to include salts.
   If any molecular entries contain multiple disconnected fragments, then any
   fragment contained in the salt file will be removed.  If no file is
   specified, or if there are multiple disconnected fragments in a molecule record
   that are not in the salt file, then the first largest remaining fragment will
   be retained and all others discarded. [Default=null]

.. option:: -sdtag

   This boolean flag indicates whether you want the molecular
   properties used for the filtering run (see `-filter`) to be attached to
   output molecules as SD tag data.  This parameter will only work for `.sdf`
   or `.oeb` formats. [Default=false]
   [Aliases=**-SDtag**,**-SDTag**]

.. option:: -dots

   Boolean flag that determines whether FILTER writes a single dot
   (.) to the terminal (stdout) for every 500 compounds that are processed.
   [Default=true]

.. option:: -unique

   This flag accepts the name of a file that contains molecules for **FILTER** to skip.  Only unique
   molecules that do not appear in this file will be sent to the output.  Molecules are checked
   for uniqueness after **FILTER** has processed them; therefore, a parameter such as -pkanorm could
   change an input structure from a duplicate to a unique molecule.

.. option:: -mmff

   If true, remove any compounds that cannot be MMFF atom-typed.
   [Default=false]


.. _filter_files:

********************
Filter Files
********************

A user can provide two parameter files if they would like
to override or augment the default parameter sets. The first is
a *filter file*. It provides acceptable limits for all of the physical
properties and functional groups in the default filter. The second is
a ``NEWRULE`` file, which allows you to
augment a filter with a set of additional rules.

There are four types of statements that can occur in a filter file:

* Physical property limits
* Rules
* New rules
* Selections

The statements should occur one per line in the filter file.

.. note::

   If the appropriate line is not in the filter file, or the value is
   false, the respective measure will not be used in filtering and
   its value will not be included in any table-based output.


Physical Property Limits
========================

There are a large number of physical property limits. They occur as
three fields on a line. For example:

::

   MIN_HETEROATOMS 2 "Minimum number of heteroatoms"

The first field is the property keyword, the second field is the value
assigned to that keyword, and the third field is a brief informational
message. There are a fixed number of physical property keywords. No
additional physical property keywords can be added by the user. The
current keywords and brief definitions of each are listed below.

.. hint::

   The values listed below are those found in the default *BlockBuster*
   filter.

.. _filter_files_basic_properties:

Basic Properties
-----------------------

Molecular Weight
^^^^^^^^^^^^^^^^^^^^^^^

Isotopic molecular weight.

::

   MIN_MOLWT 130 "Minimum molecular weight"
   MAX_MOLWT 781 "Maximum molecular weight"


Heavy Atom Count
^^^^^^^^^^^^^^^^^^^^^^^

Number of non-hydrogen atoms.

::

   MIN_NUM_HVY 9 "Minimum number of heavy atoms"
   MAX_NUM_HVY 55 "Maximum number of heavy atoms"

Carbon Count
^^^^^^^^^^^^^^^^^^^^^^^

Number of carbons.

::

   MIN_CARBONS 3 "Minimum number of carbons"
   MAX_CARBONS 41 "Maximum number of carbons"

Hetero Count
^^^^^^^^^^^^^^^^^^^^^^^

Number of non-carbon and non-hydrogen atoms.

::

   MIN_HETEROATOMS 1 "Minimum number of heteroatoms"
   MAX_HETEROATOMS 14 "Maximum number of heteroatoms"


Heteroatom to Carbon Ratio
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Hetero count/carbon count.

::

   MIN_Het_C_Ratio 0.04 "Minimum heteroatom to carbon ratio"
   MAX_Het_C_Ratio 4.0 "Maximum heteroatom to carbon ratio"

Chiral Count
^^^^^^^^^^^^^^^^^^^^^^^

Number of chiral atoms.

::

   MIN_CHIRAL_CENTERS 0 "Minimum chiral centers"
   MAX_CHIRAL_CENTERS 21 "Maximum chiral centers"

.. _filter_files_hbond_acceptor:
.. _filter_files_hydrogen_bonds:

Hydrogen Bond Acceptors
^^^^^^^^^^^^^^^^^^^^^^^

.. Depiction here would be helpful

Number of atoms which match any of the following:

* Degree 2, aromatic, nonpositive nitrogens. An example is shown below.

.. figure:: /_images/acceptorDef1.png
   :align:  center
   :width:  60%

* Electron rich (negative), valence less than 4, nonaromatic nitrogens.
  An example is shown below.

.. figure:: /_images/acceptorDef2.png
   :align:  center
   :width:  60%

* Negatively charged (does not withdraw electrons), neutral, nonaromatic oxygens.
  An example is shown below.

.. figure:: /_images/acceptorDef3.png
   :align:  center
   :width:  60%

* Degree 1, double bonded, electron rich, nonaromatic sulfur. An example
  is shown below.

.. figure:: /_images/acceptorDef4.png
   :align:  center
   :width:  60%

This definition is from the work of Mills and Dean [Mills-Dean-1996]_
and also by Jeffrey [Jeffrey-1997]_.

::

   MIN_HBOND_ACCEPTORS 0 "Minimum number of hydrogen-bond acceptors"
   MAX_HBOND_ACCEPTORS 13 "Maximum number of hydrogen-bond acceptors"

.. seealso::

   * :ref:`OEGetHBondAcceptorCount <OEMolProp_OEGetHBondAcceptorCount>` function
   * :ref:`molprops_lipinski` section

.. _filter_files_hbond_donor:

Hydrogen Bond Donors
^^^^^^^^^^^^^^^^^^^^^^^

Number of hydrogen atoms on nitrogen, oxygen, or sulfur atoms. This
definition is from the work of Mills and Dean ([Mills-Dean-1996]_)
and also the book by Jeffrey ([Jeffrey-1997]_).

::

   MIN_HBOND_DONORS 0 "Minimum number of hydrogen-bond donors"
   MAX_HBOND_DONORS 9 "Maximum number of hydrogen-bond donors"

.. seealso::

   * :ref:`OEGetHBondDonorCount <OEMolProp_OEGetHBondDonorCount>` function
   * :ref:`molprops_lipinski` section

.. _filter_files_lipinski_acceptor:

Lipinski Acceptors
^^^^^^^^^^^^^^^^^^^^^^^

Number of nitrogens or oxygens. This definition is from
the work of Lipinski [Lipinski-1997]_.

::

   MIN_LIPINSKI_ACCEPTORS 1 "Minimum number of oxygen & nitrogen atoms"
   MAX_LIPINSKI_ACCEPTORS 14 "Maximum number of oxygen & nitrogen atoms"

.. seealso::

   * :ref:`OEGetLipinskiAcceptorCount <OEMolProp_OEGetLipinskiAcceptorCount>` function
   * :ref:`molprops_lipinski` section

.. _filter_files_lipinski_donor:

Lipinski Donors
^^^^^^^^^^^^^^^^^^^^^^^

Number of nitrogens and oxygens with at least one hydrogen attached.
This definition is from the work of Lipinski [Lipinski-1997]_.

::

   MIN_LIPINSKI_DONORS 0 "Minimum number O & N atoms with hydrogens"
   MAX_LIPINSKI_DONORS 6 "Maximum number O & N atoms with hydrogens"

.. seealso::

   * :ref:`OEGetLipinskiDonorCount <OEMolProp_OEGetLipinskiDonorCount>` function
   * :ref:`molprops_lipinski` section

.. _filter_files_halide_fraction:

Halide Fraction
^^^^^^^^^^^^^^^^^^^^^^^

Percent of molecular weight from halides.

::

   MIN_HALIDE_FRACTION 0.0 "Minimum Halide Fraction"
   MAX_HALIDE_FRACTION 0.66 "Maximum Halide Fraction"

.. seealso::

   * :ref:`OEGetHalideFraction <OEMolProp_OEGetHalideFraction>` function

Formal Count
^^^^^^^^^^^^^^^^^^^^^^^

Number of atoms with a formal charge (excludes dative).

::

   MIN_COUNT_FORMAL_CRG 0 "Minimum number formal charges"
   MAX_COUNT_FORMAL_CRG 4 "Maximum number of formal charges"

Formal Sum
^^^^^^^^^^^^^^^^^^^^^^^

Total formal charge.

::

   MIN_SUM_FORMAL_CRG -2 "Minimum sum of formal charges"
   MAX_SUM_FORMAL_CRG 2 "Maximum sum of formal charges"

Connected Non-Ring
^^^^^^^^^^^^^^^^^^^^^^^

.. Need a depiction to explain this

Considers sets of contiguous (bonded) non-ring atoms.

::

   MIN_CON_NON_RING 0 "Minimum number of connected non-ring atoms"
   MAX_CON_NON_RING 19 "Maximum number of connected non-ring atoms"

.. _filter_files_unbranched_chains:

Unbranched Chains
^^^^^^^^^^^^^^^^^^^^^^^

The size of the longest chain of either heavy atoms or of all carbons.
An unbranched atom is an atom with at most two connections to other heavy
atoms and is not in a ring.  A set of unbranched atoms which are
connected together form a chain.  A molecule may contain multiple chains
which are isolated from each other by non-chain atoms (e.g., ring or
branched atoms).  The longest chain of heavy atoms and the longest
chain of carbons are identified, and the MIN and MAX parameter filters
are applied.

::

   MIN_UNBRANCHED 1 "Minimum number of connected unbranched non-ring atoms"
   MAX_UNBRANCHED 13 "Maximum number of connected unbranched non-ring atoms"
   MIN_UNBRANCHED_C 0 "Minimum number of connected unbranched non-ring carbon"
   MAX_UNBRANCHED_C 6 "Maximum number of connected unbranched non-ring carbon"

.. seealso::

   * :ref:`OEGetLongestUnbranchedHeavyAtomsChain <OEMolProp_OEGetLongestUnbranchedHeavyAtomsChain>` function
   * :ref:`OEGetLongestUnbranchedCarbonsChain <OEMolProp_OEGetLongestUnbranchedCarbonsChain>` function

Total Functional Group Count
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Total number of functional groups. Does not count any ring systems as
functional groups. Degree 1 heteroatoms, particularly those with
double bonds or dative bonds are considered part of ring systems and
do not count as functional groups.

::

   MIN_FCNGRP 0 "Minimum number of functional groups"
   MAX_FCNGRP 7 "Maximum number of functional groups"

.. (not just those recognized by filter patterns)

.. note::

   This is different than the functional group rules.

Ring Systems
^^^^^^^^^^^^^^^^^^^^^^^

.. Depiction here would be helpful

Number of ring systems (contiguous systems of ring atoms and bonds).

::

   MIN_RING_SYS 0 "Minimum number of ring systems"
   MAX_RING_SYS 5 "Maximum number of ring systems"

Ring Size
^^^^^^^^^^^^^^^^^^^^^^^

Maximum size of any single ring system.

::

   MIN_RING_SIZE 0 "Minimum atoms in any ring system"
   MAX_RING_SIZE 20 "Maximum atoms in any ring system"

.. _filter_files_rotor_count:

Rotor Count
^^^^^^^^^^^^^^^^^^^^^^^

Number of rotatable bonds. Allows optional adjustment for aliphatic
rings following the method of Oprea [Oprea-2000]_.

::

   MIN_ROT_BONDS 0 "Minimum number of rotatable bonds"
   MAX_ROT_BONDS 16 "Maximum number of rotatable bonds"
   ADJUST_ROT_FOR_RING true "BOOLEAN for whether to estimate degrees of freedom in rings"

.. seealso::

   * :ref:`OEGetRotatableBondCount <OEMolProp_OEGetRotatableBondCount>` function

Rigid Count
^^^^^^^^^^^^^^^^^^^^^^^

Number of rigid bonds (non-rotatable bonds).

::

   MIN_RIGID_BONDS 4 "Minimum number of rigid bonds"
   MAX_RIGID_BONDS 55 "Maximum number of rigid bonds"

.. _filter_files_unspecified_atom_stereos:

Unspecified Atom Stereo
^^^^^^^^^^^^^^^^^^^^^^^

Number of unspecified atom stereos

::

   MIN_UNSPECIFIED_ATOM_STEREOS 0 "Minimum number of unspecified atom stereos"
   MAX_UNSPECIFIED_ATOM_STEREOS 2 "Maximum number of unspecified atom stereos"

.. note::

   ``MIN_UNSPECIFIED_ATOM_STEREOS`` and ``MAX_UNSPECIFIED_ATOM_STEREOS`` are not 
   used for filtering in the default filters.

.. seealso::

   * :ref:`OEGetNumUnspecifiedAtomStereos <OEMolProp_OEGetNumUnspecifiedAtomStereos>` function
   * :term:`stereo atom`
   * :ref:`chapter_stereochemistry` chapter
   * :oe:meth:`OEChem::OEAtomBase::HasStereoSpecified`

.. _filter_files_unspecified_bond_stereos:

Unspecified Bond Stereo
^^^^^^^^^^^^^^^^^^^^^^^

Number of unspecified bond stereos

::

   MIN_UNSPECIFIED_BOND_STEREOS 0 "Minimum number of unspecified bond stereos"
   MAX_UNSPECIFIED_BOND_STEREOS 2 "Maximum number of unspecified bond stereos"

.. note::

   ``MIN_UNSPECIFIED_BOND_STEREOS`` and ``MAX_UNSPECIFIED_BOND_STEREOS`` are not
   used for filtering in the default filters.

.. seealso::

   * :ref:`OEGetNumUnspecifiedBondStereos <OEMolProp_OEGetNumUnspecifiedBondStereos>` function
   * :term:`stereo bond`
   * :ref:`chapter_stereochemistry` chapter
   * :oe:meth:`OEChem::OEBondBase::HasStereoSpecified`

.. _filter_files_typecheck:

Atom Type Checks
^^^^^^^^^^^^^^^^^^^^^^^

Checks the validity of atom charges, valences or MMFF atom types for
the entire molecule.

::

   TYPECHECK     false "Screen for unusual valences or charges"
   MMFFTYPECHECK false "Screen for atoms with unknown MMFF atom types"

.. seealso::

   * :ref:`filter_process_type_checking`
   * :ref:`SetTypeCheck <OEMolProp_OEFilter_SetTypeCheck>`
   * :ref:`filter_process_mmff_checking`
   * :ref:`SetMMFFTypeCheck <OEMolProp_OEFilter_SetMMFFTypeCheck>`

.. _filter_files_xlogp:

LogP
-----------------------

The logP calculation is a derivative of the published XLOGP algorithm
[Wang-R-1997]_ but is reparameterized without the dependence on 3D
coordinates or the SYBYL/Mol2 aromaticity model.

XLogP
^^^^^^^^^^^^^^^^^^^^^^^

Calculated LogP.

::

   MIN_XLOGP -3.0 "Minimum XLogP"
   MAX_XLOGP 6.85 "Maximum XLogP"

.. _filter_files_solubility:

Solubility
-----------------------

The solubility predictions are based on the atom types from the
XLOGP algorithm (see [Wang-R-1997]_) and on reparameterized atom types based on
available solubility data. Rather than a quantitative cutoff, the
solubility uses six allowable categories:

1. Insoluble
2. Poorly
3. Moderately
4. Soluble
5. Very
6. Highly

These categories are keywords used in the following filter files.

Solubility
^^^^^^^^^^^^^^^^^^^^^^^

Calculated solubility class.

::

   MIN_SOLUBILITY insoluble "Minimum solubility"

.. _filter_files_pharmacokinetic_predictors:

Pharmacokinetic Predictors
--------------------------

Several secondary filters that are built upon published combinations
of simpler properties are available.

.. note::

   All of these properties are used for filtering in the default
   filters.

.. _filter_files_anionic_carbon:

Anionic Carbon Count
--------------------------

Number of anionic carbons

::

   MIN_ANION_C 0 "Minimum number of anionic carbons"
   MAX_ANION_C 2 "Maximum number of anionic carbons"

.. note::

   ``MIN_ANION_C`` and ``MAX_ANION_C`` are not used for filtering in the default
   filters.

.. seealso::

   * :ref:`OEGetAnionicCarbonCount <OEMolProp_OEGetAnionicCarbonCount>` function

.. _filter_files_lipinski:

Lipinski Violations
^^^^^^^^^^^^^^^^^^^^^^^

Number of allowable Lipinski violations. A single Lipinski violation
is considered acceptable. The published work allows
compounds to pass with a single violation but not multiple violations [Lipinski-1997]_.

::

   MAX_LIPINSKI 3 "Maximum number of Lipinski violations"

.. seealso::

   The :ref:`Lipinski theory<molprops_lipinski>` section in the Molecular Properties
   and Predictors chapter.

.. _filter_files_PSA:

PSA
^^^^^^^^^^^^^^^^^^^^^^^

Peter Ertl's topological polar surface area (phosphorus
and sulfur areas are optional) [Ertl-2000]_.

::

   PSA_USE_SandP false "Count S and P as polar atoms"
   MIN_2D_PSA 0.0 "Minimum 2-Dimensional (SMILES) Polar Surface Area"
   MAX_2D_PSA 205.0 "Maximum 2-Dimensional (SMILES) Polar Surface Area"

.. seealso::

   The :ref:`PSA theory<molprops_polar_surface_area>` section in the Molecular
   Properties and Predictors chapter.


GSK/Veber
^^^^^^^^^^^^^^^^^^^^^^^

Veber's measure of bioavailability (PSA > 140 or Rotatable bonds >10)
[Veber-2002]_.

::

   GSK_VEBER false "PSA>140 or >10 rot bonds"


Abbott/Martin
^^^^^^^^^^^^^^^^^^^^^^^

Yvonne Martin's Abbott Bioavailability Score [Martin-2005]_. This is reported as a
probability that ``F>10%`` in rats.

::

   MIN_ABS 0.11 "Minimum probability F>10% in rats"

Pharmacopia/Egan
^^^^^^^^^^^^^^^^^^^^^^^

"Egan egg" measure of bioavailability (LogP >5.88 or PSA >
131.6) [Egan-2000]_.

::

   PHARMACOPIA false "LogP > 5.88 or PSA > 131.6"

.. _filter_files_aggregators:

Aggregators
-----------------------

Aggregators are small molecules that can interfere with assay results
by sequestering proteins in an aggregation of small molecules in
solution. They appear to have activity in many assays, but in fact are
usually not specific inhibitors of the protein in question. This includes
two measures of whether a molecule is one of the aggregators defined
by Shoichet et al. ([McGovern-2003]_; [Seidler-2003]_). The first
measure, ``AGGREGATORS``, states whether the molecule is an exact match to
one of the approximately 400 published aggregators. The second
measure, ``PRED_AGG``, states whether the molecule is included in Shoichet's QSAR
model for predicting aggregators.

Aggregators
^^^^^^^^^^^^^^^^^^^^^^^

Whether a compound is known or predicted to aggregate in
concentrations common in virtual screening.

::

   AGGREGATORS true "Eliminate known aggregators"
   PRED_AGG false "Eliminate predicted aggregators"

.. _filter_files_elemental_filters:

Elemental Filters
----------------------

The elemental filters are applied in this order:

1. Test for the existence of any of the metals in the ``ELIMINATE_METALS`` filter in the molecule.
2. Remove salts by stripping away all the disconnected components except for the largest.
3. Test to make sure only atoms specified in ``ALLOWED_ELEMENTS`` filter are in the molecule.

.. seealso::

   * :ref:`filter_process_metal_removal`
   * :ref:`filter_process_salt_removal`

The format of the two elemental filter fields is the keyword followed
by a comma-delimited list of atomic symbols.

..  _ELIMINATE_METALS:


Eliminate Metals
^^^^^^^^^^^^^^^^^^^^^^^

Any molecule with the atoms indicated in ``ELIMINATE_METALS`` fail to
pass the filter.

::

   ELIMINATE_METALS Sc,Ti,V,Cr,Mn,Fe,Co,Ni,Cu,Zn,Y,Zr,Nb,Mo,Tc,Ru,Rh,Pd,Ag,Cd

..  _ALLOWED_ELEMENTS:

Allowed Elements
^^^^^^^^^^^^^^^^^^^^^^^

Molecules with atoms other than those specified by
``ALLOWED_ELEMENTS`` fail to pass the filter.

::

   ALLOWED_ELEMENTS H,C,N,O,F,P,S,Cl,Br,I

Aromatic Ring Count
^^^^^^^^^^^^^^^^^^^^

Uses the result of the function OEGetAromaticRingCount (see toolkit docs) to filter molecules
based on their number of aromatic rings.

::

   MIN_AROMATIC_RING_COUNT 1 "Minimum aromatic ring count"
   MAX_AROMATIC_RING_COUNT 6 "Maximum aromatic ring count"

CSP3 Carbon Fraction
^^^^^^^^^^^^^^^^^^^^

Uses the result of the :ref:`OEGetFractionCsp3 <OEMolProp_OEGetFractionCsp3>` function from MolProp TK to filter molecules based
on their CSP3 carbon fraction.

::

   MIN_FRACTION_CSP3 0.1 "Minimum fraction CSP3 carbons"
   MAX_FRACTION_CSP3 0.5 "Maximum fraction CSP3 carbons"


.. _functional_group_rules:

Functional Group Rules
===============================================================================


Rules statements set the limits for the maximum number of the
specified type of functional group that may be allowed in the
molecule.

The first field of a rule statement is the word RULE in all capital
letters. The second field is a number indicating the maximum number of
the group allowed in a molecule. The third field is the functional
group keyword. Functional group keywords are case sensitive.

::

   RULE 0 acid_halide

The following is a list of functional groups which the filter recognizes
by default. Three example matches are provided with the atoms that
correspond to each other highlighted.

.. note::

   Due to the highly complex nature of the patterns, in particular
   recursive SMARTS, it is not possible to fully highlight every atom
   that was included as part of the match.


acetal
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/acetal-001.png
     - .. image:: ../../../common/images/molprop/acetal-002.png
     - .. image:: ../../../common/images/molprop/acetal-003.png

acid
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/acid-001.png
     - .. image:: ../../../common/images/molprop/acid-002.png
     - .. image:: ../../../common/images/molprop/acid-003.png

acid_chloride
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/acid_chloride-001.png
     - .. image:: ../../../common/images/molprop/acid_chloride-002.png
     - .. image:: ../../../common/images/molprop/acid_chloride-003.png

acid_halide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/acid_halide-001.png
     - .. image:: ../../../common/images/molprop/acid_halide-002.png
     - .. image:: ../../../common/images/molprop/acid_halide-003.png

acyclic_NCN
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/acyclic_NCN-001.png
     - .. image:: ../../../common/images/molprop/acyclic_NCN-002.png
     - .. image:: ../../../common/images/molprop/acyclic_NCN-003.png

acyclic_NS
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/acyclic_NS-001.png
     - .. image:: ../../../common/images/molprop/acyclic_NS-002.png
     - .. image:: ../../../common/images/molprop/acyclic_NS-003.png

acyl_cyanides
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/acyl_cyanides-001.png
     - .. image:: ../../../common/images/molprop/acyl_cyanides-002.png
     - .. image:: ../../../common/images/molprop/acyl_cyanides-003.png

acylhydrazide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0


   * - .. image:: ../../../common/images/molprop/acylhydrazide-001.png
     - .. image:: ../../../common/images/molprop/acylhydrazide-002.png
     - .. image:: ../../../common/images/molprop/acylhydrazide-003.png

alcohol
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/alcohol-001.png
     - .. image:: ../../../common/images/molprop/alcohol-002.png
     - .. image:: ../../../common/images/molprop/alcohol-003.png

aldehyde
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/aldehyde-001.png
     - .. image:: ../../../common/images/molprop/aldehyde-002.png
     - .. image:: ../../../common/images/molprop/aldehyde-003.png

alkene
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/alkene-001.png
     - .. image:: ../../../common/images/molprop/alkene-002.png
     - .. image:: ../../../common/images/molprop/alkene-003.png

alkyl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/alkyl-001.png
     - .. image:: ../../../common/images/molprop/alkyl-002.png
     - .. image:: ../../../common/images/molprop/alkyl-003.png

alkyl_halide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/alkyl_halide-001.png
     - .. image:: ../../../common/images/molprop/alkyl_halide-002.png
     - .. image:: ../../../common/images/molprop/alkyl_halide-003.png

alkyl_phosphate
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/alkyl_phosphate-001.png
     - .. image:: ../../../common/images/molprop/alkyl_phosphate-002.png
     - .. image:: ../../../common/images/molprop/alkyl_phosphate-003.png

alkylaniline
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/alkylaniline-001.png
     - .. image:: ../../../common/images/molprop/alkylaniline-002.png
     - .. image:: ../../../common/images/molprop/alkylaniline-003.png

alkylating_agent
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/alkylating_agent-001.png
     - .. image:: ../../../common/images/molprop/alkylating_agent-002.png
     - .. image:: ../../../common/images/molprop/alkylating_agent-003.png

alkyne
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/alkyne-001.png
     - .. image:: ../../../common/images/molprop/alkyne-002.png
     - .. image:: ../../../common/images/molprop/alkyne-003.png

alphahalo_amine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/alphahalo_amine-001.png
     - .. image:: ../../../common/images/molprop/alphahalo_amine-002.png
     - .. image:: ../../../common/images/molprop/alphahalo_amine-003.png

alphahalo_ketone
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/alphahalo_ketone-001.png
     - .. image:: ../../../common/images/molprop/alphahalo_ketone-002.png
     - .. image:: ../../../common/images/molprop/alphahalo_ketone-003.png

amide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/amide-001.png
     - .. image:: ../../../common/images/molprop/amide-002.png
     - .. image:: ../../../common/images/molprop/amide-003.png

aminal
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/aminal-001.png
     - .. image:: ../../../common/images/molprop/aminal-002.png
     - .. image:: ../../../common/images/molprop/aminal-003.png

amine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/amine-001.png
     - .. image:: ../../../common/images/molprop/amine-002.png
     - .. image:: ../../../common/images/molprop/amine-003.png

amino_acid
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/amino_acid-001.png
     - .. image:: ../../../common/images/molprop/amino_acid-002.png
     - .. image:: ../../../common/images/molprop/amino_acid-003.png

anhydride
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/anhydride-001.png
     - .. image:: ../../../common/images/molprop/anhydride-002.png
     - .. image:: ../../../common/images/molprop/anhydride-003.png

aniline
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/aniline-001.png
     - .. image:: ../../../common/images/molprop/aniline-002.png
     - .. image:: ../../../common/images/molprop/aniline-003.png

aniline_unsubstituted
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/aniline_unsubstituted-001.png
     - .. image:: ../../../common/images/molprop/aniline_unsubstituted-002.png
     - .. image:: ../../../common/images/molprop/aniline_unsubstituted-003.png

arene
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/arene-001.png
     - .. image:: ../../../common/images/molprop/arene-002.png
     - .. image:: ../../../common/images/molprop/arene-003.png

arenesulfonyl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/arenesulfonyl-001.png
     - .. image:: ../../../common/images/molprop/arenesulfonyl-002.png
     - .. image:: ../../../common/images/molprop/arenesulfonyl-003.png

aryl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/aryl-001.png
     - .. image:: ../../../common/images/molprop/aryl-002.png
     - .. image:: ../../../common/images/molprop/aryl-003.png

aryl_halide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/aryl_halide-001.png
     - .. image:: ../../../common/images/molprop/aryl_halide-002.png
     - .. image:: ../../../common/images/molprop/aryl_halide-003.png

aryl_mono_BrI
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/aryl_mono_BrI-001.png
     - .. image:: ../../../common/images/molprop/aryl_mono_BrI-002.png
     - .. image:: ../../../common/images/molprop/aryl_mono_BrI-003.png

azide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/azide-001.png
     - .. image:: ../../../common/images/molprop/azide-002.png
     - .. image:: ../../../common/images/molprop/azide-003.png

aziridine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/aziridine-001.png
     - .. image:: ../../../common/images/molprop/aziridine-002.png
     - .. image:: ../../../common/images/molprop/aziridine-003.png

azo
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/azo-001.png
     - .. image:: ../../../common/images/molprop/azo-002.png
     - .. image:: ../../../common/images/molprop/azo-003.png

azocyanamides
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/azocyanamides-001.png
     - .. image:: ../../../common/images/molprop/azocyanamides-002.png
     - .. image:: ../../../common/images/molprop/azocyanamides-003.png

base
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/base-001.png
     - .. image:: ../../../common/images/molprop/base-002.png
     - .. image:: ../../../common/images/molprop/base-003.png

benzyl_ether
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/benzyl_ether-001.png
     - .. image:: ../../../common/images/molprop/benzyl_ether-002.png
     - .. image:: ../../../common/images/molprop/benzyl_ether-003.png

benzyloxycarbonyl_CBZ
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/benzyloxycarbonyl_CBZ-001.png
     - .. image:: ../../../common/images/molprop/benzyloxycarbonyl_CBZ-002.png
     - .. image:: ../../../common/images/molprop/benzyloxycarbonyl_CBZ-003.png

beta_azo_carbonyl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/beta_azo_carbonyl-001.png
     - .. image:: ../../../common/images/molprop/beta_azo_carbonyl-002.png
     - .. image:: ../../../common/images/molprop/beta_azo_carbonyl-003.png

beta_carbonyl_quat_nitrogen
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/beta_carbonyl_quat_nitrogen-001.png
     - .. image:: ../../../common/images/molprop/beta_carbonyl_quat_nitrogen-002.png
     - .. image:: ../../../common/images/molprop/beta_carbonyl_quat_nitrogen-003.png

beta_halo_carbonyl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/beta_halo_carbonyl-001.png
     - .. image:: ../../../common/images/molprop/beta_halo_carbonyl-002.png
     - .. image:: ../../../common/images/molprop/beta_halo_carbonyl-003.png


carbamate
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/carbamate-001.png
     - .. image:: ../../../common/images/molprop/carbamate-002.png
     - .. image:: ../../../common/images/molprop/carbamate-003.png

carbamic_acid
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/carbamic_acid-001.png
     - .. image:: ../../../common/images/molprop/carbamic_acid-002.png
     - .. image:: ../../../common/images/molprop/carbamic_acid-003.png

carbodiimide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/carbodiimide-001.png
     - .. image:: ../../../common/images/molprop/carbodiimide-002.png
     - .. image:: ../../../common/images/molprop/carbodiimide-003.png

carbonate
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/carbonate-001.png
     - .. image:: ../../../common/images/molprop/carbonate-002.png
     - .. image:: ../../../common/images/molprop/carbonate-003.png

carbonyl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/carbonyl-001.png
     - .. image:: ../../../common/images/molprop/carbonyl-002.png
     - .. image:: ../../../common/images/molprop/carbonyl-003.png

carboxylic_acid
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/carboxylic_acid-001.png
     - .. image:: ../../../common/images/molprop/carboxylic_acid-002.png
     - .. image:: ../../../common/images/molprop/carboxylic_acid-003.png

cation_C_Cl_I_P_or_S
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/cation_C_Cl_I_P_or_S-001.png
     - .. image:: ../../../common/images/molprop/cation_C_Cl_I_P_or_S-002.png
     - .. image:: ../../../common/images/molprop/cation_C_Cl_I_P_or_S-003.png

charge
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/charge-001.png
     - .. image:: ../../../common/images/molprop/charge-002.png
     - .. image:: ../../../common/images/molprop/charge-003.png

cyanohydrins
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/cyanohydrins-001.png
     - .. image:: ../../../common/images/molprop/cyanohydrins-002.png
     - .. image:: ../../../common/images/molprop/cyanohydrins-003.png

cycloheximide_derivatives
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/cycloheximide_derivatives-001.png
     - .. image:: ../../../common/images/molprop/cycloheximide_derivatives-002.png
     - .. image:: ../../../common/images/molprop/cycloheximide_derivatives-003.png

cyclopropyl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/cyclopropyl-001.png
     - .. image:: ../../../common/images/molprop/cyclopropyl-002.png
     - .. image:: ../../../common/images/molprop/cyclopropyl-003.png

cytochalasin_derivatives
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/cytochalasin_derivatives-001.png
     - .. image:: ../../../common/images/molprop/cytochalasin_derivatives-002.png
     - .. image:: ../../../common/images/molprop/cytochalasin_derivatives-003.png

di_peptide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/di_peptide-001.png
     - .. image:: ../../../common/images/molprop/di_peptide-002.png
     - .. image:: ../../../common/images/molprop/di_peptide-003.png

dioxane_6MR
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/dioxane_6MR-001.png
     - .. image:: ../../../common/images/molprop/dioxane_6MR-002.png
     - .. image:: ../../../common/images/molprop/dioxane_6MR-003.png

dioxolane_5MR
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/dioxolane_5MR-001.png
     - .. image:: ../../../common/images/molprop/dioxolane_5MR-002.png
     - .. image:: ../../../common/images/molprop/dioxolane_5MR-003.png

disulfide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/disulfide-001.png
     - .. image:: ../../../common/images/molprop/disulfide-002.png
     - .. image:: ../../../common/images/molprop/disulfide-003.png

dithioacetal
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/dithioacetal-001.png
     - .. image:: ../../../common/images/molprop/dithioacetal-002.png
     - .. image:: ../../../common/images/molprop/dithioacetal-003.png

dye
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/dye-001.png
     - .. image:: ../../../common/images/molprop/dye-002.png
     - .. image:: ../../../common/images/molprop/dye-003.png

enamine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/enamine-001.png
     - .. image:: ../../../common/images/molprop/enamine-002.png
     - .. image:: ../../../common/images/molprop/enamine-003.png

enol_ether
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/enol_ether-001.png
     - .. image:: ../../../common/images/molprop/enol_ether-002.png
     - .. image:: ../../../common/images/molprop/enol_ether-003.png

epoxide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/epoxide-001.png
     - .. image:: ../../../common/images/molprop/epoxide-002.png
     - .. image:: ../../../common/images/molprop/epoxide-003.png

ester
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/ester-001.png
     - .. image:: ../../../common/images/molprop/ester-002.png
     - .. image:: ../../../common/images/molprop/ester-003.png

ether
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/ether-001.png
     - .. image:: ../../../common/images/molprop/ether-002.png
     - .. image:: ../../../common/images/molprop/ether-003.png

fluorenylmethoxycarbonyl_Fmoc
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/fluorenylmethoxycarbonyl_Fmoc-001.png
     -
     -

guanidine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/guanidine-001.png
     - .. image:: ../../../common/images/molprop/guanidine-002.png
     - .. image:: ../../../common/images/molprop/guanidine-003.png

halide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/halide-001.png
     - .. image:: ../../../common/images/molprop/halide-002.png
     - .. image:: ../../../common/images/molprop/halide-003.png

halo_alkene
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/halo_alkene-001.png
     - .. image:: ../../../common/images/molprop/halo_alkene-002.png
     - .. image:: ../../../common/images/molprop/halo_alkene-003.png


.. _functional_group_rules_halo_amine:

halo_amine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/halo_amine-001.png
     - .. image:: ../../../common/images/molprop/halo_amine-002.png
     - .. image:: ../../../common/images/molprop/halo_amine-003.png

halopyrimidine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/halopyrimidine-001.png
     - .. image:: ../../../common/images/molprop/halopyrimidine-002.png
     - .. image:: ../../../common/images/molprop/halopyrimidine-003.png

hemiacetal
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/hemiacetal-001.png
     - .. image:: ../../../common/images/molprop/hemiacetal-002.png
     - .. image:: ../../../common/images/molprop/hemiacetal-003.png

hemiaminal
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/hemiaminal-001.png
     - .. image:: ../../../common/images/molprop/hemiaminal-002.png
     - .. image:: ../../../common/images/molprop/hemiaminal-003.png

hemiketal
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/hemiketal-001.png
     - .. image:: ../../../common/images/molprop/hemiketal-002.png
     - .. image:: ../../../common/images/molprop/hemiketal-003.png

hetatm
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/hetatm-001.png
     - .. image:: ../../../common/images/molprop/hetatm-002.png
     - .. image:: ../../../common/images/molprop/hetatm-003.png

hetero_hetero
-------------------------------------------------------------------------------

.. list-table: IGNORING DUE TO NO EXAMPLE FOUND IN EMOLECULES
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/hetero_hetero-001.png
     - .. image:: ../../../common/images/molprop/hetero_hetero-002.png
     - .. image:: ../../../common/images/molprop/hetero_hetero-003.png

HOBT_esters
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/HOBT_esters-001.png
     - .. image:: ../../../common/images/molprop/HOBT_esters-002.png
     -

hydrazine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/hydrazine-001.png
     - .. image:: ../../../common/images/molprop/hydrazine-002.png
     - .. image:: ../../../common/images/molprop/hydrazine-003.png

hydrazone
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/hydrazone-001.png
     - .. image:: ../../../common/images/molprop/hydrazone-002.png
     - .. image:: ../../../common/images/molprop/hydrazone-003.png

hydroxamic_acid
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/hydroxamic_acid-001.png
     - .. image:: ../../../common/images/molprop/hydroxamic_acid-002.png
     - .. image:: ../../../common/images/molprop/hydroxamic_acid-003.png

hydroxyl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/hydroxyl-001.png
     - .. image:: ../../../common/images/molprop/hydroxyl-002.png
     - .. image:: ../../../common/images/molprop/hydroxyl-003.png

hydroxylamine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/hydroxylamine-001.png
     - .. image:: ../../../common/images/molprop/hydroxylamine-002.png
     - .. image:: ../../../common/images/molprop/hydroxylamine-003.png

imidoyl_chlorides
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/imidoyl_chlorides-001.png
     - .. image:: ../../../common/images/molprop/imidoyl_chlorides-002.png
     - .. image:: ../../../common/images/molprop/imidoyl_chlorides-003.png

imine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/imine-001.png
     - .. image:: ../../../common/images/molprop/imine-002.png
     - .. image:: ../../../common/images/molprop/imine-003.png

imino
------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/imino-001.png
     - .. image:: ../../../common/images/molprop/imino-002.png
     - .. image:: ../../../common/images/molprop/imino-003.png

iodine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/iodine-001.png
     - .. image:: ../../../common/images/molprop/iodine-002.png
     - .. image:: ../../../common/images/molprop/iodine-003.png

iodoso
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/iodoso-001.png
     - .. image:: ../../../common/images/molprop/iodoso-002.png
     - .. image:: ../../../common/images/molprop/iodoso-003.png

iodoxy
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/iodoxy-001.png
     - .. image:: ../../../common/images/molprop/iodoxy-002.png
     - .. image:: ../../../common/images/molprop/iodoxy-003.png

isocyanate
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/isocyanate-001.png
     - .. image:: ../../../common/images/molprop/isocyanate-002.png
     - .. image:: ../../../common/images/molprop/isocyanate-003.png

isonitrile
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/isonitrile-001.png
     - .. image:: ../../../common/images/molprop/isonitrile-002.png
     - .. image:: ../../../common/images/molprop/isonitrile-003.png

isothiocyanate
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/isothiocyanate-001.png
     - .. image:: ../../../common/images/molprop/isothiocyanate-002.png
     - .. image:: ../../../common/images/molprop/isothiocyanate-003.png

ketal
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/ketal-001.png
     - .. image:: ../../../common/images/molprop/ketal-002.png
     - .. image:: ../../../common/images/molprop/ketal-003.png

ketone
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/ketone-001.png
     - .. image:: ../../../common/images/molprop/ketone-002.png
     - .. image:: ../../../common/images/molprop/ketone-003.png

lactam
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/lactam-001.png
     - .. image:: ../../../common/images/molprop/lactam-002.png
     - .. image:: ../../../common/images/molprop/lactam-003.png

lactone
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/lactone-001.png
     - .. image:: ../../../common/images/molprop/lactone-002.png
     - .. image:: ../../../common/images/molprop/lactone-003.png

lawesson_s_reagent
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/lawesson_s_reagent-001.png
     - .. image:: ../../../common/images/molprop/lawesson_s_reagent-002.png
     - .. image:: ../../../common/images/molprop/lawesson_s_reagent-003.png

long_aliphatic_chain
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/long_aliphatic_chain-001.png
     - .. image:: ../../../common/images/molprop/long_aliphatic_chain-002.png
     - .. image:: ../../../common/images/molprop/long_aliphatic_chain-003.png

malonic
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/malonic-001.png
     - .. image:: ../../../common/images/molprop/malonic-002.png
     - .. image:: ../../../common/images/molprop/malonic-003.png

mercapto
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/mercapto-001.png
     - .. image:: ../../../common/images/molprop/mercapto-002.png
     - .. image:: ../../../common/images/molprop/mercapto-003.png

methoxyethoxymethyl_MEM
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/methoxyethoxymethyl_MEM-001.png
     - .. image:: ../../../common/images/molprop/methoxyethoxymethyl_MEM-002.png
     - .. image:: ../../../common/images/molprop/methoxyethoxymethyl_MEM-003.png

methyl_ketone
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/methyl_ketone-001.png
     - .. image:: ../../../common/images/molprop/methyl_ketone-002.png
     - .. image:: ../../../common/images/molprop/methyl_ketone-003.png

michael_acceptor
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/michael_acceptor-001.png
     - .. image:: ../../../common/images/molprop/michael_acceptor-002.png
     - .. image:: ../../../common/images/molprop/michael_acceptor-003.png

monensin_derivatives
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/monensin_derivatives-001.png
     -
     -

mono_alkene
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/mono_alkene-001.png
     - .. image:: ../../../common/images/molprop/mono_alkene-002.png
     - .. image:: ../../../common/images/molprop/mono_alkene-003.png

mono_alkyne
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/mono_alkyne-001.png
     - .. image:: ../../../common/images/molprop/mono_alkyne-002.png
     - .. image:: ../../../common/images/molprop/mono_alkyne-003.png

nitrile
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/nitrile-001.png
     - .. image:: ../../../common/images/molprop/nitrile-002.png
     - .. image:: ../../../common/images/molprop/nitrile-003.png

nitro
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/nitro-001.png
     - .. image:: ../../../common/images/molprop/nitro-002.png
     - .. image:: ../../../common/images/molprop/nitro-003.png

nitroso
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/nitroso-001.png
     - .. image:: ../../../common/images/molprop/nitroso-002.png
     - .. image:: ../../../common/images/molprop/nitroso-003.png


N_methoyl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/N_methoyl-001.png
     - .. image:: ../../../common/images/molprop/N_methoyl-002.png
     - .. image:: ../../../common/images/molprop/N_methoyl-003.png

nonacylhydrazone
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/nonacylhydrazone-001.png
     - .. image:: ../../../common/images/molprop/nonacylhydrazone-002.png
     - .. image:: ../../../common/images/molprop/nonacylhydrazone-003.png

noxide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/noxide-001.png
     - .. image:: ../../../common/images/molprop/noxide-002.png
     - .. image:: ../../../common/images/molprop/noxide-003.png

N_P_S_Halides
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/N_P_S_Halides-001.png
     - .. image:: ../../../common/images/molprop/N_P_S_Halides-002.png
     - .. image:: ../../../common/images/molprop/N_P_S_Halides-003.png

NS_beta_halothyl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/NS_beta_halothyl-001.png
     - .. image:: ../../../common/images/molprop/NS_beta_halothyl-002.png
     - .. image:: ../../../common/images/molprop/NS_beta_halothyl-003.png

nucleophile
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/nucleophile-001.png
     - .. image:: ../../../common/images/molprop/nucleophile-002.png
     - .. image:: ../../../common/images/molprop/nucleophile-003.png

organometallic
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/organometallic-001.png
     - .. image:: ../../../common/images/molprop/organometallic-002.png
     - .. image:: ../../../common/images/molprop/organometallic-003.png

oxalyl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/oxalyl-001.png
     - .. image:: ../../../common/images/molprop/oxalyl-002.png
     - .. image:: ../../../common/images/molprop/oxalyl-003.png

oxaziridine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/oxaziridine-001.png
     - .. image:: ../../../common/images/molprop/oxaziridine-002.png
     - .. image:: ../../../common/images/molprop/oxaziridine-003.png

oxime
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/oxime-001.png
     - .. image:: ../../../common/images/molprop/oxime-002.png
     - .. image:: ../../../common/images/molprop/oxime-003.png

oxygen_cation
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/oxygen_cation-001.png
     - .. image:: ../../../common/images/molprop/oxygen_cation-002.png
     - .. image:: ../../../common/images/molprop/oxygen_cation-003.png

paranitrophenyl_esters
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/paranitrophenyl_esters-001.png
     - .. image:: ../../../common/images/molprop/paranitrophenyl_esters-002.png
     - .. image:: ../../../common/images/molprop/paranitrophenyl_esters-003.png

pentafluorophenyl_esters
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/pentafluorophenyl_esters-001.png
     - .. image:: ../../../common/images/molprop/pentafluorophenyl_esters-002.png
     - .. image:: ../../../common/images/molprop/pentafluorophenyl_esters-003.png

perhalo_ketone
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/perhalo_ketone-001.png
     - .. image:: ../../../common/images/molprop/perhalo_ketone-002.png
     - .. image:: ../../../common/images/molprop/perhalo_ketone-003.png

peroxide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/peroxide-001.png
     - .. image:: ../../../common/images/molprop/peroxide-002.png
     - .. image:: ../../../common/images/molprop/peroxide-003.png

phenol
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/phenol-001.png
     - .. image:: ../../../common/images/molprop/phenol-002.png
     - .. image:: ../../../common/images/molprop/phenol-003.png

phosphanes
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/phosphanes-001.png
     - .. image:: ../../../common/images/molprop/phosphanes-002.png
     - .. image:: ../../../common/images/molprop/phosphanes-003.png

phosphinic_acid
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/phosphinic_acid-001.png
     - .. image:: ../../../common/images/molprop/phosphinic_acid-002.png
     - .. image:: ../../../common/images/molprop/phosphinic_acid-003.png

phosphonamide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/phosphonamide-001.png
     - .. image:: ../../../common/images/molprop/phosphonamide-002.png
     - .. image:: ../../../common/images/molprop/phosphonamide-003.png

phosphonic_acid
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/phosphonic_acid-001.png
     - .. image:: ../../../common/images/molprop/phosphonic_acid-002.png
     - .. image:: ../../../common/images/molprop/phosphonic_acid-003.png

phosphonic_ester
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/phosphonic_ester-001.png
     - .. image:: ../../../common/images/molprop/phosphonic_ester-002.png
     - .. image:: ../../../common/images/molprop/phosphonic_ester-003.png

phosphonylnitrile
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/phosphonylnitrile-001.png
     -
     -

phosphoramides
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/phosphoramides-001.png
     - .. image:: ../../../common/images/molprop/phosphoramides-002.png
     - .. image:: ../../../common/images/molprop/phosphoramides-003.png

phosphoranes
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/phosphoranes-001.png
     - .. image:: ../../../common/images/molprop/phosphoranes-002.png
     - .. image:: ../../../common/images/molprop/phosphoranes-003.png

phosphoric_acid
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/phosphoric_acid-001.png
     - .. image:: ../../../common/images/molprop/phosphoric_acid-002.png
     - .. image:: ../../../common/images/molprop/phosphoric_acid-003.png

phosphoric_ester
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/phosphoric_ester-001.png
     - .. image:: ../../../common/images/molprop/phosphoric_ester-002.png
     - .. image:: ../../../common/images/molprop/phosphoric_ester-003.png

phosphoryl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/phosphoryl-001.png
     - .. image:: ../../../common/images/molprop/phosphoryl-002.png
     - .. image:: ../../../common/images/molprop/phosphoryl-003.png

phthalimides_PHT
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/phthalimides_PHT-001.png
     - .. image:: ../../../common/images/molprop/phthalimides_PHT-002.png
     - .. image:: ../../../common/images/molprop/phthalimides_PHT-003.png

polyenes
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/polyenes-001.png
     - .. image:: ../../../common/images/molprop/polyenes-002.png
     - .. image:: ../../../common/images/molprop/polyenes-003.png

primary_amine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/primary_amine-001.png
     - .. image:: ../../../common/images/molprop/primary_amine-002.png
     - .. image:: ../../../common/images/molprop/primary_amine-003.png

propiolactones
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/propiolactones-001.png
     - .. image:: ../../../common/images/molprop/propiolactones-002.png
     - .. image:: ../../../common/images/molprop/propiolactones-003.png

pseudo_amine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/pseudo_amine-001.png
     - .. image:: ../../../common/images/molprop/pseudo_amine-002.png
     - .. image:: ../../../common/images/molprop/pseudo_amine-003.png

quinone
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/quinone-001.png
     - .. image:: ../../../common/images/molprop/quinone-002.png
     - .. image:: ../../../common/images/molprop/quinone-003.png

ring
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/ring-001.png
     - .. image:: ../../../common/images/molprop/ring-002.png
     - .. image:: ../../../common/images/molprop/ring-003.png

saponin_derivatives
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/saponin_derivatives-001.png
     -
     -

SCN2
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/SCN2-001.png
     - .. image:: ../../../common/images/molprop/SCN2-002.png
     - .. image:: ../../../common/images/molprop/SCN2-003.png

secondary_amine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/secondary_amine-001.png
     - .. image:: ../../../common/images/molprop/secondary_amine-002.png
     - .. image:: ../../../common/images/molprop/secondary_amine-003.png

squalestatin_derivatives
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/squalestatin_derivatives-001.png
     -
     -

sulfide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/sulfide-001.png
     - .. image:: ../../../common/images/molprop/sulfide-002.png
     - .. image:: ../../../common/images/molprop/sulfide-003.png

sulfinimine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/sulfinimine-001.png
     - .. image:: ../../../common/images/molprop/sulfinimine-002.png
     - .. image:: ../../../common/images/molprop/sulfinimine-003.png

sulfinylthio
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/sulfinylthio-001.png
     - .. image:: ../../../common/images/molprop/sulfinylthio-002.png
     - .. image:: ../../../common/images/molprop/sulfinylthio-003.png

sulfonamide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/sulfonamide-001.png
     - .. image:: ../../../common/images/molprop/sulfonamide-002.png
     - .. image:: ../../../common/images/molprop/sulfonamide-003.png

sulfone
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/sulfone-001.png
     - .. image:: ../../../common/images/molprop/sulfone-002.png
     - .. image:: ../../../common/images/molprop/sulfone-003.png

sulfonic_acid
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/sulfonic_acid-001.png
     - .. image:: ../../../common/images/molprop/sulfonic_acid-002.png
     - .. image:: ../../../common/images/molprop/sulfonic_acid-003.png

sulfonic_ester
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/sulfonic_ester-001.png
     - .. image:: ../../../common/images/molprop/sulfonic_ester-002.png
     - .. image:: ../../../common/images/molprop/sulfonic_ester-003.png

sulfonimine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/sulfonimine-001.png
     - .. image:: ../../../common/images/molprop/sulfonimine-002.png
     - .. image:: ../../../common/images/molprop/sulfonimine-003.png

sulfonyl_halide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/sulfonyl_halide-001.png
     - .. image:: ../../../common/images/molprop/sulfonyl_halide-002.png
     - .. image:: ../../../common/images/molprop/sulfonyl_halide-003.png

sulfonylnitrile
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/sulfonylnitrile-001.png
     - .. image:: ../../../common/images/molprop/sulfonylnitrile-002.png
     - .. image:: ../../../common/images/molprop/sulfonylnitrile-003.png

sulfonylurea
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/sulfonylurea-001.png
     - .. image:: ../../../common/images/molprop/sulfonylurea-002.png
     - .. image:: ../../../common/images/molprop/sulfonylurea-003.png

sulfoxide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/sulfoxide-001.png
     - .. image:: ../../../common/images/molprop/sulfoxide-002.png
     - .. image:: ../../../common/images/molprop/sulfoxide-003.png

t_butyldimethylsilyl_TBDMS
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/t_butyldimethylsilyl_TBDMS-001.png
     - .. image:: ../../../common/images/molprop/t_butyldimethylsilyl_TBDMS-002.png
     - .. image:: ../../../common/images/molprop/t_butyldimethylsilyl_TBDMS-003.png

t_butyldiphenylsilyl_TBDPS
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/t_butyldiphenylsilyl_TBDPS-001.png
     - .. image:: ../../../common/images/molprop/t_butyldiphenylsilyl_TBDPS-002.png
     -

t_butyl_ether
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/t_butyl_ether-001.png
     - .. image:: ../../../common/images/molprop/t_butyl_ether-002.png
     - .. image:: ../../../common/images/molprop/t_butyl_ether-003.png

t_butoxycarbonyl_tBOC
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/t_butoxycarbonyl_tBOC-001.png
     - .. image:: ../../../common/images/molprop/t_butoxycarbonyl_tBOC-002.png
     - .. image:: ../../../common/images/molprop/t_butoxycarbonyl_tBOC-003.png

terminal_vinyl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/terminal_vinyl-001.png
     - .. image:: ../../../common/images/molprop/terminal_vinyl-002.png
     - .. image:: ../../../common/images/molprop/terminal_vinyl-003.png

tertiary_amine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/tertiary_amine-001.png
     - .. image:: ../../../common/images/molprop/tertiary_amine-002.png
     - .. image:: ../../../common/images/molprop/tertiary_amine-003.png

tetrahydropyran_THP
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/tetrahydropyran_THP-001.png
     - .. image:: ../../../common/images/molprop/tetrahydropyran_THP-002.png
     - .. image:: ../../../common/images/molprop/tetrahydropyran_THP-003.png

thioamide
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/thioamide-001.png
     - .. image:: ../../../common/images/molprop/thioamide-002.png
     - .. image:: ../../../common/images/molprop/thioamide-003.png

thiocarbamate
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/thiocarbamate-001.png
     - .. image:: ../../../common/images/molprop/thiocarbamate-002.png
     - .. image:: ../../../common/images/molprop/thiocarbamate-003.png

thiocarbonyl
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/thiocarbonyl-001.png
     - .. image:: ../../../common/images/molprop/thiocarbonyl-002.png
     - .. image:: ../../../common/images/molprop/thiocarbonyl-003.png

thioester
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/thioester-001.png
     - .. image:: ../../../common/images/molprop/thioester-002.png
     - .. image:: ../../../common/images/molprop/thioester-003.png

thiol
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/thiol-001.png
     - .. image:: ../../../common/images/molprop/thiol-002.png
     - .. image:: ../../../common/images/molprop/thiol-003.png

thiourea
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/thiourea-001.png
     - .. image:: ../../../common/images/molprop/thiourea-002.png
     - .. image:: ../../../common/images/molprop/thiourea-003.png

triacyloxime
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/triacyloxime-001.png
     - .. image:: ../../../common/images/molprop/triacyloxime-002.png
     - .. image:: ../../../common/images/molprop/triacyloxime-003.png


triazine
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/triazine-001.png
     - .. image:: ../../../common/images/molprop/triazine-002.png
     - .. image:: ../../../common/images/molprop/triazine-003.png

tricarbo_phosphene
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/tricarbo_phosphene-001.png
     - .. image:: ../../../common/images/molprop/tricarbo_phosphene-002.png
     - .. image:: ../../../common/images/molprop/tricarbo_phosphene-003.png


triflates
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/triflates-001.png
     - .. image:: ../../../common/images/molprop/triflates-002.png
     - .. image:: ../../../common/images/molprop/triflates-003.png

triisopropylsilyl_TIPS
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/triisopropylsilyl_TIPS-001.png
     - .. image:: ../../../common/images/molprop/triisopropylsilyl_TIPS-002.png
     - .. image:: ../../../common/images/molprop/triisopropylsilyl_TIPS-003.png

trimethylsilyl_TMS
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/trimethylsilyl_TMS-001.png
     - .. image:: ../../../common/images/molprop/trimethylsilyl_TMS-002.png
     - .. image:: ../../../common/images/molprop/trimethylsilyl_TMS-003.png

unbranched_chain
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/unbranched_chain-001.png
     - .. image:: ../../../common/images/molprop/unbranched_chain-002.png
     - .. image:: ../../../common/images/molprop/unbranched_chain-003.png

urea
-------------------------------------------------------------------------------

.. list-table::
   :widths: 35 35 35
   :header-rows: 0

   * - .. image:: ../../../common/images/molprop/urea-001.png
     - .. image:: ../../../common/images/molprop/urea-002.png
     - .. image:: ../../../common/images/molprop/urea-003.png

.. _filter_files_newrules:

New Rules
========================

New rules specify additional functional groups or substructures that
may be used. They must specify a substructure definition in the form
of a SMARTS pattern, in addition to the substructure name and maximum
limit. For example:

::

   NEWRULE norbornane 1 C1CC2CCC1C2

The first field is the ``NEWRULE`` keyword. The second field defines
the name associated with the substructure (primarily for logging
purposes). The third field indicates the maximum number of the
substructure that can be allowed. The fourth field is the SMARTS
string for the substructure, norbornane in this case. This example rule
indicates that molecules with a single norbornane substructure
would be allowable, but those with two or more norbornanes would be
eliminated.

New rules that have a name that is identical with one of the original
rules take precedence over the original rule.

.. _filter_files_selection:

Selection Statements
========================

The selection statement allows a filter file to specify the required
number of substructures in order to be able to pass the filter. These
statements are similar to new rules except that they list a required
range for passing the filter rather than the range for failing to pass
the filter. For example:

::

   SELECT amine 1 1 [N;!$(*-*[!#6;!#1]);!$(*-a);!$(*=,#*)]

The first field is the ``SELECT`` keyword. The second field indicates
the name for the selection (again for logging purposes). The third
field is the minimum number of substructures required to be in the
molecule. The fourth field is the maximum number of substructures
allowed in the molecule. The fifth field is the substructure defined
by a SMARTS pattern. The example requires that molecules contain
exactly one amine. Only a single ``SELECT`` statement is
allowed in the filter file. Any complex boolean substructure
statements can be incorporated directly into the SMARTS. If multiple
``SELECT`` statements occur in a filter file, only the final one will
be applied.



.. _chapter_omega:

OMEGA
=====

.. toctree::
   :maxdepth: 2

   omega_overview
   omega_gpuomega
   omega_example
   omega_help
   omega_req_params
   omega_opt_params
   omega_add_specs


.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _omega_overview:

.. program:: omega 

======================
Overview
======================

**OMEGA** is a tool for generating 3D conformations of molecules. 
It provides two different methods for conformation generation: torsion driving and distance geometry. The torsion driving method works best on molecules that do NOT contain large, flexible rings, while the distance geometry method works for all molecules but has been designed for molecules that do contain large, flexible rings (macrocycles).

**OMEGA** can be used with various preset modes that generate conformers suitable
for different downstream applications.

	* ``classic``: The ``classic`` mode is the original customizable **OMEGA** interface.
	* ``rocs``: The ``rocs`` mode generates conformers for **ROCS**.
	* ``fastrocs``: The ``fastrocs`` mode generates conformers for **FastROCS**. 
	* ``pose``: The ``pose`` mode generates conformers for **OEDocking**. 
	* ``dense``: The ``dense`` mode generates conformers for **Freeform**.
	* ``macrocycle``: The ``macrocycle`` mode uses a different
	  algorithm than the other modes and is designed for conformation generation of molecules
	  that contain large, flexible rings (macrocycles).


.. _omega_gpuomega:

********************************************************************************
GPU-Omega
********************************************************************************

**GPU-Omega** refers to the CUDA-enabled GPU implementation of **OMEGA**. **GPU-Omega** takes
advantage of a GPU during torsion driving for accelerated conformer generation. To
make use of **GPU-Omega** conformer generation, please follow the guidelines below.

Prerequisites
--------------------------------------------------------------------------------


GPU-Related Requirements
========================

The following features are required in order to use GPU-accelerated OpenEye toolkits and applications.


Supported Platforms
-------------------

CUDA-enabled OpenEye software is only available on supported Linux platforms.
For supported Linux platforms see the `Platform Support Page <https://www.eyesopen.com/supported-platforms>`_.


Supported GPUs
-------------------

An NVIDIA `Tesla <http://www.nvidia.com/object/tesla-supercomputing-solutions.html>`_,
`Quadro <http://www.nvidia.com/object/workstation-solutions.html>`_, or
`GeForce <http://www.nvidia.com/object/geforce_family.html>`_ GPU with a **compute capability of 3.5
or higher** is required on your system. For a comprehensive table of compute capability
categories for each GPU, please refer to the `CUDA <https://en.wikipedia.org/wiki/CUDA>`_ Wikipedia page.


NVIDIA Drivers
-------------------

* **Minimum NVIDIA Driver version: 450.x**.

* CUDA is **not** required to be installed.

We recommend driver `450.80.02 <https://www.nvidia.com/Download/driverResults.aspx/165294/en-us>`_, and
we strongly advise manually downloading and installing the appropriate NVIDIA driver
for your system as opposed to using a package manager.

To install, root privilege is required. Follow these steps:

  #. Download the driver to the machine you are installing it on.
  #. ``chmod +x`` the driver package to make it executable.
  #. Ensure you have disabled X-server by killing any running sessions.
     Reboot may be required if X-server is still running after this step.
     
     .. warning::

        Disabling X-server requires different processes to be killed depending on your Linux
        distribution.
        See the `NVIDIA installation guide
        <http://docs.nvidia.com/cuda/cuda-installation-guide-linux/#runfile>`_ for more details.

     .. warning::

        The NVIDIA kernel module can often conflict with the open source
        Nouveau display drivers, depending on your specific Linux
        distribution. The NVIDIA documentation is a much more complete
        and up-to-date source for information on how to work around this issue.
        See `Disabling Nouveau
        <http://docs.nvidia.com/cuda/cuda-installation-guide-linux/#runfile-nouveau>`_ on the NVIDIA website.

  #. Install the driver by ``sudo ./NVIDIA-Linux-x86_64-450.80.02.run`` and follow the step-by-step installation instructions.

  For more details on driver installations, see the `CUDA Installation Guide
  <https://docs.nvidia.com/cuda/cuda-installation-guide-linux/#runfile>`_

.. note::

  The output of the ``nvidia-smi`` command is extremely useful when
  debugging GPU issues. Please include the output from
  ``nvidia-smi`` in any request to support@eyesopen.com.


Performance Tuning
-------------------

To get the most performance out of an NVIDIA graphics card, use the persistence daemon to switch persistence mode
across all cards on the system (root privilege required)::

  sudo nvidia-persistenced --user foo

This will automatically enable persistence mode after reboot.

For full instructions on the persistence daemon, see the `Persistence daemon section
<https://docs.nvidia.com/deploy/driver-persistence/index.html#persistence-daemon>`_ of the NVIDIA docs.

.. _section_gpuomega_app_usage:

Usage
--------------------------------------------------------------------------------
* **GPU-Omega** accelerates the torsion driving component of conformer generation in **OMEGA** and is
  available through the `-useGPU` flag.

  .. code-block:: bash

   prompt> oeomega classic -in drugs.mol2 -out drugs.oeb.gz -useGPU true

  The `-useGPU` true flag will engage **GPU-Omega** for accelerated torsion driving using a GPU if one is present on
  the system.

* By default, if a GPU is detected at runtime, torsion driving will be carried
  out on the GPU. To turn this feature off and run on the CPU, set the flag `-useGPU` to false.

* **GPU-Omega** uses the default mmff94smod_NoEstat force field. If attempting to use an alternative
  force field, conformer generation will fall back to the CPU. As a result of this, **GPU-Omega** is not
  compatible with the default settings of the **OMEGA** ``dense`` sampling mode. To take advantage of a GPU
  with ``dense`` sampling mode, set `-searchff` to `mmff94smod_NoEstat`.

* **GPU-Omega** does *not* support the distance geometry method of torsion driving, and therefore
  is incompatible with the ``macrocycle`` mode.


.. _omega_examples:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: omega

======================
Example Commands
======================

This section has a series of example **OMEGA** command line executions.  Each
example is followed by a brief description of its behavior.
Sample data files can be found in the data directory.

Basic Commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   prompt> oeomega classic drugs.smi drugs.oeb.gz
   prompt> oeomega classic -in drugs.smi -out drugs.oeb.gz

These two commands will yield identical results.  These execute **OMEGA** ``classic`` with the
default parameters.  The file `drugs.smi` is opened in SMILES format for
input, and the output is written to the file `drugs.oeb.gz` in gzipped
OEBinary format.

.. code-block:: bash

   prompt> oeomega macrocycle -in drugs.smi
   prompt> oeomega macrocycle -in pdb_10_examples.oeb -prefix pdbexamples -mpi_np 8

The first command executes **OMEGA** ``macrocycle`` mode with the default parameters. By default, the conformers
are written to the file `oeomega_macrocycle_conformers.oeb.gz`. The macrocycle mode execution will
take a longer time than the classic mode and usually result in fewer conformers for the same input
molecule. The second command executes ``macrocycle`` mode using an input file with macrocyclic
molecules. The conformers are written to the file `pdbexamples_conformers.oeb.gz` and the
execution time will be even longer because of the macrocyclic molecules. It is preferable to run
the ``macrocycle`` mode under Open MPI using the maximum number of CPU cores available.

Using Parameters and Param Files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   prompt> oeomega classic -in drugs.smi -out drugs.oeb.gz -maxconfs 1

The parameter `-maxconfs` can be used to specify the maximum number of conformers for each output molecule.
This command will generate a single low energy conformer for every molecule in drugs.smi.

.. code-block:: bash

   prompt> oeomega classic -in drugs.smi -out drugs.oeb.gz -param myparameters

This command is the same as the basic commands above except for the `-param` flag.
It executes **OMEGA** ``classic`` with the parameters found in the `myparameters`
file.  The file `drugs.smi` is opened in SMILES format for input, and
the output is written to the file `drugs.oeb.gz` in gzipped OEBinary
format.

.. code-block:: bash

   prompt> oeomega classic -param myparameters drugs.smi drugs.oeb.gz
   prompt> oeomega classic drugs.smi drugs.oeb.gz -param myparameters

The first of these two commands will yield exactly the same results as the
example above.  `drugs.smi` will be mapped to the `-in` flag and
`drugs.oeb.gz` will be mapped to the `-out` flag to begin the second to
last and last command line arguments, respectively.  Unfortunately, the second
of these two commands will fail to parse because the implicit input and output
arguments are not the final two arguments in the list.

.. code-block:: bash

   prompt> oeomega classic -in drugs.smi -out drugs_maxconfs600.oeb.gz
                  -param myparameters -maxconfs 600

Again, this is a very similar command.  It executes **OMEGA** `classic` using the
parameters in the `myparameters` file, except the `-maxconfs`
parameter is overridden with the 600 from the command line.  The
command line `-maxconfs` parameter would take precedence over the
value in the parameter file independent of the order of flags on the
command line.

Advanced Commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   prompt> oeomega classic -in drugs.mol2 -out drugs.oeb.gz -fromCT true

The `-fromCT` true flag will cause **OMEGA** `classic` to ignore the input
conformations in the `drugs.mol2` file.  An initial conformation will
be generated by a distance-bounds algorithm from the connection table of
the molecules in the input file.  Be aware that the default value of
`-fromCT` is true, however it is listed explicitly here for emphasis.

.. code-block:: bash

   prompt> oeomega classic -in drugs.smi -out drugs.oeb.gz -log null

The `-log` flag normally allows specification of the log file's name.
However, `nul` and `null` are reserved names which indicate that
no log file will be written (this includes failure modes).

CSV Report File for ``macrocycle`` Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For each molecule in the input file, a row of data with the following columns is recorded:

* `Molecule`
   Title of the molecule.

* `SMILES`
   SMILES string corresponding to the molecule.

* `Conformers`
   Number of conformers in the output file. Its maximum number is always smaller than
   or equal to the value of the :option:`-maxconfs`.

* `LargestRing`
   Size of the largest ring system in the molecule.

   .. note:: **All fused rings are considered to be a part of the macrocycle ring. Within this
      convention, decalin is assumed to be a 10-membered ring system.**

* `Iterations`
   This number is equal to the parameter :option:`macrocycle -max_iterations`.

* `Elapsed Time`
   Time used to generate conformers (in seconds).

* `Status`
   Failure reason in case conformers are not generated.

   .. note:: **Message: "No conformer left after post processing" is usually caused by a chirality mismatch
      between the chirality of the input molecule and the chirality of each generated conformation.
      It means that the force field refinement was not able to reproduce input chirality. It is recommended
      therefore to check the correctness of chirality input molecule. This situation is common when the input
      is taken from the 3D PDB file. A good example is the PDB structure of the rifampicin antibiotic extracted
      from the 1SKX entry. This molecule has nine atomic chiral centers and two chiral bonds. Its chirality
      assignment based on the 3D PDB structure differs from the actual chirality of this antibiotic.**


.. _omega_help:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: omega 

============================
Command Line Help
============================

A description of the command line interface can be obtained by executing **OMEGA**
with the `--help` option.

.. code-block:: bash
   
   prompt> oeomega --help

will generate the following output:

::

  Available Modes:
    classic - The original customizable **OMEGA** interface
    macrocycle - Conformer generation for macrocycles
    fastrocs - Optimal conformer generation for FastROCS
    rocs - Optimal conformer generation for ROCS
    pose - Optimal conformer generation for molecular alignment
           and pose prediction by docking
    dense - Optimal conformer generation for Freeform

  For more help type:
    oeomega classic --help
    oeomega macrocycle --help
    oeomega fastrocs --help
    oeomega rocs --help
    oeomega pose --help
    oeomega dense --help

There are four help functions available for each mode:

::

  Help functions:
    oeomega <mode> --help simple      : Get a list of simple parameters
    oeomega <mode> --help all         : Get a complete list of parameters
    oeomega <mode> --help <parameter> : Get detailed help on a parameter
    oeomega <mode> --help html        : Create an html help file for this program



.. _omega_req_params:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _omega-interface:

=======================
Required Parameters
=======================

.. option:: -in

   File containing one or more molecular connection
   tables to be processed by **OMEGA**. Multiple input files of the same format can be merged together into a single input file using the `cat` command.
   A pipe can be used to avoid writing the merged input file to disk.

   .. code-block:: bash
      
      cat filename1.ism filename2.ism | oeomega classic -in .ism -out output.oeb.gz

   Supported file formats: 
   cxsmiles, ism, mol2, oeb, oez, sdf, smi, and the corresponding compressed formats (i.e., xx.gz).
   ``lst`` and ``list`` formats containing lists of supported files are also applicable.


.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _omega_opt_params:

=======================
Optional Parameters
=======================

Execute Options
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -param

   The argument for this flag is the name of a
   file containing control parameters.  The control parameter file acts
   to either replace or augment the command line interface.  All
   parameters necessary for program execution may be provided in the
   control parameter file, although any command given explicitly on the
   command line will supersede options found in the parameter file.
   The application generates a new parameter file containing the full set of
   execution parameters upon every execution.  The name of the
   parameter file is created by combining the prefix
   base name with the *'_parm'* suffix and the *'.txt'* extension.

.. option:: -mpi_np <n>

   Specifies the number of processors ``n`` when the application is run in MPI mode.

.. option:: -mpi_hostfile <filename>

   Specifies the name of the file containing the processor's configuration. For every host,
   this file should contain a line ``host_name slots=n`` where ``n`` is the number of
   processors on the host.



.. program:: omega

File Options
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -out

   This file writes conformers generated by **OMEGA**. Gzipped OEBinary is the
   recommended output format.

   Supported file formats: 
   mol2, oeb, oez, sdf, and the corresponding compressed formats (i.e., xx.gz).

.. option:: -failed

   This file writes molecules for which **OMEGA** fails to generate conformers. A failed file is only
   generated when specifically requested by users.

   Supported file formats: 
   cxsmiles, ism, mol2, oeb, oez, sdf, smi, and the corresponding compressed formats (i.e., xx.gz).

.. option:: -commentEnergy

   This flag causes the conformer energy in kcal/mol to
   be written in the comment field for each conformer.  This is
   particularly useful when writing SD or MOL2 files that will be
   passed to software that anticipates strain energies written in the
   comment field.  [Default=false]

.. option:: -includeInput

   When true, this boolean flag will include the
   input conformer in the output file. This requires that the input file
   format is in a 3D format (e.g., SDF, MOL2, OEB). [Default=false]

.. option:: -log

   The argument for this flag specifies the name of
   the log file.  The level of detail for log file information can be
   altered using the :option:`-verbose` flag.  Output can
   be directed to the terminal as well with the :option:`-progress` log option.  Generation of an
   output log may be disabled by providing ``nul`` as a argument in Windows and ``/dev/null`` as an
   argument on Linux and macOS.  [Default=``prefix`` _log.txt]

.. option:: -prefix

   The argument for this flag defines the prefix to be used
   for various information and data files generated by **OMEGA**.  Most
   important among these is the *oeomega_<mode>_parm.txt* file which includes a
   copy of all the parameters used in the **OMEGA** run.  The prefix is
   also used to generate a default log file name if it is not explicitly
   specified with the *-log* flag. [Default=oeomega_<mode>].

.. option:: -progress

   This flag shows the progress on screen.  Options are *none*, *dots*, *log*, and *percent*.
   The *dots* options will display dots on-screen to show molecules
   completed.  The *log* option will duplicate the log file on-screen.
   The *percent* option will track progress through the input file.  [Default=none]

.. option:: -rotorOffsetCompress

   This flag controls the behavior of
   writing the rotor offset compressed flavor of the OEBinary format.
   Rotor offset compressed files contain the same information as
   standard Cartesian OEBinary files but require a small fraction of
   the storage space.  Optimal compression of **OMEGA** output can be
   obtained by writing gzip compressed OEBinary files with the
   `-rotorOffsetCompress` flag turned on. [Default=true]

.. note:: **Rotor offset compression cannot be performed and is automatically
   disabled when any of the methods to fix part of the molecule geometry,
   such as -fixmol, -fixfile, -fixsmarts, or -fixmcs, are used during
   conformer generation.**

.. option:: -sdEnergy

   This flag controls the
   behavior of writing strain energies as SD tags.  This flag may be
   used with either OEBinary or MDL SD files.  [Default=false]

.. option:: -verbose

   This is a boolean flag that controls the level of
   detail written to the log file.  By default, **OMEGA** will only write
   minimal information to the log file.  Molecule titles and warning
   messages constitute the bulk of logging at the default level.
   Verbose logging will cause more information to be written to the log
   file in order to follow behavior during program execution.  In order to
   have the log shown on the screen, use `-progress log`.  [Default=false]

.. option:: -warts

   This boolean flag is used to generate unique titles for
   conformers that reflect their position in an ensemble of
   conformations produced by **OMEGA**.  The title given to each conformer
   will begin with the molecule title taken from the input file and
   appended with an underscore and the integer corresponding to the
   rank order number of the conformer in the final ensemble.  [Default=false]

3D Construction Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -addfraglib

   [alias: -setfraglib]

   The argument that follows this flag is
   one fragment file, normally generated by MakeFraglib.
   These fragments will supplement the built-in fragment library.

   For use in a Windows platform, an enhanced fragment library, ``omega_fragment_lib_2023.oeb.gz``,
   that improves the performance of conformer
   generation is available upon request from the `database downloads page
   <https://www.eyesopen.com/database-downloads>`_. The enhanced library is the
   default on both Linux and OSX.

.. option:: -buildff

   This flag sets the force field used for
   constructing fragments that are assembled to build an initial model
   of the input structure.  Consult the description of force fields
   (see :ref:`section_ForceFields`) for an explanation of appropriate
   arguments for this flag.  [Default=mmff94smod_NoEstat]

.. option:: -canonOrder

   This flag can be used to disable the
   automatic reordering of input molecules to a canonical atom and bond
   order.  In order to obtain consistent results from different file
   formats and different connection table orders, **OMEGA** reorders the
   input connection table.  This behavior can be turned off using the
   `-canonOrder` flag; however, the resultant ensembles will
   likely be inconsistent in their composition. [Default=true]

.. option:: -deleteFixHydrogens

   When a fixfile fragment is
   specified, all possible mappings (matches) of the fragment and the
   input molecule are considered for positioning the input molecule.
   This process begins with a substructure search of the fragment in
   the input molecule.  If hydrogens are included on the fixfile
   fragment, the number of possible matches will grow exponentially
   with the number of equivalences.  Each geminal hydrogen pair on the
   fixfile produces a nonproductive match multiplied by all other
   nonproductive matches.  This flag can be used to prevent the
   explosion of nonproductive matches by deleting hydrogens from the
   fixfile fragment prior to the substructure search.  [Default=true]

.. option:: -fixfile

   The argument that follows this flag is a molecule file
   used to specify the coordinates for a substructure of the input
   molecules.  An initial structure is generated for every input
   molecule, then a substructure search is performed using the
   molecule or fragment provided in the fixfile as a query molecule.
   Every instance of the fixed substructure found in the input molecule
   up to a predetermined limit (see `maxmatch` and `umatch`)
   is used to replace the coordinates of the atoms that match the
   substructure.  The input molecule coordinates are aligned relative
   to the substructure prior to fragment replacement, then the
   coordinates are taken from the fixed fragment and assigned to the
   corresponding atoms of the input molecule.  A separate alignment,
   replacement, and conformer search is carried out for every
   matching substructure in the input molecule.  Molecules that do not
   match the fixfile will fail and will be reported as such in the log file.

.. option:: -fixmcs

   This flag fixes a portion of a molecule based on the maximum common subgraph against the
   `-fixfile` molecule.   Molecules that do not have any common subgraph will fail
   and be reported as such in the log file.
   [default = false]

.. option:: -fixrms

   Fixfile fragments taken from crystallographic
   sources may differ in their geometry relative to optimal MMFF94
   geometries.  **OMEGA** attempts to superimpose built structures onto
   fixfile fragments, and if the geometry differs too greatly, **OMEGA**
   considers the superposition a poor match and will fail to build a
   structure using the fixfile.  This flag can be used to loosen the
   default RMS superposition criteria to allow suboptimal
   superpositions to succeed in spite of the poor geometric
   complementarity.  [Default=0.15]

.. option:: -fixsmarts

   This is another way to specify a fixed portion of a molecule.  The SMARTS pattern is used to fix a portion of the `-fixfile` primarily, or to fix a portion
   of the input molecule if `-fromCT` is set to *false* secondarily.   Molecules that do not
   match will fail and be reported as such in the log file.

.. option:: -fixmcs

   This flag fixes a portion of a molecule based on the maximum common subgraph against the
   `-fixfile` molecule.   Molecules that do not have any common subgraph will fail
   and be reported as such in the log file.
   [Default=false]

.. option:: -fromCT

   This boolean flag determines whether **OMEGA** should
   generate an initial set of 3D coordinates using only the connection
   table of the input molecule.  Initial model generation is always
   necessary for molecule file formats devoid of coordinates (i.e.,
   SMILES).  Bond lengths and angles taken from molecule files
   containing coordinates may be retained by setting this flag to
   false.  `-enumNitrogen off` must also be set for identical stereochemistry
   to be guaranteed in the output.  [Default=true]

.. option:: -maxmatch

   This flag is used to limit the number
   of fixfile substructure matches in the input molecule.  Each match
   will result in replacement of the matching substructure with
   coordinates taken from the fixfile fragment.  The number of matches
   may need to be limited using this parameter for a substructure
   where many matches are possible.  [Default=1]

.. option:: -mcsMinAtoms

   This parameter is used to define the limit of MCS-based fixes using `-fixmcs`.
   This is the minimum number of atoms that is required for a MCS-based fix.
   [Default=1]

.. option:: -strictfrags

   This flag sets how **OMEGA** generates fragments that are not in the fragment library.  The default is
   a faster and less rigorous fragment generation than the **MakeFragLib** program, whereas
   a *true* value will require **OMEGA** to be identical to the **MakeFragLib** program.  The most noticeable
   difference is the time limit for fragment generation, which is increased from 30 seconds to 300 seconds with
   `-strictfrags` set to ``true``.  [Default=false]

.. option:: -strictatomtyping

   This flag uses strict atom typing for MMFF94 or allows "close enough" atom typing.  A *true* setting will fail any molecule
   that contains an atom type that does not have specified parameters.  A *false* setting will allow parameters
   from a similar atom type to be used.  [Default=true]

.. option:: -umatch

   The *-umatch* boolean flag determines whether only
   the unique substructure matches of the fixfile are used for
   coordinate replacement.  A unique substructure match is defined as a
   match that does not cover the identical set of target atoms as any
   other substructure match in a set.  For example, a benzene
   substructure will match a benzene ring 12 times.  Only one
   substructure match constitutes a unique match, while the other 11
   matches are duplicates.  If the flag is set to *false*, then all
   possible substructure matches may be used for coordinate
   replacement.  This behavior is usually unnecessary as nonunique
   matches will frequently lead to duplication. [Default=true]

Structure Enumeration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -enumNitrogen

   The `-enumNitrogen` string flag controls
   the behavior of **OMEGA** with respect to enumeration of nonterminal
   nitrogens.  Any nitrogen with pyramidal geometry in the initial
   model of the input molecule and having no more than two ring bonds
   is considered by OMEGA to be *invertible*.  OMEGA will enumerate all
   possible puckers if the `-enumNitrogen` flag is set to ``all``.  OMEGA 
   will only enumerate unspecified invertible nitrogens if the flag is set to ``unspecified``.
   Nitrogen enumeration can be turned off by setting the flag to ``off``.
   [Default=unspecified]

.. option:: -enumRing

   The `-enumRing` boolean flag controls the
   behavior of **OMEGA** with respect to ring conformations.  If this flag
   is set to *true*, **OMEGA** will generate all possible combinations of all
   ring conformations in a molecule.  Ring systems with only a single
   conformation will be replaced with a conformation taken from a
   fragment file or generated on the fly by **OMEGA**. If this flag is set
   to *false*, then no ring conformer enumeration or replacement will
   occur.  Initial geometries provided by an input file (see
   `-fromCT`) may therefore be preserved by setting
   `-enumRing` to *false* as well.  [Default=true]

.. option:: -sampleHydrogens

   This flag sets whether hydrogens will be sampled.  This option enables sampling of hydrogen
   locations for -OH, -SH, and amines.  [Default=false]

Torsion Driving Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -addtorlib

   This flag takes a filename as a parameter.  Torsion rules in the file are placed above any previous torsion rules and therefore are matched first
   (see :ref:`section_TorsionLibraryFormat`).

.. option:: -erange

   The `-erange` flag sets the energy cutoff
   used as an accept or reject criteria for conformers depending on the
   number of rotatable bonds in the structure.  Any conformer that has
   a calculated strain energy less than the sum of the energy window
   and the energy of the global minimum conformer will be accepted.
   Conformers with strain energies above this threshold are rejected.
   The energy range is given as a list of values that
   correspond to the `-rangeIncrement` parameter.  For example,
   `-erange 5.0 10.0 15.0 20.0` used with
   `-rangeIncrement 3` sets the energy window to 5.0 kcal/mol for
   structures with zero to two rotatable bonds, 10.0 kcal/mol for
   structures with three to five rotatable bonds, and so on.  The
   energy window for structures with more rotors than the highest
   `-erange` value specified will be taken as the highest specified
   value. [default = 10.0 15.0 15.0 20.0 (classic) ]

.. option:: -ewindow

   The `-ewindow` flag sets the energy window in kcal/mol used
   as an accept or reject criteria for conformers.  Any conformer that
   has a calculated strain energy less than the sum of the energy
   window and the energy of the global minimum conformer will be
   accepted.  Conformers with strain energies above this threshold are
   rejected. [Default=10.0 (classic) or 20.0 (macrocycle)]

.. option:: -maxConfRange

   The `-maxConfRange` flag allows the user to specify the maximum number of
   conformers to be output for a structure based on the number of rotatable
   bonds in the structure.  The maximum conformer range is given as a list of 
   values that correspond to the `-rangeIncrement` parameter.
   For example, `-maxConfRange 100 150 200 250` used with
   `-rangeIncrement 3` sets the maximum number of conformers to 100 for
   structures with zero to two rotatable bonds, 150 for
   structures with three to five rotatable bonds, and so on.  The
   number of conformers for structures with more rotors than the highest
   `-maxConfRange` value specified will be taken as the highest specified
   value.

.. option:: -maxconfs

   The `-maxconfs` flag sets the maximum number of conformations to be included in the output ensemble for each
   molecule. For molecules with few conformational degrees of freedom, the number of output conformers might be lower than
   the value set for this flag but will never exceed it. Out of all the generated conformers that satisfy the
   other ensemble slicing criteria (like `-ewindow` , `-rms`, etc.), the output
   includes only up to the `-maxconfs` number conformers that are the lowest in energy according force field
   set in `-searchff` flag.
   As a special case, setting `-maxconfs 0` along with `-rms 0` will result in **OMEGA** skipping the duplicate
   removal step and will write all generated conformers that satisfy all other criteria to the output file.
   [Default=200]

.. option:: -maxrot

   The `-maxrot` flag sets the cutoff for the maximum number
   of rotatable bonds.  Molecules that have rotors less than or equal to the `-maxrot`
   cutoff will be processed by **OMEGA**.
   **OMEGA** will not search for conformers of molecules that have more
   rotors than the `-maxrot` cutoff.  By default, **OMEGA** does not
   apply a cutoff for the number of rotatable bonds.  Instead, a desired cutoff
   must be supplied by the user.  [Default=9999]

.. option:: -maxtime

   This flag limits the amount of time (in seconds) spent for the torsion driving search during
   conformer generation for each molecule. The total time used for each molecule may
   exceed this limit due to all other steps of conformer generation.
   [Default=120.0]

.. option:: -rangeIncrement

   The `-rangeIncrement` is used to
   control the range for the number of rotatable bonds used with the
   `-maxConfRange`, `-rmsrange`, and `-erange` flags.
   The preceding flags are used to control the maximum number of
   conformers, RMS cutoff, and energy windows that are dependent
   on the number of rotors in a given structure. [Default=5]

.. option:: -rms

   The `-rms` flag sets the minimum Root Mean Square
   (RMS) Cartesian distance below which two conformers are duplicates.
   The RMS calculation is performed after superposition such that the
   true minimum distance between conformers is calculated.  Lowering
   the `-rms` value may cause **OMEGA** to generate ensembles that
   contain more representative conformers of a similar shape.  Higher
   `-rms` values may result in smaller, yet possibly more, shape-
   diverse ensembles.  [Default=0.5]

.. option:: -rmsrange

   The `-rmsrange` flag allows the user to specify the RMS cutoff used
   for duplicate conformer removal based on the number of rotatable bonds
   in the structure.  The RMS range is given as a list of values that
   correspond to the `-rangeIncrement` parameter.
   For example, `-rmsrange 0.8 1.0 1.2 1.4` used with
   `-rangeIncrement 3` sets the RMS cutoff value to 0.8 for
   structures with zero to two rotatable bonds, 1.0 for
   structures with three to five rotatable bonds, and so on.  The
   RMS cutoff value for structures with more rotors than the highest
   `-rmsrange` value specified will be taken as the highest specified
   value.

.. option:: -searchff

   This flag sets the force field used to calculate
   strain energies of conformers generated during a torsion search.
   Consult the description of force fields (see :ref:`section_ForceFields`)
   for an explanation of appropriate arguments for this flag.  [Default=mmff94smod_NoEstat]

.. option:: -settorlib

   The `-settorlib` flag is used to specify the file
   name of the file containing rules used in resolution control of the
   torsion driving part of conformer generation.  Refer to the :ref:`section_TorsionLibraryFormat` section
   describing the format of the torsion library.

.. option:: -thompson

   The `-thompson` flag sets whether to use Thompson sampling for exploring the conformer space.
   **OMEGA** will use this by default. If switched off, exhaustive sampling will be used. [default = true]

.. option:: -torlibtype

   The `-torlibtype` flag is used to specify the type of built-in torsion library.
   There are two types: `original`, and `guba`. The `original` is
   the default OMEGA torsion library and the `guba` [Guba-2016]_ is available in 
   OMEGA 3.0 and above. [Default=original]

.. option:: -useGPU

   The `-useGPU` flag is used to engage GPU-Omega to accelerate torsion driving on a
   GPU if one is available on the system. See :ref:`omega_gpuomega` for details. [Default=true]

.. option:: -thompson

   The `-thompson` flag sets whether to use Thompson sampling for exploring the conformer space.
   OMEGA will use exhaustive sampling by default. If switched Thompson sampling is used, the parameters
   can be controlled by the Thompson Sampling Options class. [Default=false]

..  _thompson-sampling-parameters:

Thompson Sampling Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -maxTrials

    This parameter sets a limit on the number of Thompson sampling trials.
    OMEGA will stop exploration of the conformer space once this limit is reached,
    irrespective of how many conformers have been found so far. The default (and recommended) way of controlling
    this quantity, however, is through the `-maxTrialsRange` parameter. [Default=0]

.. option:: -maxTrialsRange

    This flag sets the maximum number of trials in Thompson sampling depending on the number of rotatable
    bonds in a given molecule. The range is determined by the `-trialsRangeIncrement` parameter.
    For example, `-maxTrialsRange 1000 2000 3000 5000` used with `-trialsRangeIncrement 3` sets the maximum
    number of trials  to 1000 for molecules with 0–2 rotors, 2000 for 3–5 rotors, 3000 for 6–8 rotors, and 5000 for all
    molecules with 9 or more rotors.

.. option:: -trialsRangeIncrement

    This parameter is used to control the dependence of maximum number of Thompson sampling trials on the
    number of rotors in the molecule along with the
    :ref:`SetMaxTrialsRange<OEConfGen_OEThompsonOptions_SetMaxTrialsRange>` parameter. [Default=1].

.. option:: -batchMaxRotors

    This parameter controls the maximum allowed number of rotors for which batching is done; that is, two
    samples are drawn from the current distributions to form all these rotors.
    The resulting :math:`2^{BatchMaxRotors}` conformers are processed in a batch and the distributions
    associated with the rotors are then updated. Higher `-batchMaxRotors` values result in a lower runtime, but for large
    enough batches, accuracy can be compromised as the learning is not reinforced frequently enough to
    influence many samples. [Default=2]

.. option:: -priorTemperature

    This parameter is used to set the initial probabilities (prior distributions) associated with
    each angle in the torsion rule according to values of respective strain associated with the angles.
    If a rule does not provide these strain values, all angles are assumed to be at zero strain and
    equally likely.
    For nonzero strains, this parameter acts as a Boltzmann temperature and gives the
    probability as :math:`= exp(-1 \times \frac{strain}{PriorTemperature})`.
    The lower the parameter, the stronger the initial preference for the angles with low strain.

    For instance, a torsion angle with strain of 5 kcal/mol will be initialized to a probability of 0.7% for
    `-priorTemperature` of 1, 60.6% for `-priorTemperature`  = 10 and 95% for `-priorTemperature`  = 100.
    [Default=100.0]

..  _omega-stereo-parameters:

Stereo Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -flipper

   This parameter creates an ensemble of stereoisomers before passing the molecules for
   conformer generation.  A value of *true* will flip all unspecified stereo centers and
   a value of *force* will flip all stereo centers.  [Default=false]

.. option:: -flipper_enhstereo

   This flag considers enhanced stereo information during stereo-enumeration.
   [default = false]

.. option:: -flipper_maxcenters

   This flag sets the maximum number of stereocenters that can be flipped exhaustively.
   The number of molecules generated by
   enumerating the stereocenters is :math:`2^N`, where `N` is the number of
   stereocenters.  In some instances, this may be larger than is desired.  The
   `-flipper_maxcenters` parameter indicates the maximum number of stereocenters
   which will be fully enumerated.  If a molecule has more than
   `-flipper_maxcenters` stereocenters, **OMEGA** will randomly enumerate
   `2^(flipper_maxcenters)` instances from the full set of potential isomers.
   [Default=12]

.. option:: -flipper_warts

   This flag adds a wart to the title of each stereoisomer.
   [Default=false]

.. option:: -flipper_enhstereo

   This flag considers enhanced stereo information during stereo-enumeration.
   [Default=false]

.. option:: -strictstereo

   This parameter requires all stereo centers to be specified.  Molecules sent to conformer
   generation with unspecified stereo will fail. [Default=true]

General
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. option:: -strict

   This is a convenience flag for setting *-strictstereo*, *-strictatomtyping*,
   and *-strictfrags* all at once.  This setting will override any individual
   settings for these flags.

.. _omega_macrocycle_opt_params:

.. program:: macrocycle

Options Specific to the Macrocycle Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Execute Options**

.. option:: -mpi_hostfile

   This is the path to the host file to be used for launching MPI processes.

.. option:: -mpi_np

   This is the number of MPI processors to launch. If this is not used, the job will run on a single processor.

.. note:: **The number of processors should be set to a reasonable number,
   preferably the maximum number of CPU cores available.**

.. option:: -param

   This is a parameter file name.

**File Options**

.. option:: -in

   This is the input molecular file name. Contrary to oeomega classic, pipe streaming cannot be used.

.. option:: -molnames

   This parameter specifies a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set, then only molecules in the
   input file(s) (parameter :option:`-in`) with names that match those
   in the text files will be read.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecules that are contained in a large database, without
   having to extract those molecules by hand from the database.

.. option:: -out

   This is the output molecular file name. The following SD tags will be attached to the output:
   "Macrocycle Energy," "Relative Energy," "Macrocycle Iteration," "Macrocycle Duplicate Minima Count,"
   and "RMSD from Input Structure."
   Important note: the macrocycle mode does *not* support the `-rotorOffsetCompress` option.

.. option:: -prefix

   This is the prefix used to name output files.

.. option:: -progress

   This shows progress on the screen.  Options are *none*, *dots*, *log*, and *percent*.
   The *dots* options will display dots on the screen to show molecules that are
   completed.  The *log* option will duplicate the log file on screen.
   The *percent* option will track progress through the input file.  [Default=none]

**Calculation Options**

.. option:: -ewindow

   This is the energy window for output conformers. All conformations with energy higher than the energy window
   will be skipped from the molecular output file.

..  option:: -iteration_cycle_size

    This is the number of iterations to run before checking if a new minimum was found (the run will
    finish if no new minimum is found). [Default=100]
    [Aliases=-cycle_size]

..  option:: -max_iterations

    This is the maximum number of iterations (the calculation may converge before reaching this number).
    Each iteration is a single conformation generation which originates from a unique
    random atom (or fragment) placement. [Default=2000]
    [Aliases=-max_iter]

.. option:: -ref_tolerance

    This is the RMS gradient tolerance for force field refinement. [Default=0.001]

.. option:: -rms

   This is the deduplication threshold. [Default=0.5 |A|].

.. option:: -maxconfs

   The `-maxconfs` flag sets the maximum number of conformations to be included in the output ensemble for each
   molecule. For molecules with few conformational degrees of freedom, the number of output conformers might be lower than
   the value set for this flag but will never exceed it. [Default=400]


.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _omega_additional:

.. program:: omega 

============================
Additional Specifications
============================

OMEGA Modes and Parameters 
---------------------------

**OMEGA** provides the facility for users to select one of a number of
pre-defined ``modes``.  Except for the ``macrocycle`` mode, all of the
other modes share the same set of parameters. However, the default
parameters vary between the various modes.

Default parameters for each mode are described below. While the
default parameters for each mode may vary, the user has the ability to modify 
any parameter in any mode.

*classic*:

The ``classic`` mode is the original customizable OMEGA interface.  All **OMEGA** default
parameters mentioned in the :ref:`Optional Parameters <omega_opt_params>` refer to the ``classic`` mode.

::

    -maxConfRange = 200
    -rangeIncrement = 4
    -eRange = "10, 15, 15, 20"
    -rms = 0.5
    -searchff = mmff94smod_NoEstat

*fastrocs*:

For ``fastrocs`` mode, all default parameters are identical to the default parameters in ``classic`` mode
except for the following changes:

::

    -maxconfs = 10
    -eWindow = 10

*rocs*:

For ``rocs`` mode, all default parameters are identical to the default parameters in ``classic`` mode
except for the following changes:

::

    -maxconfs = 50
    -eWindow = 10

*pose*:

For ``pose`` mode, all default parameters are identical to the default parameters in ``classic`` mode
except for the following changes:

::

    -maxConfRange = "200,200,800"
    -eRange = "10, 15, 25, 30"

*dense*:

For ``dense`` mode, all default parameters are identical to the default parameters in ``classic`` mode
except for the following changes:

::

    -searchff = mmff94s_sheff
    -strictstereo = false 
    -ewindow = 15 
    -maxtime = 3600
    -rms = 0.3
    -maxrot = 20
    -maxconfs = 20000
    -thompson = false

*macrocycle*:

The ``macrocycle`` mode has its own set of default parameters as described in the
:ref:`omega_macrocycle_opt_params`.

.. note:: **All molecules containing 10-membered or larger rings are considered by **OMEGA**
      to be macrocycles except those which are made entirely by fused small rings. For example,
      cyclodecane and porphyrin are  macrocycles but decaline, naphthalene, and all
      polycyclic aromatic hydrocarbons are not.**

.. _section_ForceFields:
    
Force Fields
----------------------

**OMEGA** provides the facility for users to select one of a number of
predefined force fields.  The force field selected may be different
for model construction and torsion search.  The ability to select a
force field provides a mechanism for task specificity.  Some force
fields may be more appropriate for solution phase ensemble generation,
while others may excel for bioactive conformer reproduction.  The
following predefined force fields may be used as arguments to the
`-buildff` and `-searchff` flags.

*  `mmff` This is an exact reproduction of the published Merck Molecular
   Force Field (MMFF94) with additional atom types parameterized
   using the same algorithm.

*  `mmff_NoEstat` This force field variant includes all MMFF94
   terms except Coulomb interactions.

*  `mmff_Trunc` This force field variant excludes both
   Coulomb interactions and the attractive part of van der Waals
   interactions.  All other components of the MMFF94 force field are
   calculated according to literature specifications.

*  `mmff_Sheff` This force field variant includes all MMFF94
   terms, and the Sheffield solvation model [Grant-2007]_ is used during the
   calculation of energies for the conformers generated.

*  `mmff94s` This is an exact reproduction of the 94s variant of the
   Merck Molecular force Field (MMFF94s) with additional atom types
   parameterized using the same algorithm.

*  `mmff94s_NoEstat` This force field variant includes all
   MMFF94s terms except Coulomb interactions.

*  `mmff94s_Trunc` This force field variant excludes both
   Coulomb interactions and the attractive part of van der Waals
   interactions.  All other components of the MMFF94s force field are
   calculated according to literature specifications.

*  `mmff94s_Sheff` This force field variant includes all MMFF94s
   terms, and the Sheffield solvation model [Grant-2007]_ is used during the
   calculation of energies for the conformers generated.

*  `mmff94smod` This is an exact reproduction of the 94s variant of the
   Merck Molecular force Field (MMFF94s) with additional atom types
   parameterized using the same algorithm and some torsion interaction
   parameters modified to produce desired equatorial conformers for
   monosubstituted cyclohexanes.

*  `mmff94smod_NoEstat` This force field variant includes all
   MMFF94s-Mod terms except Coulomb interactions.

*  `mmff94smod_Trunc` This force field variant excludes both
   Coulomb interactions and the attractive part of van der Waals
   interactions.  All other components of the MMFF94s-Mod force field are
   calculated according to literature specifications.

*  `mmff94smod_Sheff` This force field variant includes all MMFF94s-Mod
   terms, and the Sheffield solvation model [Grant-2007]_ is used during the
   calculation of energies for the conformers generated.

*  `sage` This is an exact reproduction of the published SAGE force field, OpenFF-2.2.0,
   from the Open Force Field Initiative.

*  `sage_NoEstat` This force field variant includes all SAGE
   terms except Coulomb interactions.

*  `sage_Sheff` This force field variant includes all SAGE
   terms and the Sheffield solvation model [Grant-2007]_ is used during the
   calculation of energies for the conformers generated.

.. _section_TorsionLibraryFormat:

Torsion Library Format
--------------------------------

A file of alternate torsion rules may be specified with the
`-settorlib` command.  **OMEGA** will match only the first rule found
for a torsion angle and will discontinue matching alternate possible
rules.  Thus, a correctly ordered torsion file will be arranged with
the most specific patterns appearing at the top of the file, and more
general patterns appearing toward the end.  Simple torsion rules are
composed of a single SMARTS pattern containing at least four atom
expressions, followed by a listing of the torsion angles that **OMEGA**
will sample.  Each reference atom in the SMARTS pattern that is used
to define the torsion angle being sampled must have a map index
(numbered 1 through 4) specified that indicates the ordering of the
atoms in the torsion angle.  The pattern must appear all on a single
line, with a carriage return separating one rule from the next.
Comments in the file must be preceded with a `#` character.  The
following is an example of a simple torsion rule.

.. code-block:: bash

   #methyl ester pattern
   [O:1]=[C:2]-[O:3][CH3:4] 0

More advanced rules may be included that alter the energy calculation
for particular torsion angles.  In these types of torsion rules, a
SMARTS pattern with associated map indices is still used to define the
molecular environment in which the rule is to be applied, but the
sampled values appear on subsequent lines with one torsion angle per
line.  The first number per line indicates the torsion angle, in
degrees, that **OMEGA** must sample.  If a second number follows a torsion
angle on the same line, the value is added to the total energy
computed for that conformer.  The following is an example of an
advanced torsion rule.

.. code-block:: bash

   #experimental structure test
   O=[C:1][NX3H:2][c:3]([cH,nH0])[nH:4]
   0
   180 10.0
   <end>


Utilities
=========

.. toctree::
   :maxdepth: 2

   flipper
   makefraglib
   oebtosdconf



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: flipper

.. _chapter_flipper:

*************
Flipper
*************

====================
Overview
====================

The **OMEGA** distribution includes **Flipper**, a utility program for
enumerating stereocenters in a molecule.  We have taken the philosophy that
conformer generation and stereochemistry enumeration are related but distinct
problems.  Thus we provide **Flipper** as part of the **OMEGA** product, but not as
part of the same executable.

The current version of **Flipper** can handle enumeration of R/S
stereochemistry (including N and S stereochemistry) as well as
cis/trans stereochemistry. **Flipper** uses graph algorithms to determine
which atoms are stereocenters.  If a stereocenter has a designated
stereochemistry, by default **Flipper** does not change the stereochemistry.
However, if a stereocenter does not have a specified stereochemistry,
**Flipper** will enumerate both stereochemistry states of the stereocenter.

Many common file formats are limited in their ability to fully express
stereochemistry without resorting to Cartesian coordinates.  This can
lead to ambiguity in whether a particular conformer is supposed to
represent a racemic mixture or an isolated stereoisomer. SD file format performs
better than most, as it allows the designation of R, S, or racemic on
each tetrahedral stereocenter independent of the particular conformation.
However, SD format is not as robust for cis/trans stereochemistry.  Isomeric SMILES
is the only common file format which allows complete specification of R/S
and cis/trans stereochemistry.  In fact, although **Flipper** does not
support higher orders of stereochemistry, the isomeric SMILES format is
capable of handling them.  For this reason, **Flipper** output is limited to SD
format (.sdf or .mol) and isomeric SMILES format (.ism). **OpenEye** OEBinary
format, like isomeric SMILES, is capable of fully specifying
stereochemistry; however, isomeric SMILES is more efficient for compounds
without any data beyond the title and connection table.

The **Flipper** process can
also be done with **OMEGA** using the `-flipper` flag.

Input Dimensionality
------------------------------------

**Flipper** is designed for use prior to 3D coordinate generation.  So 2D
or 1D (SMILES) input is normally expected.  Input files containing 3D
coordinates are handled, but the 3D coordinates are ignored and not
transferred to the output.

.. _section_flipper_usage:

======================
Example Commands
======================

Below are three example *flipper* executions.  Each example is followed by a
brief description of the parameter's effects.
Sample data files can be found in the data directory.

.. code-block:: bash

   flipper -in drugs.smi -out enumerated.ism

This execution will examine each stereocenter in *drugs.smi*.  If the
stereocenter does not have a specified stereochemistry, **Flipper** will
generate molecules with each of the stereochemistry states at each
stereocenter.

.. code-block:: bash

   flipper -in drugs.smi -out enumerated_forceflip.ism -forceflip true

This execution will differ from the first in that **all** stereocenters
will be enumerated, regardless of whether the stereochemistry is specified
in the input file.

.. code-block:: bash

   flipper -in drugs.smi -out enumerated_maxcenters6.ism -maxcenters 6

In this execution, **Flipper** will exhaustively enumerate all unspecified
stereocenters in molecules with up to six stereocenters.  For molecules with
more than six stereocenters, a random set of 64 isomers will be generated
from the larger set of potential stereoisomers.

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing **Flipper**
with the `--help` option.

.. code-block:: console

   flipper --help

will generate the following output:

::

   Help functions:
     flipper --help simple      : Get a list of simple parameters
     flipper --help all         : Get a complete list of parameters
     flipper --help defaults    : List the defaults for all parameters
     flipper --help <parameter> : Get detailed help on a parameter
     flipper --help html        : Create an HTML help file for this program
     flipper --help versions    : List the toolkits and versions used in the application

====================
Required Parameters
====================

.. option:: -in

   File containing one or more molecules for which stereoisomers will be generated.

====================
Optional Parameters
====================

.. option:: -out

   Output molecule file name. The output file format is limited to OEB, isomeric SMILES
   (*.ism* and *.smi*), or SD formats since these are the only formats which fully specify
   stereocenters without the need for three-dimensional coordinates.

.. option:: -enhstereo

   The `-enhstereo` string flag controls
   the behavior of **Flipper** with respect to enumeration of stereocenters
   in the presence of enhanced stereogroups.  When true, stereocenters in enhanced stereogroups are enumerated to
   retain relative stereo relationships between centers within a given stereogroup.
   [Default=false]

.. option:: -enumAtoms

   Enumerate atom stereocenters in a molecule according to the atom qualifier flags.
   [Default=true]

.. option:: -enumAtomSpecifiedStereo

   Modify atom stereocenters in a molecule. If *false*, only atoms which
   do not already have a specified stereochemistry would be enumerated.
   [Default=false]

.. option:: -enumBonds

   Enumerate bond stereocenters in a molecule according to the bond qualifier flags.
   [Default=true]

.. option:: -enumBondSpecifiedStereo

   Modify cis/trans bonds in a molecule. If *false*, only bonds which do
   not already have a specified parity would be enumerated.
   [Default=false]

.. option:: -enumBridgehead

   Enumerate bridgehead stereocenters.
   [Default=false]

.. option:: -enumEZ

   Enumerate E/Z stereocenters only.
   [Default=false]

.. option:: -enumNitrogen

   The `-enumNitrogen` string flag controls
   the behavior of **Flipper** with respect to enumeration of nonterminal
   nitrogens.  Any nitrogen with pyramidal geometry in the initial
   model of the input molecule, and having no more than two ring bonds
   is considered by **OMEGA** to be *invertible*.  **Flipper** will enumerate all
   possible puckers if the `-enumNitrogen` flag is set to *True*. [Default = False]
   [Aliases: -en]

.. option:: -enumRS

   Enumerate R/S stereocenters only.
   [Default=false]

.. option:: -enumRelativeAtomStereo

   Enumerate relative atom stereocenters in a molecule.
   [Default=false]

.. option:: -enumSpecifiedStereo

   This parameter forces **Flipper** to modify all of the
   stereocenters in a molecule.  If `-enumSpecifiedStereo` is false (the default),
   
   **FLIPPER**  only enumerates stereocenters which do not already have a specified
   stereochemistry.
   [Default=false]
   [Aliases=-forceflip]

.. option:: -maxCenters

   Obviously, the number of molecules generated by
   enumerating the stereocenters is :math:`2^N`, where `N` is the number of
   stereocenters.  In some instances, this may be larger than is desired.  The
   `-maxCenters` parameter indicates the maximum number of stereocenters
   which will be fully enumerated.  If a molecule has more than
   `-maxCenters` stereocenters, **Flipper** will randomly enumerate
   `2^(maxCenters)` instances from the full set of potential isomers.
   [Default=12]
   [Aliases=-maxcenters]

.. option:: -molNames

   Molecule names file corresponding to the input file.

.. option:: -prefix

   Prefix to use to name output files.

.. option:: -progress

   Type of progress to show on screen during run.

.. option:: -warts

   Add wart to title of each stereoisomer.
   [Default=false]




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: makefraglib

.. _chapter_makefraglib:

******************
MakeFragLib
******************

==================
Overview
==================

:ref:`MakeFragLib <chapter_makefraglib>` identifies, extracts, and generates conformers of
molecular fragments.  The model builder in **OMEGA** fragments input
molecules, retrieves corresponding fragment conformers, and assembles
them into a three dimensional structure.  Pregenerating fragment
conformers using **MakeFragLib** accelerates the model building
process.

The model builder in **OMEGA** attempts to capture all of the relevant
bond lengths, bond angles, and ring conformations for an input molecule.
Fragment assembly allows for a "divide and conquer" approach to model
building.  Much of the relevant information for building a molecular
model is contained in carefully chosen fragments.  :ref:`MakeFragLib <chapter_makefraglib>`
uses distance constraints and geometry optimization to generate
fragment conformations.  Only a single conformation is stored for
acyclic fragments, while all possible unique ring conformers are
retained within user defined limits.  Libraries created with
**MakeFragLib** can then be provided to **OMEGA** using the
`-setfraglib` or `-addfraglib` flags.

**MakeFragLib** can be used from the command line to generate ring
templates for use with **OMEGA** starting from only a collection of
molecules.  The output file from **MakeFragLib** can then be passed
directly into **OMEGA** using the `-setfraglib` or `-addfraglib`
flag.  Although fragment libraries may be concatenated using the Unix
'cat' command, this is not strictly necessary as multiple fragment
libraries may be specified as one argument to the flag.

.. _section_makefraglib_usage:

====================
Example Commands
====================

The following section shows several common command line executions of
:ref:`MakeFragLib <chapter_makefraglib>`.  Each example is followed by an explanation of what the
program will do.
Sample data files can be found in the data directory.

.. code-block:: bash

   prompt> makefraglib -in drugs.smi -out drugs_fraglib.oeb

All of the molecules in *drugs.smi* will be processed.  The set of all
unique fragments (according to **OMEGA** fragmentation rules) from all molecules in *drugs.smi* will be collected.

.. code-block:: bash

   prompt> makefraglib -in vendor.smi -out new_drugs_fraglib.oeb -ewindow 5.0

Conformers will be generated for all of the unique fragments found in
the user-supplied file *vendor.smi*.  An energy
window of 5 kcal above the global minimum conformer will be used to
accept or reject conformations of flexible ring systems.

===================
Command Line Help
===================

A description of the command line interface can be obtained by executing **MakeFragLib**
with the `--help` option.

.. code-block:: console
   
   > makefraglib --help

will generate the following output:

::

   Help functions:
     makefraglib --help simple      : Get a list of simple parameters
     makefraglib --help all         : Get a complete list of parameters
     makefraglib --help defaults    : List the defaults for all parameters
     makefraglib --help <parameter> : Get detailed help on a parameter
     makefraglib --help html        : Create an HTML help file for this program
     makefraglib --help versions    : List the toolkits and versions used in the application

======================
Required Parameters
======================

.. option:: -in

   File containing one or more molecules from which fragments will be generated.

.. option:: -out

   File to write fragments generated by **MakeFragLib**.  OEBinary format is required and gzipped OEBinary is recommended.

=======================
Optional Parameters
=======================

Execute Options
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -param

   The argument for this flag is the name of a
   file containing control parameters.  The control parameter file acts
   to either replace or augment the command line interface.  All
   parameters necessary for program execution may be provided in the
   control parameter file, although any command given explicitly on the
   command line will supersede options found in the parameter file.
   The application generates a new parameter file containing the full set of
   execution parameters upon every execution.  The name of the
   parameter file is created by combining the prefix
   base name with the *'.param'* extension.

.. option:: -mpi_np <n>

   Specifies the number of processors ``n`` when the application is run in MPI mode.

.. option:: -mpi_hostfile <filename>

   Specifies the name of the file containing processors configuration. For every host
   this file should contain a line ``host_name slots=n`` where ``n`` is the number of
   processors on the host.


File Options
==================

.. option:: -log

   The argument for this flag specifies the name of
   the log file.  The level of detail for logfile information can be
   altered using the :option:`-verbose` flag.  Generation of an
   output log may be disabled by providing ``nul`` as a argument in Windows and ``/dev/null`` as an
   argument on Linux and macOS.  
   [default = ``prefix`` _log.txt]

.. option:: -prefix

   The argument for this flag defines the prefix to be used
   for various information and data files generated.  Most
   important among these is the '*prefix_parm.txt*' file which includes a
   copy of all the parameters used in the run.  The prefix is
   also used to generate a default log file name if not explicitly
   specified with the *-log* flag. 
   [default = <app_name>].

.. option:: -verbose

   This is a boolean flag that controls the level of
   detail written to the log file.  By default only
   minimal information is written to the log file. 
   Verbose logging will cause more information to be written to the log
   file in order to follow behavior during program execution.  
   [default = false]

.. option:: -molNames

   This parameter takes a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set then only molecules in the
   input file(s) (see parameter :option:`-in`) with names that match those
   in the text files will be read in.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecule(s) that are contained in a large file, without
   having to extract those molecules by hand from the input molecules file.
   [default = NONE].

.. option:: -progress

   Show progress on screen.  Options are 'none', 'dots', 'log' and 'percent'.
   The 'dots' options will displays dots on screen to show molecules
   completed.  The 'log' option will duplicate the log file on screen.
   The 'percent' option will track progress through the input file.  
   [default = none]


3D Construction Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -buildff

   This flag sets the force field used for
   constructing fragments that are assembled to build an initial model
   of the input structure.  Consult the description of Force Fields
   (see :ref:`section_ForceFields`) for an explanation of appropriate
   arguments for this flag.  [Default=mmff94smod_NoEstat]
   [Aliases=**-bldff**,**-bldFF**]

.. option:: -fromCT

   This boolean flag determines whether *makefraglib* should
   generate an initial set of 3D coordinates using only the connection
   table of the input molecule.  Initial model generation is always
   necessary for molecule file formats devoid of coordinates (i.e.,
   SMILES).  Bond lengths and angles taken from molecule files
   containing coordinates may be retained by setting this flag to
   false.  [Default=true]
   [Aliases=**-fromct**]

.. option:: -ewindow
.. option:: -ewindowRing

   These flags set the energy window in accepting or rejecting
   fragment conformers.  Any fragment conformer that
   has a calculated strain energy less than the sum of the energy
   window and the energy of the global minimum fragment conformer will be
   accepted.  Conformers with strain energies above this threshold are
   rejected. [Default=4.0]

.. option:: -rms
.. option:: -rmsRing

   These flags set the minimum Root Mean Square
   (RMS) Cartesian distance below which two fragment conformers are duplicates.
   The RMS calculation is performed after superposition such that the
   true minimum distance between fragment conformers is calculated.  Lowering
   the value may cause **MakeFragLib** to generate ensembles that
   contain more fragment conformers of a similar shape.  Higher
   values may result in smaller, yet possibly more shape
   diverse ensembles.  [Default=0.1]

.. option:: -startfact
.. option:: -startfactRing

   Factor for determining number of random starting geometries when 
   generating fragments. Legal values are from 1 to 100. [Default=2, 20]

.. option:: -fragGen
.. option:: -fragGenRing

   Maximum Number of conformers to be generated with distance geometry 
   for each fragment. [Default=40, 50000]

.. option:: -fragKeep
.. option:: -fragKeepRing

   Maximum Number of conformers to be kept for each fragment. 
   [Default=1, 1024]

.. option:: -timeLimit
.. option:: -timeLimitRing

   Maximum time in sec allowed for each fragment generation. 
   [Default=300]

.. option:: -maxtime

   Maximum time (s) allowed for fragment conformer search.
   [Default=300.0]
   [Aliases=**-maxsearchtime**]



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_oebtosdconf:

******************
Oeb2SdConf
******************

**Oeb2SdConf** is a utility that allows **OMEGA**-generated conformers to be used with the MOE program.
Please contact Chemical Computing Group support if you require assistance with this utility.



.. _section_omega_theory:

Theory
======

.. toctree::
   :maxdepth: 2

   omega_overview
   filter_theory



.. _section_omega_overview:

OMEGA Overview
==============

**OMEGA** is a fast, systematic conformer generator that produces high-quality 3D conformations
of drug-like molecules. Conformation generation is a foundational step in many molecular modeling
workflows because the biologically relevant properties of a molecule and the interactions with its
environment depend on the accessible three-dimensional shapes it can adopt. **OMEGA** generates conformer
ensembles rapidly while maintaining accuracy, affordability, robustness across diverse chemical space, and utility
for downstream applications.

.. figure:: /_images/objectives_of_omega.png
   :align: center
   :alt: Diagram highlighting the main goals of OMEGA.

   **Figure 1.** Key objectives of the **OMEGA** conformer generator: speed, accuracy, and broad coverage of chemical space.

Two Approaches to Conformer Generation
---------------------------------------

**OMEGA** uses two main approaches to generate 3D conformers based on the topology of the input molecule.

- **Torsion Driving (TD):** Used for linear molecules with only small rings. This method samples
  the torsional degrees of freedom along rotatable bonds, making it fast and effective at covering
  the conformational space of typical drug-like molecules.

- **Distance Geometry (DG):** Used for macrocycles, which are molecules with large rings. In this approach, atoms and rigid
  fragments are placed randomly in Cartesian space, then an error function is minimized to satisfy
  distance constraints derived from MMFF94 force field parameters, followed by force field refinement.
  This approach is general and provides thorough conformational coverage, making it especially suited
  for macrocycles where torsion driving cannot be applied.
  
.. figure:: /_images/two_approaches_of_omega.png
   :align: center
   :alt: Flowchart contrasting the conformer generation paths for macrocycles and nonmacrocyclic molecules.

   **Figure 2.** Overview of the two conformer generation approaches in **OMEGA**: distance geometry for macrocycles and torsion driving for linear molecules.

.. _chapter_omegatheory:


Torsion Driving (TD) in OMEGA
-----------------------------

The torsion driving (TD) algorithm of **OMEGA** is composed of two main
components; building the molecular scaffold (model) from non-rotor fragments and
sampling the torsional degrees of freedom.
Model generation may be bypassed by importing fragment structures from
external sources ([Hawkins-2010]_; [Hawkins-2012]_).

**OMEGA** builds initial structures for the molecule by assembling fragment
templates along sigma bonds.  Input molecules' graphs are fragmented at
exocyclic sigma, and carbon to heteroatom acyclic (but not exocyclic)
sigma bonds.  Conformations for the fragments are either retrieved
from pregenerated libraries built with :ref:`MakeFraglib <chapter_makefraglib>` or
constructed on-the-fly using the same approach
that :ref:`MakeFraglib <chapter_makefraglib>` uses.  Molecule
assembly is accomplished by simple vector alignment since all
interfragment joints are along sigma bonds.

Once an initial structure is constructed or given as
input, **OMEGA** generates additional ones enumerating ring
conformations and invertible nitrogen atoms.  Ring conformations are
taken from the same fragment library used to build the initial model.
**OMEGA** detaches all exocyclic substituents from a ring system, then aligns
and attaches them relative to the new ring conformation.  **OMEGA**
attempts to generate every possible combination of ring conformations
possible for a given structure.  

The next step in model generation is to detect and enumerate
invertible nitrogens.  Nitrogens that have pyramidal geometry, no specified
stereochemistry, no more than one hydrogen, are three
valent, and have no more than three ring bonds are considered by **OMEGA**
to be invertible.  Invertible in this context simply means that at
room temperature a pyramidal nitrogen is likely to be able to rapidly
(on an NMR timescale) interconvert between two puckered forms.  All
multiconformer ring models are further expanded by enumerating all
possible nitrogen puckers.  The resulting model set is the starting
point for conformer search by torsion driving.

**OMEGA** begins the torsion search process by examining the molecular
graph and determining the bonds that may freely rotate.  By default, **OMEGA**
selects acyclic sigma bonds that have at least one non-hydrogen atom
attached to each end of the bond.  By default, hydrogen rotors (e.g., hydroxyl
groups) are not altered during the torsion search; however, this can be enabled.
The final ensemble selection is based on
RMS distance of heavy atoms and sampled hydrogen atoms; unsampled hydrogen atoms
do not affect this RMS distance. A list of
possible dihedral angles are then assigned to each rotatable bond.
The current mechanism for assignment is based on SMARTS matching,
although alternate strategies for assigning angles based on
experimental (i.e., X-ray) or theoretical (i.e., fragment optimization
studies) are possible.  The molecular graph is then subjected to
pattern and geometric symmetry detection.  Common patterns such as
para-disubstituted benzene are used to reduce the number of symmetry
equivalent dihedral angles that need to be searched.  All torsions are
altered by 120 and 180 degrees, and an RMS calculation is performed,
taking into account symmetry-equivalent atoms in order to detect two-
and three-fold symmetries. Once a set of nonredundant dihedral angles is
assigned to each rotatable bond, **OMEGA** samples the torsion space through
a systematic enumeration of combinations of these angles. Depending on the
flexibility of the molecule, the maximum number of conformers to be
generated, and the mode in which **OMEGA** is run, the algorithm to sample
the torsion space is decided. By default, Thompson sampling, a Bayesian reinforcement
learning algorithm, is used.
The best conformers identified in the torsion search
are rank-ordered by energy. A
final ensemble is selected by sequentially testing the conformers
using the RMS distance cutoff. To be accepted into the final
ensemble, a conformer must have an RMS distance to every other member
of the ensemble that exceeds the user-defined cutoff value.  The final
ensemble is populated up to the user-defined maximum ensemble size
limit, or until the list of low energy conformers is exhausted.

.. figure:: /_images/steps_in_tordrive.png
   :align: center
   :alt: Three-step TD workflow: generate initial models, sample conformer space using rotatable bond torsions, then prune and keep low-energy diverse conformers.

   **Figure 1.** Illustration of steps in torsion driving **OMEGA**.

Thompson Sampling in OMEGA
--------------------------
The torsion library provides a set of likely dihedral angles for each rotatable bond.
In Thompson sampling for torsion driving, we use these angles from the torsion rules as
priors for a Bayesian process. Instead of enumerating every possible
combination of angles and searching the combinatorially expanding space of conformers,
conformers are instead generated based on these priors.
For every angle for a given rotatable bond, a distribution of beliefs is maintained
for modeling the likelihood of that angle to be part of a new low strain conformer. We sample these
distributions to pick an angle for a given rotor. This process is repeated for every
rotatable bond to pick a combination of angles that defines a conformer.
After a conformer is generated, its energy is evaluated and the beliefs are updated
based on the result. As we generate more conformers while continuously updating the beliefs,
the sampling process is steered toward the low-strain structures of interest.

.. figure:: /_images/TSinOMEGA_cartoon.png
   :align: center
   :alt: Conceptual loop diagram of iterative torsion sampling, conformer scoring, and probability updates that favor unique, low-strain structures.

   **Figure 2.** Illustration of Thompson sampling algorithm in torsion driving **OMEGA**.

.. note::

   Conformers generated from **OMEGA** with default options do not maintain
   input relative stereochemistry, that is, cis/trans configurations for cyclohexane or other
   cyclic molecules.



.. _section_omega_modes:


OMEGA Sampling Modes
--------------------

**OMEGA** provides a set of predefined sampling modes, each tuned for a specific downstream
application. Selecting the right mode ensures that the output ensemble is appropriately sized and
shaped for the intended use case: not too sparse to miss binding-relevant geometries, but
not so dense as to be computationally unaffordable in the downstream step.
All modes except ``macrocycle`` (see the :ref:`Macrocycle Conformations section <section_macrocycle>`)
share the same underlying torsion driving (TD)
algorithm described in :ref:`Torsion Driving in Omega <chapter_omegatheory>`, but they differ in the default values of key
parameters such as the maximum number of conformers, energy window, and RMS pruning threshold.

.. figure:: /_images/modes_in_omega.png
   :align: center
   :alt: OMEGA sampling modes and relative sampling depth for downstream applications; see text for details.


   **Figure 1.** The torsion driving sampling modes in **OMEGA**.


The ``classic`` mode is the default mode. This allows a maximum of 200 conformations for a molecule.
These conformers represent a gas-phase ensemble. The  ``fastrocs``  and ``rocs`` modes are tailored toward
effective use in shape-based virtual screening applications: **FastROCS** and **ROCS**, with a
maximum of 10 and 50 conformations, respectively. The ``pose`` mode is designed for docking
with **OEDocking** (FRED/HYBRID) and allows up to 800 conformations for molecules with eight or more rotors.
The ``dense`` mode is designed for free-energy or solvation calculations with **Freeform** and generates
large ensembles (up to 20,000 conformations) with a tight RMS pruning threshold and a wide energy window
to provide thorough coverage of accessible conformational space.


Each of these modes not only has its own set of default parameters for ensemble slicing that are 
optimized for the intended downstream application, but the Thompson sampling strategy is also tailored 
for each mode, based on the typical flexibility of the molecule and the maximum number of conformers generated in that mode.


Choosing a Mode
^^^^^^^^^^^^^^^

The table below summarizes the recommended mode for common downstream applications:

.. list-table::
   :header-rows: 1
   :widths: 25 35 80

   * - Mode
     - Downstream Application
     - Key Characteristic
   * - ``classic``
     - General purpose
     - Gas-phase ensemble with balanced defaults
   * - ``fastrocs``
     - FastROCS GPU screening
     - Compact ensemble (up to 10 confs)
   * - ``rocs``
     - ROCS shape screening
     - Moderately sized, representative ensemble (up to 50 confs)
   * - ``pose``
     - OEDocking (FRED/HYBRID)
     - Wide energy window for bioactive conformers, up to 800 confs for flexible molecules
   * - ``dense``
     - Freeform free energy
     - Very dense ensemble with solvation scoring


.. _section_macrocycle:


Macrocycle Conformations
------------------------

Torsion driving conformational sampling methods such as described in the
:ref:`chapter_omegatheory` section often perform poorly
for macrocyclic molecules due to the problem of ring closure after the torsion driving step. 
Conformational sampling of macrocycles therefore requires a different approach;
we address this issue with **OMEGA** using distance geometry (DG) [Hawkins-2020]_. Other methods have been applied to this
problem, such as distance geometry (DG) [Crippen-1988]_, molecular dynamics (MD/LLMOD) [Watts-2014]_,
MD with perturbation along low energy eigenvectors [Labute-2010]_, and inverse kinematics
[Coutsias-2016]_. It is important to note that **OMEGA** DG also works well for very flexible linear molecules which have
such a large conformational space that torsion driving may not be able to adequately sample it.

**OMEGA**'s method of conformational sampling of macrocycles is an adaptation of the distance geometry method 
of Spellmeyer et al. [Spellmeyer-1997]_. In this method, a traditional embedding DG algorithm is replaced
with a direct error function minimization of the random atomic coordinates, followed by force field 
refinement. Each initial Cartesian atomic coordinate *x* is assigned by choosing a random number *r* 
between *-1* and *1*, multiplied by a factor :math:`f\sqrt{N}` which determines the box of maximum extent 
for a molecule with *N* atoms:

.. math:: x = f\sqrt{N}r
   :label: eqtnext

Alternatively, instead of randomly placing atoms in Cartesian space, the method allows for random
placement of rigid fragments such as aromatic rings, nitro groups, and so on. After randomly
placing molecules, atoms, or rigid fragments, an error function of the form:

.. math:: F = \sum_{i,j} (d_{ij}-c_{i,j})^2 + \sum_k V_k
   :label: eqtnerror

is optimized. In the above equation, the first sum runs over all pairs of atoms in the molecule,
where :math:`d_{ij}` are the interatomic distances and :math:`c_{ij}` are elements of the constraint matrix;
they are obtained from the MMFF94 force field parameters. When atoms *(i,j)* are
bonded or are the first and last atoms in a bond angle, the upper and lower bounds
are the same and are taken as the corresponding equilibrium force field distances. When
atoms *(i,j)* are the first and last atoms of a torsion angle, the lower bound corresponds to the cis configuration and
the upper bound to the trans configuration of those atoms. Finally, when atoms *(i,j)* are separated
by more than three bonds, the lower bound is taken as the sum of the vdW radii and the upper
bound as the sum of bond lengths which separate the pair. The second summation in
equation :eq:`eqtnerror` is over the tetrahedral constraints which result from:


1. planarity

2. chirality

3. cis-trans isomerism

Optimization of the error function :eq:`eqtnerror` leads to a rough conformation. No hydrogen atoms
except those which are bonded to chiral atoms are included in the error function minimization.
Each rough conformation is checked for chirality correctness before refinement. 
If the rough conformation passes the chirality checks, it is refined against a forcefield, MMFF94
([Halgren-I-1996]_, [Halgren-II-1996]_, [Halgren-III-1996]_, [Halgren-IV-1996]_, [Halgren-V-1996]_).
Solvent forces can be included in the refinement step using a simple continuum
solvation model (the Sheffield model [Grant-2007]_). When the sequence of random
placement followed by error function minimization and force field refinement is repeated for a large enough
number of times for a given macrocycle, its conformational space is reasonably well covered.

Special measures are taken for zwitterionic molecules (containing both positively and negatively
charged groups, such as :math:`CO_2^-` and :math:`NH_3^+`). In order to prevent possible Coulombic collapse
in the absence of a stabilizing receptor, zwitterionic molecules are neutralized before performing 
the distance geometry calculation and the refined structures are recharged before writing them out. 
This approach meaningfully improves **OMEGA**’s ability to reproduce solid-state conformations of
zwitterionic ligands.

This method of conformation sampling is completely general and can be used to generate conformations
for any molecule, whether or not it contains a large ring. However the ``macrocycle`` mode in **OMEGA** has
been specifically developed and parameterized to perform well on macrocycles, therefore its performance
on linear and small ring molecules is worse than with ``classic`` **OMEGA**.




.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _filter_theory:

###################
Filtering Theory
###################

.. _section_filter_theory:

****************
Introduction
****************

Filtering attempts to eliminate inappropriate or undesirable compounds
from a large set before beginning to use them in modeling studies.
The goal is to remove all of the compounds that should not be
suggested to a medicinal chemist as a potential hit. This exercise is
obviously case dependent, depending on ease of the assay, intended
target, needs of the user, and so on.

To match this need, the default filter encapsulates many of the
standard filtering principles, such as removal of unstable, reactive,
and toxic moieties. In addition, |product| allows the customization of
the filtering criteria to fit specific needs.

The criteria for passing or failing a given molecule fall into three categories.

.. _filter_theory_physical_properties:

* Physical properties

    - Molecular weight

    - Topological polar surface area (TPSA)

    - logP

    - Bioavailability


* Atomic and functional group content

    - Absolute and relative content of heteroatoms

    - Limits on a very wide variety of functional groups

* Molecular graph topology

    - Number and size of ring systems

    - Flexibility of the molecule

    - Size and shape of non-ring chains

All of the data generated in filtering molecules can be written to a
tab-separated file for easy import into a spreadsheet. This functionality
allows for combining the values dynamically for a variety of purposes,
including, but not limited to, determining which filter values best fit
each project's needs.

History
=========

When OpenEye's work on filtering technology began in 2000, it was
designed simply to remove compounds with reactive or otherwise
undesirable functional groups. Over the years, the understanding of
lead-like and drug-like compound selection has advanced. In addition,
with the publication of Lipinski's "Rule of 5" [Lipinski-1997]_, more
and more pharmacokinetic properties have appeared earlier in the
virtual screening process.

In addition to providing basic functional group selection, the
technology is a one-stop database preparation tool aimed at generating
databases suitable for high-throughput virtual screening. The following are some components of this tool.

* Cheminformatics quality control

  - Valence-state validation

  - Aromaticity perception

  - Implicit hydrogen perception

  - Bond-order perception

* Database preparation

  - Setting pKa states

  - Applying normalizations (tautomers and dative or hypervalent states)

* Compound selection

  - Physical properties (see :ref:`above <filter_theory_physical_properties>`)

  - Assay counter-indicators (aggregators and dyes)

  - Promiscuous actives [Baell-2010]_

  - PK ([Martin-2005]_, [Veber-2002]_, [Egan-2000]_, [Lipinski-1997]_)


Finally, it should be pointed out that in the virtual screening world,
time is of the essence. Algorithms for preliminary database
preparation should not take large amounts of time. Because of this,
all the calculations included are 2D or graph-based algorithms. While
this does occasionally limit the technology, it allows for the delivery
of a product that is appropriate for the task of virtual-screening
database preparation.

.. _filter_theory_rant:

A Detailed Examination of False Positives and False Negatives
===============================================================

Nearly every computational tool used in early drug discovery yields
statistically predictive, rather than absolutely definitive results.
In nearly every case, prudence demands that one consider the causes of
false positives and false negatives and make an attempt to optimize
the area under the receiver-operator curve (ROC) for the computational
tool.  However, there are well-known methods for improving statistical
predictions of this nature that are independent of the absolute
false-positive and false-negative rates.  These methods include
filtering the population to which a test will be applied.  By applying
a test to smaller populations that only contain molecules appropriate
for the specific application at hand, the negative impact of the
false-positive rate on the predictive results can be dramatically
improved.

A familiar example from the medical world will serve to illustrate
this principle.  Assume we have a test for the presence of the new
*foo virus* which has an exceptional ROC curve with false-positive
and false-negative values (1/1,000 and 1/1,000 respectively).  Let us
assume that the *foo syndrome*, caused by the *foo virus*, affects 1
person in 20,000.  If we gave this test to 100,000 people from the
general population, we would expect 5 to actually have the *foo
syndrome*.  With this test, there is only a 0.05% percent chance that
any of them would not be detected (that is, be a false negative).
However, we would expect there to be 100 false-positive test results.
Thus of the 105 total positive test results, only 4.8% would actually
have the *foo syndrome* (positive predictive value = 4.8%).

.. list-table:: Confusion table for the **unfiltered** *foo virus* test (prevalence 1 in 20,000)
   :widths: 9 13 13 20
   :header-rows: 1
   :stub-columns: 1

   * -
     - Actual Positive
     - Actual Negative
     -
   * - Predicted Positive
     - True Positives = 5
     - False Positives = 100
     - Positive Predictive Value = 4.8%
   * - Predicted Negative
     - False Negatives = 0
     - True Negatives = 99,895
     -

Alternatively, we could start by using very simple screening before
applying the test.  We first eliminate people who do not have any risk
factors for contracting the *foo virus*.  Next, we may eliminate people
whose blood is incompatible with the test for the *foo virus*.  Further,
we may want to eliminate people who acknowledge that they will refuse
treatment for the *foo virus* even if we determine that they do have it.
By these admittedly simple screens, we apply the test for the *foo
virus* to a much smaller group with a decidedly higher prevalence of
the virus.  For instance, after the filtering, we may be left with a
group of only 1,000 people who have a 1 in 200 chance of having the
syndrome.  Now, we still have the same five people who actually have
the disease, but we only expect one false-positive test.  Now
there are six total positive tests, and 83% of them actually have the
syndrome!  This is reflected in a much more reasonable (83%) positive
predictive value.

.. list-table:: Confusion table for the **filtered** *foo virus* test (prevalence 1 in 200)
   :widths: 9 13 13 20
   :header-rows: 1
   :stub-columns: 1

   * -
     - Actual Positive
     - Actual Negative
     -
   * - Predicted Positive
     - True Positives = 5
     - False Positives = 1
     - Positive Predictive Value = 83%
   * - Predicted Negative
     - False Negatives = 0
     - True Negatives = 994
     -

Returning to drug design, in a
ligand-based design tool such as **ROCS**, we can posit that the
receiver-operator curve may have a false positive rate as low as 1
in 10,000.  For this exercise, assume no false negatives.  When
using that to identify 50 inhibitors from a database of 2.5 million
available compounds, we would identify 300 potential inhibitors, and 5 out
of every 6 of these would be a false positive (positive predictive
value of 17%). However, running ``filter`` first would eliminate 65% of the 2.5
million compounds, leaving 875,000 compounds to run
through **ROCS**.  There will be approximately 88 false positives along with the
50 true positives increasing the positive predictive value more than
two-fold with relatively little work.

.. list-table:: Confusion table for the **unfiltered** ROCS virtual screen
   :widths: 9 13 13 20
   :header-rows: 1
   :stub-columns: 1

   * -
     - Actual Positive
     - Actual Negative
     -
   * - Predicted Positive
     - True Positives = 50
     - False Positives = 250
     - Positive Predictive Value = 17%
   * - Predicted Negative
     - False Negatives = 0
     - True Negatives = 2,499,700
     -

.. list-table:: Confusion table for the **filtered** ROCS virtual screen
   :widths: 9 13 13 20
   :header-rows: 1
   :stub-columns: 1

   * -
     - Actual Positive
     - Actual Negative
     -
   * - Predicted Positive
     - True Positives = 50
     - False Positives = 88
     - Positive Predictive Value = 36%
   * - Predicted Negative
     - False Negatives = 0
     - True Negatives = 874,862
     -


Filtering Principles
==============================================

The same principle of increasing the positive predictive value by removing
obvious true negatives applies to screening for lead candidates,
regardless of whether it is virtual screening or high-throughput
screening (HTS).  While both are reasonable screens, each can be plagued by
very low positive predictive values (despite low false-positive
rates), particularly when applied to all available compounds or large
virtual libraries.  Simple filtering techniques focus the set of
compounds passed on to more computationally intensive screening
methods.

The first approach is to filter based on :ref:`functional
groups <molprops_functional_groups>`. Generally speaking, there are
toxic and reactive functional groups that should be removed from consideration,
such as alkyl bromides or metals. There are also functional
groups that are not strictly forbidden, but are undesirable in large
quantities. For instance, parafluorobenzene or trifluoromethyl have
specific purposes, but heavily fluorinated molecules can be
eliminated.

Beyond simple functional group filtering, both simple
and complex physical properties can be used to characterize the
kinds of compounds to keep or to
eliminate. These properties attempt to consider drug-like qualities, such
as bioavailability, solubility, toxicity, and synthetic accessibility,
even before the primary high-throughput or virtual screening, which
are primarily geared toward detecting potency alone. The best known
physical property filters is :ref:`Lipinski's "rule-of-five"
<molprops_lipinski>`, which focuses on bioavailability
[Lipinski-1997]_. However, many other physical properties, such
as :ref:`solubility <molprops_logs>`, :ref:`atomic content
<filter_process_metal_removal>`, :ref:`ring structures
<molprops_structural_and_chemical_features>`, and :ref:`surface area
ratios <molprops_polar_surface_area>` can also be
considered. |product| provides algorithms for calculating many of
these properties and applying them with filters based on literature
studies.

Finally, types of compounds that can be
troublesome at later stages should be eliminated. For instance,
Shoichet's :ref:`aggregating compounds <molprops_aggregators>` often
produce false positives that can waste enormous resources if they are
identified by virtual or HTS ([McGovern-2003]_;
[Seidler-2003]_). Similarly, :ref:`dyes <molprops_dyes>` can appear to
be inhibitors by interfering with colorimetric or fluorometric assays
or by nonspecific binding to the target protein.

.. _filter_theory_variations_of_filters:

Variations of Filters
==============================================

Different types of filters are appropriate under different
circumstances.  Very early in a project, when little or no information
on the structure-activity relationship (SAR) is
available, very strict drug-like filters can be applied.  This
avoids spending chemistry resources to pursue
difficult compounds that may not be modifiable for
appropriate properties. However, when considering compounds to
purchase for HTS, different filters can be applied. Oprea et al.
pointed out that the best molecules for initial HTS are smaller and have
less functionality than drugs but show some activity
[Oprea-2000]_. Therefore, strict lead-like filters can be applied to
ensure that hits identified from HTS can be investigated for potential
leads, especially those that may be larger or more highly functionalized.
However, when SAR suggests that particular compounds or series
may yield valuable information, filtering criteria can be loosened,
because secondary screens can be effective in detecting useful
compounds. Circling back to the medical analogy, this is a case
where an improved primary screen with a dramatically improved
false-positive rate (e.g., 1 in 100,000) can be applied to a
larger population without detrimental effects on the positive-predictive
value.

|product| provides the following filters:

* **BlockBuster**: The BlockBuster filter is based on 141 best-selling, non-antibiotic
  prescription drugs. We designed the physical property portion of the filter
  so that it passes all of the compounds. The physical property values in this
  filter are quite good. However, the functional group filters in this
  filter may be too restrictive because 141 compounds will not span all acceptable functionality.
* Drug: The original drug filter
  is provided as well [Oprea-2000]_, but has been shown to be very restrictive.
  The BlockBuster filter was developed as an alternative.
* Fragment: The fragment filter is designed specifically to filter molecules with attachment points. This filter
  is used inside **CHOMP** to restrict the fragments generated for the **BROOD** database.
* Lead: The Lead filter corresponds to the Oprea
  lead-like filters that are useful for preparing HTS screening databases.
* PAINS: The PAINS filter is based on work by Baell which describes identification
  and filtering of promiscuous (nonspecific) actives across a number of screening
  types and targets [Baell-2010]_.  Unlike the other filter types, the PAINS filter
  consists of only functional group filters; no physical property filters are
  included.  In practice, combination of the PAINS filter with
  a user-defined set of physical property filters may be desirable.

.. hint::

   We recommend the default BlockBuster filter for most
   purposes. If you have specific filtering needs or are unsatisfied with the
   results, please see the :ref:`filter file<filter_files>`.

   If you modify the :ref:`filter file<filter_files>`, the
   depictions found in the :ref:`functional_group_rules` section can be
   particularly helpful in determining which functional groups are
   indicated by each name in the file.

Accumulation of Rules
======================

**FILTER** contains rules to judge the quality of molecules on various properties.
Individually, each of these rules
seems quite reasonable and even profitable. However, when each
molecule is tested against hundreds of individual filters, the
fraction of molecules that pass all the filters can be surprisingly
small. Sometimes less than 50% of vendor databases pass the
filters. If this is unacceptable, we recommend you examine the
predicted aggregator, solubility, and Veber filters. In our
experience, these are the most common failures. The best method of
investigating failures is looking at the filter log.

The BlockBuster filter addresses these challenges. Sometimes the range needs to be expanded
in order to allow more compounds to pass.
For each value, its properties extend from the 2.5th percentile to the 97.5th percentile. The differences
between the original BlockBuster filter and the adjusted filter are both
in reasonable ranges. For instance, the full range of molecular weights for
the BlockBuster filter spans 130 to 781, while the 2.5th percentile is 145
and the 97.5th percentile is 570. Surprisingly, when the
reduced filter is used, only 75 of the 141 original molecules pass the filter!
This demonstrates how slight changes to many filters can lead to a
significant reduction in the number of compounds that pass all filters.

The opposite approach of allowing everything to pass can be
equally challenging. For example, a filter was designed around the
"small molecule drug" file available from the DrugBank `website
<http://redpoll.pharmacy.ualberta.ca/drugbank>`_. In order to pass
all of these molecules, including some that would no longer be
acceptable, many of the individual filters
must be set to unreasonable values, such as a molecular weight
range from 30 to 1500 and a heteroatom count range from 1 to 60.

.. hint::

   Because every project is different, we recommend that you
   inspect each :ref:`filter file<filter_files>`. The depictions found in the
   :ref:`functional_group_rules` section can be particularly helpful
   in discerning what functional groups are desirable and undesirable.


.. _filter_process:

*********************
Filter Preprocessing
*********************

Before the application of any :ref:`molecular property filters
<molprops>`, a preprocessing step may be used to alter the molecule
significantly to fit the criteria needed for most modeling
applications. This filter preprocessing step is applied to each molecule
in a series of stages in the following order:

#. :ref:`filter_process_metal_removal`
#. :ref:`filter_process_salt_removal`
#. :ref:`filter_process_canonicalization`
#. :ref:`filter_process_pka_normalization`
#. :ref:`filter_process_normalization`
#. :ref:`filter_process_reagent_selection`
#. :ref:`filter_process_type_checking`
#. :ref:`filter_process_mmff_checking`

.. _filter_process_metal_removal:

Metal Removal
==============

Metal removal is the first stage of element-based filtering. This
stage removes specified metal complexes from the molecule.
It will not reject a molecule with a metal complex. This allows
the filter to treat atoms in the counterion portion of a molecule
separately from the atoms in the primary portion of the molecular
record.

For instance, organic molecules that are complexed with
silver can be eliminated based on their metal chelate even though they
themselves are acceptable, while at the same time eliminating a
sulfate counterion from another molecule before it leads to
elimination of the acceptable cationic molecule.

.. seealso:: 

   :ref:`filter_files_elemental_filters`

.. _filter_process_salt_removal:

Salt Removal
=============

This step deletes all atoms that are not part of the largest connected
component of a compound. This effectively eliminates all
non-covalently bound portions of the compound.


.. _filter_process_canonicalization:

Canonicalization
================

This step canonicalizes the atom and bond order of the portion of the
molecule that remains after the previous removal steps. This is
necessary to avoid different atom orderings producing slightly
different normalizations in the following normalization
steps. 

.. _filter_process_pka_normalization:

pKa Normalization
==================

pKa normalization uses a rule-based system to set the ionization state of input
molecules. If pKa normalization is turned on, the molecule is set to
its most energetically favorable ionization state for pH=7.4. The
rule-based nature of this calculation allows it to be very
fast. Furthermore, despite being rule-based, this approach takes into
account many secondary charge interactions.

While more advanced levels of theory can be found for predicting
ionization states, this method is very well suited to
virtual-screening database preparation. However, this may not be
appropriate for hit-to-lead or lead optimization.


.. _filter_process_normalization:

Normalization
=============

In addition to :ref:`pKa normalization<filter_process_pka_normalization>`, |product|
allows any number of additional molecular normalizations. Since
normalizations are usually specific to a particular company or
site, |product| provides the ability for users to input
normalizations, such as the nitro tautomer state, but does not provide
default implementations.


.. _filter_process_reagent_selection:

Reagent Selection
=================

Reagent selection for small linear library synthesis or large
combinatorial library synthesis is usually a necessary task. A user hoping to identify a
set of acyl-halide reagents could specify a selection parameter to
require each compound to have exactly one acyl-halide. In addition,
the filter could be modified to exclude functional groups
(such as primary amines) that may be acceptable for typical lead-like
molecules, but are not acceptable for the specific reagent the user has
in mind.

Therefore, the selection parameter is the reverse of a filtering
parameter. The molecule *must include* the given substructure in order
to pass the filter.

.. seealso::
   
   The :ref:`select parameter<filter_files_selection>` in filter files. 


.. _filter_process_type_checking:

Type Checking
==============

This checks the valence state and formal charge of the entire
molecule. The check identifies molecules that are poorly specified, or
represent nonsensical chemical states, often from corrupt input data.
For example, an oxygen with eight hydrogens attached or a carbon with
a +9 formal charge would be rejected.

.. _filter_process_mmff_checking:

MMFF94 Atom Type Checking
==========================

This checks that all atoms in the molecule have valid MMFF94 atom type
assignments.  The check identifies molecules that will fail downstream
processing that depends on MMFF94 atom types (e.g., **Omega**).



.. _molprops:

*************************************
Molecular Properties and Predictors
*************************************

|product| provides a range of properties to predictors to be used as
molecular filters. Molecular properties are distinct physical
properties that can be measured, including the following:

* :ref:`molprops_structural_and_chemical_features`
* :ref:`molprops_functional_groups`

There have been several attempts to develop fast-approximate QSAR
models for bioavailability. The first of these
was :ref:`Lipinski's work <molprops_lipinski>` [Lipinski-1997]_,
followed by work at Pharmacopia [Egan-2000]_, Abbott
[Martin-2005]_, and GSK [Veber-2002]_. The simplest and probably most
trusted work includes studies of
:ref:`LogP <molprops_logp>` and :ref:`PSA <molprops_polar_surface_area>` used
by Egan. Martin's Abbott
Bioavailability Score (ABS) appears to be a refinement of the first
generation models and is designed specifically to categorize a
molecule's probability of having a bioavailability >10% in rats.

.. seealso::

   The :ref:`filter_files_pharmacokinetic_predictors` section in the Filter
   Files chapter.

.. _molprops_structural_and_chemical_features:

Structural and Chemical Features
================================

A number of important structural and chemical features of
molecules should be limited for virtual screening. The following
simple measures are provided as filterable properties:

* Molecular weight
* Ring count
* Ring-system size
* Size of non-ring structures
* Length of unbranched chains
* Heteroatom fraction
* Halide fraction
* Formal charges
* Rotatable bonds

MolProp TK also includes slightly more complex algorithms for hydrogen bond donors and
acceptors as well as chiral centers.

.. seealso::

   The :ref:`filter_files_basic_properties` section in the Filter Files chapter.


.. _molprops_functional_groups:

Functional Groups
==================

Functional group removal remains at the heart of the **FILTER** algorithm.
Functional groups fall into several categories, including:

* Reactive or labile groups
* Undesirable groups
* Generally acceptable groups
* Protecting groups
* User-derived groups

Reasonable defaults are provided for each functional group in
the above categories, with the filter files being designed as basic guides.
They can be tailored for each user's particular needs.
Examining the filter file can provide useful information.
Developing a custom filter for a specific task is
strongly encouraged.

.. seealso::

   The filter files contain only functional group names. For
   clarification of the definitions, please refer to
   the :ref:`functional_group_rules` section for complete descriptions.

.. _molprops_dyes:

Dyes
==================

In the past, colored
molecules interfered with many high-throughput assays.
While assay technology continues to advance and this problem has decreased,
most dyes are not commonly carried forward in
lead development projects. Therefore, a pattern-based filter for dye
molecules is included. While these patterns occasionally identify molecules
that are considered acceptable by some users, in general, they identify
molecules that the majority of chemists would rather not see at the top
of their virtual screening hit lists.

.. _molprops_logp:

LogP
==================

The XLOGP algorithm ([Wang-R-1997]_) is provided because its atom type
contribution allows calculation of the XLogP contribution of any
fragment in a molecule and allows minimal corrections in a simple
additive form to calculate the LogP of any molecule made from
combinations of fragments. Further, although the method contains
many free parameters, its simple linear form allows for ready
interpretation of the model, and most of the parameters in the model
make rational sense.

Unfortunately, the original algorithm is difficult to implement as
published. First, the internal hydrogen bond term was calculated using
a single 3D conformation, which was found to be both arbitrary
and unnecessary. This arbitrary 3D calculation has been replaced with
a 2D approach to recognize common internal hydrogen bonds. In tests,
the 2D method worked comparably to the published 3D algorithm. Next,
the training set had a few subtle atom-type inconsistencies.

Both of these problems were corrected and refit to the original XLOGP
training data. This implementation gives results that are quite
similar to the original XLOGP algorithm, so it is called OEXLogP to
distinguish it from the original method.

.. seealso::

   * The :ref:`XLogP parameter<filter_files_xlogp>` in the Filter Files chapter.

.. _molprops_logs:

LogS
==================

The work of Samuel Yalkowsky [Yalkowsky-1980]_ at the University of Arizona has resulted in what is now
called the "generalized solvation equation." It states that the
solubility of a compound can be broken into two steps, first the
melting from the pure solid to pure liquid, and second, the phase
transfer from pure liquid into water. For many small organic
molecules, this second step is somewhat related to LogP.

Because of this relationship, we explored the use of the XLogP
atom types in solubility prediction, with the goal of providing an approximate though robust and fast method for
calculating solubility. We fit the XLogP atom types to a training set
of nearly 1000 public solubility values, then derived a linear
model for solubility. The model is extremely fast and can
classify compounds as insoluble, poorly soluble, slightly soluble,
moderately, soluble, or very soluble. However, it has
difficulty in predicting the solubility of compounds with ionizable
groups. Furthermore, it is not suitable for the PK predictions that come
late in a project. Nevertheless, it can be utilized to eliminate compounds
with severe solubility problems early in the virtual screening
process.

.. seealso::

   The :ref:`solubility parameter<filter_files_solubility>` in the Filter Files chapter.

.. _molprops_polar_surface_area:

Polar Surface Area
==================

Topological polar surface area (TPSA) is based on the algorithm
developed by Ertl et al [Ertl-2000]_. In Ertl's publication, use of
TPSA both with and without accounting for phosphorus and sulfur
surface area is reported. However, evidence shows that in most PK
applications, it is better to avoid counting the contributions of
phosphorus and sulfur atoms toward the total TPSA for a molecule. This
implementation of TPSA allows either inclusion or exclusion of
phosphorus and sulfur surface area, with the default being to exclude it.

.. seealso::

   Including phosphorus and sulfur surface area:

   * The ``PSA_USE_SandP`` parameter in the :ref:`filter file
     <filter_files_PSA>`.

.. warning::

   TPSA values are mildly sensitive to the protonation state of a
   molecule. If the pKaNorm parameter is false, the TPSA value is
   calculated using the input structure, and if pKaNorm is true, the
   TPSA is calculated using the pKa normalized molecular structure.

   .. seealso::

      * The :ref:`pKa normalization<filter_process_pka_normalization>`
        section of the Filter Preprocessing chapter.

.. _molprops_lipinski:

Lipinski and Hydrogen Bonds
===========================

The work of Lipinski [Lipinski-1997]_ introduced the application of
simple filter-like rules to roughly predict late-stage PK properties,
in particular oral bioavailability. Unfortunately, Lipinski's
rule of five has come into the common vernacular to such a large
degree that some of the specific details are often lost. There are two critical examples of this. First, Lipinski
used "violation of two rules" to categorize compounds. In the subsequent
analysis, a significant difference in the two populations of molecules
was detected, however, little analysis of the importance of a single
violation was done. However, many now consider a single violation to
be bad and two violations to be worse. Second, Lipinski used well-codified
and well-understood yet imprecise definitions of "hydrogen bond
donors" and "hydrogen bond acceptors" in his classification model.
While this makes the algorithm quite understandable and easy to
implement, it sometimes causes confusion with those who prefer more
refined definitions of hydrogen bond donors and acceptors.

To address the first problem, users are allowed to set the number of
Lipinski failures required to reject a molecule. In keeping with the
original publication, the default value is 2. To address the second
problem, two kinds of hydrogen bond donors and
acceptors are calculated. In the Lipinski calculation, the published
definitions are used (donor count is the number of nitrogen or oxygen atoms
with at least one hydrogen attached and acceptors are the number of nitrogens
and oxygens). For calculation of the number of donors and acceptors in the
molecule for the sake of chemical properties, a more complex
algorithmic approach is taken. This approach identifies the donors and
acceptors outlined in the work of Mills and Dean [Mills-Dean-1996]_
and also in the book by Jeffrey [Jeffrey-1997]_.

.. seealso::

   The :ref:`Lipinski violations<filter_files_lipinski>`
   and :ref:`hydrogen-bond acceptors<filter_files_hbond_acceptor>` sections
   in the Filter Files chapter.

.. _molprops_aggregators:

Aggregators
==================

The Shoichet lab ([McGovern-2003]_; [Seidler-2003]_)
has demonstrated the importance of small-molecule aggregation in
medium and high-throughput assays. Because these small-molecule
aggregates can sequester some proteins, they give the appearance of
being active inhibitors. There are now several hundred published
aggregators, in addition to a published QSAR model for predicting
aggregation propensity. The user can eliminate any of
the known aggregators and also eliminate compounds
that are predicted to be aggregators using the QSAR model. The published QSAR model for predicting aggregators may be
considered quite aggressive, as it occasionally identifies compounds that are known
to be genuine small-molecule inhibitors of a specific protein. While
in most cases this model can be useful, it is important to gain experience with the model and
judge the performance for specific needs.

In some cases, aggregation
properties are specific to specific experimental conditions, thus
caution should be exercised in the interpretation of these
predictions. Nevertheless, aggregation remains an important issue in
HTS hit follow-up and, short of experimental validation, this flag may
be the best available.

.. seealso::

   The :ref:`aggregators parameter<filter_files_aggregators>` in
   the Filter Files chapter.

.. _PAINS_theory:

PAINS
==================

Pan-assay interference compounds (PAINS) filters are a set of functional group filters
created to identify and filter promiscuous (nonspecific) actives across
a number of screening types and targets [Baell-2010]_.  The original PAINS paper includes
a set of functional group prefilters, created via two iterations of
their work, and three sets of structure class filters, called filter sets
A, B, and C, which were used to identify and remove promiscuous actives.
The OpenEye PAINS filter set is a combination of all four filter sets
(the functional group prefilter set plus the three structural class sets)
into a single filter set.

There are two distinct use cases for the PAINS filters.  The first is the
typical prefiltering of structures prior to screening or compound selection
to remove undesirable molecules.  One can simply eliminate any molecules
which fail the PAINS filtering.

The second use case, which may ultimately be more interesting, is to use the
PAINS filters retrospectively on a set of data which has been filtered (and
tested) using another methodology.  In this scenario, the PAINS filters can be
used to identify potentially problematic reactive functionality in otherwise
reasonable, drug-like structures.  By using the table output mode and 
identifying matches for the A, B, and C filter sets, one can identify fairly
specific chemical functionalities that have been known to result in
nonspecific activity.  This can be useful information for either prioritizing
further lead development or for modifying lead structures to mitigate adverse
reactivity.

There are approximately 650 SMARTS rules which have been converted from the
SLN query strings provided in the supplemental information of the
original paper.  For the functional group filters, the authors do not provide
identifying names for each individual filter, so our PAINS rules are named
based on the comments used to describe each functional group class, prefixed
with the string ``pains_fg_[classname]``.  For the structural class filters,
the authors provided unique RegID values for each filter.  For those cases,
our rules are named based on the PAINS group and RegID
as ``pains_[group]_[RegID]``.

Note that in certain cases, the SLN
queries cannot be represented with a single SMARTS, so in those cases the
rules have been split out into multiple SMARTS patterns and are named
``pains_[group]_[RegID]1``, ``pains_[group]_[RegID]2``, etc.

.. hint:: 

   Unlike the other filter types, the PAINS filter consists only of
   functional group filters; no physical property filters are included.
   It may be desirable to combine the PAINS filter with a separate
   user-defined set of physical property filters.  The
   :ref:`filter file<filter_files>` section describes the creation of additional filter rules.




.. _omega_releasenotes:

Release History
===============

.. toctree::
   :maxdepth: 3

   version7_0_0
   version6_1_1.rst
   version6_1_0.rst
   version6_0_0.rst
   version5_1_0.rst
   version5_0_0.rst
   version4_2_2.rst
   version4_2_1.rst
   version4_2_0.rst
   version4_1_2.rst
   version4_1_1.rst
   version4_1_0.rst
   version4_0_0.rst
   version3_1_2.rst
   version3_1_1.rst
   version3_1_0.rst
   version3_0_1.rst
   version3_0_0.rst
   version2_5_1.rst
   version2_4_6.rst
   version2_4_3.rst
   version2_4_1.rst
   version2_4_0.rst
   version2_3_3.rst
   version2_3_2.rst
   version2_3_1.rst
   version2_3_0.rst
   version2_2_2.rst
   version2_2_1.rst



#################
OMEGA 6.1.1
#################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************



Omega TK 6.1.1
================================================================================

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

* The default value and the lower range for :ref:`MaxTrials<OEConfGen_OEThompsonOptions_SetMaxTrials>`
  in :ref:`OEThompsonOptions<OEConfGen_OEThompsonOptions>` have been changed from
  ``0`` to ``1``.



MolProp TK 2.6.7
================================================================================

Minor internal improvements have been made.



################################
OMEGA 6.1.0
################################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


Omega TK 6.1.0
================================================================================

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

* The new methods :ref:`SetOverlayRMS<OEConfGen_OESliceEnsembleOptions_SetOverlayRMS>` and
  :ref:`GetOverlayRMS<OEConfGen_OESliceEnsembleOptions_GetOverlayRMS>` have been added to 
  :ref:`OESliceEnsembleOptions <OEConfGen_OESliceEnsembleOptions>`, enabling conformer slicing
  with in-place RMSD calculation between conformers, with :ref:`OEConfSlicer <OEConfGen_OEConfSlicer>`
  and :ref:`OESliceEnsemble <OEConfGen_OESliceEnsemble>`.


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

* :ref:`OEOmega <OEConfGen_OEOmega>` now properly places carboxylic acids in cis
  configuration when hydrogen sampling is not performed.

* All conformers generated with :ref:`OEMacrocycleOmega<OEConfGen_OEMacrocycleOmega>`
  now properly set the dimensionality of the conformers to 3.


MolProp TK 2.6.6
================================================================================

Minor internal improvements have been made.



..  program:: omega

OMEGA 6.0.0
==============

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

* Supported input and output file formats for **OMEGA** have been revised
  to improve clarity.

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

* **OMEGA** now properly propagates ``SD data`` of molecules when running jobs
  using ``MPI``.

* **OMEGA** no longer reports time used per molecule in the log output, but
  they are properly reported in the ``CSV`` report.



Omega TK 6.0.0
================================================================================

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

* The following new methods have been added to :ref:`OETorDriveOptions <OEConfGen_OETorDriveOptions>`
  to enable use of Thompson sampling, instead of exhaustive sampling, of torsion angles during
  torsion driving. Use of Thompson sampling is especially useful, being significantly faster
  without losing quality, in generating smaller ensembles as obtained with the
  :ref:`FastROCS <OEConfGen_OEOmegaSampling_FastROCS>` or :ref:`ROCS <OEConfGen_OEOmegaSampling_ROCS>`
  modes.

  * :ref:`GetUseThompson<OEConfGen_OETorDriveOptions_GetUseThompson>`
  * :ref:`SetUseThompson<OEConfGen_OETorDriveOptions_SetUseThompson>`
  * :ref:`GetThompsonOptions<OEConfGen_OETorDriveOptions_GetThompsonOptions>`
  * :ref:`SetThompsonOptions<OEConfGen_OETorDriveOptions_SetThompsonOptions>`

* A new class, :ref:`OEThompsonOptions<OEConfGen_OEThompsonOptions>`, has been added that
  enables controlling Thompson sampling during torsion driving.

* Generation of a single conformer with :ref:`OEConformerBuilder<OEConfGen_OEConformerBuilder>`
  has been modified to use Thompson sampling.

Minor bug fixes
--------------------------------------------------------------------------------
* User-defined values passed through :ref:`SetEnergyWindow<OEConfGen_OESliceEnsembleOptions_SetEnergyWindow>`,
  :ref:`SetMaxConfs<OEConfGen_OESliceEnsembleOptions_SetMaxConfs>`, and
  :ref:`SetRMSThreshold<OEConfGen_OESliceEnsembleOptions_SetRMSThreshold>`
  are now properly accounted for, even when the corresponding defaults are range-based.

* Molecule titles are retained when :ref:`Build<OEConfGen_OEOmega_Build>` fails in
  :ref:`OEOmega<OEConfGen_OEOmega>` with ``fails to build structure from CT``.

* A verbose log is provided for fragments that fail when :ref:`Build<OEConfGen_OEOmega_Build>` fails in
  :ref:`OEOmega<OEConfGen_OEOmega>` with ``fails to build structure from CT``.

* The :ref:`OEOmegaIsGPUReady <OEConfGen_OEOmegaIsGPUReady>` function has been safeguarded from a rare crash.
  The function has also been updated to check not only for device 0,
  but for devices from 0 to 100.




MolProp TK 2.6.5
================================================================================

Minor internal improvements have been made.




..  program:: omega

OMEGA 5.1.0
==============

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

* **MakeFragLib** now generates outputs that are consistent with outputs generated 
  from **OMEGA**.  The following outputs are generated by default.

    * makefraglib_frags.oeb.gz: Output fragments library
    * makefraglib_log.txt: Output run log
    * makefraglib_param.txt: Parameter file for rerunning the job

..  program:: makefraglib

* These new command line parameters have been introduced in **MakeFragLib**.

    * :option:`-ewindowRing`: Energy window for ring fragment conformer generation
    * :option:`-rmsRing`: RMS threshold for ring fragment conformer generation
    * :option:`-startfactRing`: Multiplier for number of starts during ring fragment conformer generation
    * :option:`-timeLimit`: Maximum time in seconds allowed for non-ring fragment generation
    * :option:`-fragGen`: Maximum number of conformers to generate for non-ring fragments
    * :option:`-fragKeep`: Maximum number of fragments to keep for non-ring fragments
    * :option:`-timeLimitRing`: Maximum time in seconds allowed for ring fragment generation
    * :option:`-fragGenRing`: Maximum number of conformers to generate for ring fragments
    * :option:`-fragKeepRing`: Maximum number of fragments to keep for ring fragments

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

* Running **OMEGA** with the ``-useGPU false`` option on a GPU-configured machine previously caused a memory leak.
  This issue has now been resolved.

* **MakeFragLib** now generates multiple conformers of fragments as expected.

* **OMEGA** can now properly handle input ``CIF`` files.



Omega TK 5.1.0
================================================================================

New features
--------------------------------------------------------------------------------
* A new **Flipper** option has been added to enumerate internally perceived 
  relative stereocenters (e.g., 1,4-disubstituted cyclohexanes).
  See :ref:`SetEnumRelativeAtomStereo<OEConfGen_OEFlipperOptions_SetEnumRelativeAtomStereo>`.

Minor bug fixes
--------------------------------------------------------------------------------
* Stereochemistry of input molecules is now respected more consistently
  in :ref:`OEMacrocycleBuilder <OEConfGen_OEMacrocycleBuilder>`.

* For :ref:`SetMacroCycOptions<OEConfGen_OEFragBuilderOptions_SetMacroCycOptions>`
  in :ref:`OEFragBuilderOptions<OEConfGen_OEFragBuilderOptions>`, defaults for :ref:`SetFragGen <OEConfGen_OEFragOptions_SetFragGen>`,
  :ref:`SetFragKeep <OEConfGen_OEFragOptions_SetFragKeep>`, and
  :ref:`SetStartFactor <OEConfGen_OERingFragOptions_SetStartFactor>`  have been
  changed to more appropriate values of 50000, 1024, and 20, respectively.

* An issue with the order of loading rules to an existing torsion
  library with :ref:`AddTorsionLibrary<OEConfGen_OETorLib_AddTorsionLibrary>`
  has been fixed.

* A duplicate entry from the ``GUBA`` torsion library has been removed.





MolProp TK 2.6.4
================================================================================

Minor internal improvements have been made.





..  program:: omega

OMEGA 5.0.0
==============

New Features
--------------------------------------------------------------------------------
* The default fragment library in **OMEGA** has been updated in ``Linux`` and
  ``OSX`` platforms. The new fragment library consists of over 580 K fragments,
  replacing the previous library of ~80 K fragments.  **OMEGA** in Windows
  still uses the previous library as default, but the modified library,
  ``omega_fragment_lib_2023.oeb.gz``, is available through the ``-addfraglib``
  on the `database downloads page <https://www.eyesopen.com/database-downloads>`_.

* A new parameter, ``-failed``, has been added to **OMEGA** to allow reporting
  the failed molecules into a separate file.

Major bug fixes
--------------------------------------------------------------------------------
* Running **OMEGA** with ``-fixfile`` and ``-mpi_np`` now appropriately picks
  up the file for fixing part of molecule.

* Output ``rpt.csv`` file from **OMEGA** now contains SMILES strings for most molecules.
  The entry is still blank for extremely large molecules that are beyond 400 atoms.

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

* Running **OMEGA** with one molecule in the ``classic/pose/dense/rocs/fastrocs`` modes and using 
  ``-progress percent`` no longer causes the input molecule to be read twice.



Omega TK 5.0.0
================================================================================

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

* The default fragment library for  :ref:`OEOmega<OEConfGen_OEOmega>`
  and :ref:`OEMolBuilder<OEConfGen_OEMolBuilder>` has been updated. The new
  fragment library consists of over 580 K fragments, replacing the previous
  library with ~80 K fragments.

* Three new force fields have been added and can be used with
  :ref:`OEMolBuilder<OEConfGen_OEMolBuilder>` and :ref:`OETorDriver<OEConfGen_OETorDriver>`
  in :ref:`OEOmega<OEConfGen_OEOmega>`:

    * :ref:`SAGE <OEConfGen_OEOmegaForceFieldType_SAGE>`
    * :ref:`SAGE_NOESTAT <OEConfGen_OEOmegaForceFieldType_SAGE_NOESTAT>`
    * :ref:`SAGE_SHEFF <OEConfGen_OEOmegaForceFieldType_SAGE_SHEFF>`

* The behavior of :ref:`OEFlipperOptions <OEConfGen_OEFlipperOptions>` has changed.
  New flags have been added
  to :ref:`OEFlipperOptions <OEConfGen_OEFlipperOptions>`,
  facilitating more complete decoupling of individual flags and
  more selective enumeration of specific stereocenter classes and environments
  than was previously possible.

* A new option class,
  :ref:`OEFlipperClassicOptions <OEConfGen_OEFlipperClassicOptions>`,
  has been added to allow a detailed
  comparison of the new flag behaviors with the previous OEFlipper enumeration behavior.
  This class will be deprecated in a future toolkit release.

* The internal algorithm for storage and usage of torsion rules in
  :ref:`OETorLib<OEConfGen_OETorLib>` has been modified to improve performance
  when working with a library containing a large set of rules.

* A new return code :ref:`FailedCharges <OEConfGen_OEOmegaReturnCode_FailedCharges>` has been
  added to :ref:`OEOmegaReturnCode <OEConfGen_OEOmegaReturnCode>` to indicate failures due to partial charge assignment.

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

* The order of torsion rules in the default
  :ref:`OETorLib<OEConfGen_OETorLib>` has been changed to ensure that a
  specific rule is not ignored due to the presence of a more generic rule.




MolProp TK 2.6.3
================================================================================

Minor internal improvements have been made.





..  program:: omega

OMEGA 4.2.2
==============

Minor bug fixes
--------------------------------------------------------------------------------
* Defaults for ``-warts`` and ``-flipper_warts`` have been changed to ``False``
  in **OMEGA**.

* **OMEGA** now fails robustly when incorrectly attempting to use ``-fixsmarts``
  without providing ``-fixfile`` or turning ``-fromCT`` to ``false``.



Omega TK 4.2.2
================================================================================

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

* The OEOmega method :ref:`Build <OEConfGen_OEOmega_Build>`
  will now fail when ``MCS matching`` is requested but a corresponding ``FixMol``
  has not been set. 




MolProp TK 2.6.2
================================================================================

Minor internal improvements have been made.




..  program:: omega

==============
OMEGA 4.2.1
==============

*Fall 2022*

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

* A new command line parameter, :option:`-fixmcs`, has  been added to provide enhanced
  support to fix part of a molecule during conformer generation based on
  maximum common substructures (MCS).

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

* :ref:`OMEGA <chapter_omega>` now generates report files with
  appropriate content.

* Log files from :ref:`OMEGA <chapter_omega>` now contain
  newly generated titles of molecules for untitled molecules.



Omega TK 4.2.1
================================================================================

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

* The ability to fix a part of a molecule during conformer generation
  based on maximum common substructure (MCS) has been added. The following new methods
  have been added to the :ref:`OEConfFixOptions <OEConfGen_OEConfFixOptions>`
  to enable this functionality:

    * :ref:`SetFixMCS <OEConfGen_OEConfFixOptions_SetFixMCS>`
    * :ref:`GetFixMCS <OEConfGen_OEConfFixOptions_GetFixMCS>`
    * :ref:`SetMCSFunc <OEConfGen_OEConfFixOptions_SetMCSFunc>`
    * :ref:`GetMCSFunc <OEConfGen_OEConfFixOptions_GetMCSFunc>`
    * :ref:`SetMCSType <OEConfGen_OEConfFixOptions_SetMCSType>`
    * :ref:`GetMCSType <OEConfGen_OEConfFixOptions_GetMCSType>`
    * :ref:`SetMCSMinAtoms <OEConfGen_OEConfFixOptions_SetMCSMinAtoms>`
    * :ref:`GetMCSMinAtoms <OEConfGen_OEConfFixOptions_GetMCSMinAtoms>`

* New methods :ref:`SetIgnoreStereo <OEConfGen_OEMolBuilderOptions_SetIgnoreStereo>`
  and :ref:`GetIgnoreStereo <OEConfGen_OEMolBuilderOptions_GetIgnoreStereo>` have been
  added to :ref:`OEMolBuilderOptions <OEConfGen_OEMolBuilderOptions>` to allow
  continuation of conformer generation when specified stereo signatures in a molecule
  could not be honored.

* New methods :ref:`SetMaxEnumConfs <OEConfGen_OEMolBuilderOptions_SetMaxEnumConfs>`
  and :ref:`GetMaxEnumConfs <OEConfGen_OEMolBuilderOptions_GetMaxEnumConfs>` have been
  added to :ref:`OEMolBuilderOptions <OEConfGen_OEMolBuilderOptions>` to allow
  specifying the  maximum number of conformers to be generated from ring enumeration,
  nitrogen enumeration, and/or hydrogen sampling.

* Verbose mode logging now reports torsion angles sampled, along with the rules,
  during torsion driving.


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

* Conformer generation with :ref:`OEOmega.Build <OEConfGen_OEOmega_Build>`
  or :ref:`OEMolBuilder.Build <OEConfGen_OEMolBuilder_Build>` now fails correctly
  when specified stereo signatures on a molecule cannot be honored. The existing 
  behavior, to carry on even if stereo signatures could not be honored, can be
  obtained by setting :ref:`IgnoreStereo <OEConfGen_OEMolBuilderOptions_SetIgnoreStereo>`
  to ``true``.

* Ring fragment building during :ref:`OEOmega.Build <OEConfGen_OEOmega_Build>`,
  :ref:`OEFragBuilder.Build <OEConfGen_OEFragBuilder_Build>`,
  :ref:`OEMolBuilder.Build <OEConfGen_OEMolBuilder_Build>`, or
  :ref:`GenerateMissingFrags <OEConfGen_OEMakeFragLib_GenerateMissingFrags>`
  now properly honors the :ref:`SetFragKeep <OEConfGen_OEFragOptions_SetFragKeep>`
  parameter regarding the maximum number of generated fragment conformers to be kept.





MolProp TK 2.6.1
================================================================================

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

* A new free function, :ref:`OECheckXLogXType <OEMolProp_OECheckXLogXType>`, that returns ``true`` if an atom has a
  valid XLogPType has been added.

* A new free function, :ref:`OECheckXLogXTypes <OEMolProp_OECheckXLogXTypes>`, that returns ``true`` if all atoms excluding
  hydrogen in a molecule have valid XLogP types has been added.


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

* An issue with filter output failure reporting, where failure due to the rules :ref:`ALLOWED_ELEMENTS <ALLOWED_ELEMENTS>` 
  and :ref:`ELIMINATE_METALS <ELIMINATE_METALS>` was not
  included in the output table, has been fixed.





OMEGA 4.2.0
================================================================================

*Spring 2022*

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

* **OMEGA** torsion driving (that is, in the ``classic``, ``rocs``, ``fastrocs``,
  ``dense``, and ``pose`` modes) now generates outputs that are consistent with
  outputs generated in the ``macrocycle`` mode.  The following outputs are
  generated by default:

    * oeomega_mode_conformers.oeb.gz: Output molecule conformers
    * oeomega_mode_log.txt: Output run log
    * oeomega_mode_param.txt: Parameters file for re-running the job
    * oeomega_mode_rpt.csv: Output Report

* **OMEGA** now supports ``cxsmiles`` file format with enhanced stereo information
  as input.

* A new command line parameter, ``-flipper_enhstereo``, has  been added to provide enhanced
  stereo support for stereo enumeration when ``-flipper`` is set to ``true``.

* **OMEGA** no longer supports writing outputs in non-3D file formats (e.g. ``smi``).

* **OMEGA** now provides a detailed description of available modes when an invalid mode
  is presented in the command line.

* **OMEGA** torsion driving (i.e., in the ``classic``, ``rocs``, ``fastrocs``, 
  ``dense``, and ``pose`` modes) now reports correct defaults for parameters in the command line
  help. 

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

* ``oeomega classic --help`` now returns a list of ``simple`` command line parameters.  
  A list of all parameters can be viewed by typing ``oeomega classic --help all``

* Inputs for **OMEGA** command line range parameters (i.e., ``-erange``, ``-maxConfRange``,
  and ``-rmsrange``) have been simplified and now accept list-like parameters
  (e.g., ``-maxConfRange 10 20 30`` is a valid input).

* An issue has been fixed to enable **OMEGA** to generate an appropriate set of
  conformers when run with ``-fixfile`` and a ``-maxmatch`` value greater than 1.

* An issue has been fixed related to **GPU-OMEGA** occasionally writing to standard out stream. 

* An issue has been fixed to enable **Flipper** to support piped input.



Omega TK 4.2.0
================================================================================

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

* Support for consideration of MDL enhanced stereo collection
  information during isomer generation has been added.  :ref:`The OEFlipperOptions class <OEConfGen_OEFlipperOptions>` adds a
  new ``SetEnhancedStereo`` option
  to control consideration of explicit enhanced stereo groups defined by :ref:`OEGroupBase <OEChem_OEGroupBase>` information
  that may have been read from ``V3000`` the :ref:`OEFormat <oechem_OEFormat>` values indicating ``SDF`` structures or ``CXSMILES`` files.

* A new method, :ref:`SetFragBuilderMode <OEConfGen_OEMolBuilderOptions_SetFragBuilderMode>`, has been added
  that allows setting fragment building mode in the corresponding :ref:`OEFragBuilderOptions <OEConfGen_OEFragBuilderOptions>`.

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

* Internal generic data tags applied to the ``flip-ee`` used for performance
  during the flipping activity are now stripped from the structures
  returned by :ref:`OEFlipper <OEConfGen_OEFlipper>` as this information is no longer relevant.




MolProp TK 2.6.0
================================================================================

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

* The ability to filter based on aromatic ring count and fraction of CSP3 carbons has been added.




OMEGA 4.1.2
================================================================================

*Fall 2021*

*  Minor internal improvements have been made.


Omega TK 4.1.2
================================================================================

*Fall 2021*

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

* An issue with overwriting partial charges of atoms in input molecules has been fixed.  

* The :ref:`section_examples_stereo_and_torsion` example has been modified to use 
  :ref:`OEFlipperOptions <OEConfGen_OEFlipperOptions>`.

* An issue running :ref:`OEOmega <OEConfGen_OEOmega>` when both
  SetUseGPU  and
  :ref:`SetSampleHydrogens <OEConfGen_SetSampleHydrogens>` are set to `True`
  was fixed by disabling SetUseGPU
  in these cases.



MolProp TK 2.5.7
================================================================================

*Fall 2021*


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

* A method, :ref:`GetMessage <OEMolProp_GetMessage>`, was added to the :ref:`OEFilter <OEMolProp_OEFilter>` class
  to be able to retrieve
  information on whether the filter passed a molecule, or why it failed
  a specific molecule.

* A method, :ref:`SetErrorLevel <OEMolProp_SetErrorLevel>`, was added to
  the :ref:`OEFilter <OEMolProp_OEFilter>` class
  to add explicit control of
  warnings output by the filter class and the filter application.

* A BlockBusterPAINS filter was added in the :ref:`OEFilterType <OEMolProp_OEFilterType>` namespace,
  which   combines filtering criteria   for the BlockBuster and   PAINS filters .

* Excess warning output that was causing large log files is now suppressed by default,
  and can be switched on using the new :ref:`SetErrorLevel <OEMolProp_SetErrorLevel>` method.
  See :ref:`OEFilterType <OEMolProp_OEFilterType>`.






OMEGA 4.1.1
================================================================================

*July 2021*

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

* ``Flipper`` now has an improved default output file name.


Omega TK 4.1.1
================================================================================

*July 2021*

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

* Function :ref:`OEOmegaSystemHasGPU <OEConfGen_OEOmegaSystemHasGPU>` has been added to test
  for availability of a GPU.
  
Major bug fixes
--------------------------------------------------------------------------------
* A bug that caused a segmentation fault when zero was passed to the
  :ref:`SetMaxConfs <OEConfGen_SetMaxConfs>` method has been
  fixed. 

* And issue that prevented oeomega from using the GPU in child threads when
  :ref:`OEOmegaIsGPUReady <OEConfGen_OEOmegaIsGPUReady>` was called from the main thread has been fixed.

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

* An issue with stereo specificity of the imino group (=NH) not being retained in
  a macrocycle has been fixed.

* An issue with loss of relative stereo marked atoms in macrocycle mode has been fixed.




MolProp TK 2.5.6
================================================================================

*July 2021*

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

* An issue with :ref:`OEGetRotatableBondCount <OEMolProp_OEGetRotatableBondCount>` counting carbamates
  and ureas as rotatable has been fixed.





OMEGA 4.1.0.0
================================================================================

*Fall 2020*

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

* The defaults for the ``-warts`` and ``-flipper_warts`` in **OMEGA** have been
  changed from ``false`` to ``true``.

* The Boolean flag ``-mmff`` has been added to the **Filter** application to allow filtering of
  atoms that cannot be atom-typed with ``MMFF``.  It is ``false`` by default.

* Six new flags have been added to **Flipper** to allow more control when selecting
  stereo centers as well as improving usability of the program:

  * ``-enumEZ``
  * ``-enumRS``
  * ``-enumBridgehead``
  * ``-molNames``
  * ``-prefix``
  * ``-progress``

* The built-in default filter for the **Filter** application is now in sync with
  the provided ``filter_frag.txt`` file.

* **GPU-OMEGA** now requires a minimum NVIDIA Driver version of 450.x and a
  minimum GPU compute capability of 3.5. See :ref:`section_supported_gpus_drivers`
  and :ref:`section_supported_gpus` for more details.

* Conformer generation using ``dense`` mode will now default to running on the
  CPU instead of the GPU. The other torsion driving sampling modes (``classic``,
  ``rocs``, ``fastrocs`` and ``pose``) will still run on a GPU by default if one
  is available on a Linux platform. For details on how to run with ``dense``
  mode sampling on a GPU see the :ref:`Usage<section_gpuomega_app_usage>` section
  of the **GPU-OMEGA** docs.

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

* **OMEGA** in the ``macrocycle`` mode now works with pipes.

* A memory leak in **GPU-OMEGA** has been fixed.

Documentation Changes
-------------------------------------------------------------------------------

* Documentation for the ``-erange``, ``-maxConfRange``, and ``-rmsrange`` for **OMEGA**
  has been improved for clarification.


Omega TK 4.1.0
================================================================================

*Fall 2020*

New features
--------------------------------------------------------------------------------
* **GPU-Omega** now requires a minimum NVIDIA Driver version of 450.x and a
  minimum GPU compute capability of 3.5. See :ref:`section_supported_gpus_drivers`
  and :ref:`section_supported_gpus` for more details.
* Conformer generation using ``dense`` mode now defaults to running on the
  CPU instead of the GPU. The other torsion-driving sampling modes (``sparse``,
  ``rocs``, ``fastrocs``, and ``pose``) will still run on a GPU by default if one
  is available on a Linux platform. For details on how to run with ``dense``
  mode sampling on a GPU, see the :ref:`Usage<section_gpuomega_usage>` section
  of the **GPU-Omega** docs.

* A new class, :ref:`OEFlipperOptions <OEConfGen_OEFlipperOptions>`, has been added that defines parameters
  for specifying stereo centers and other options.

* :ref:`OEFlipper <OEConfGen_OEFlipper>` has been updated to take a molecule and an
  :ref:`OEFlipperOptions <OEConfGen_OEFlipperOptions>` value.
  The old version of :ref:`OEFlipper <OEConfGen_OEFlipper>`
  that takes five parameters has been deprecated.

* A new function, :ref:`OEFlipperStereoCenters <OEConfGen_OEFlipperStereoCenters>`, has been added that returns a number of
  undefined stereo centers in a molecule as interpreted by :ref:`OEFlipper <OEConfGen_OEFlipper>`.

Major bug fixes
--------------------------------------------------------------------------------
* A memory leak in **GPU-Omega** has been fixed.

* An issue with generating conformers on the CPU using child processes with the same
  :ref:`OEOmega <OEConfGen_OEOmega>` object has been fixed.

* **GPU-Omega** no longer throws an error when attempting to generate conformers with the same
  :ref:`OEOmega <OEConfGen_OEOmega>` object in child processes. Instead, it falls back to the CPU.
  To use **GPU-Omega** with child processes, each child must construct a new :ref:`OEOmega <OEConfGen_OEOmega>` object.

Minor bug fixes
--------------------------------------------------------------------------------
* :ref:`OEConfGen <OEConfGen_ClearFragLibs>` now clears **all** fragment
  libraries. Previous releases did not clear the internal shared fragment library
  (a shared memory library of fragments accrued while generating conformers with the same OEOmega object).

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

* :ref:`OEOmegaReturnCode <OEConfGen_OEOmegaReturnCode>` has been updated to reflect the current possible values.








MolProp TK 2.5.5
================================================================================

*Fall 2020*

* Minor internal improvements have been made.




.. _section_omega_releasenotes_4006:

OMEGA 4.0.0.6
================================================================================

* The **Filter** application  no longer counts invertible-nitrogens as chiral centers.

* **OMEGA** no longer enumerates specified nitrogen when ``-enumNitrogen`` is ``unspecified``.

.. _section_omega_releasenotes_400:

OMEGA 4.0.0
================================================================================

*Spring 2020*

* This version of **OMEGA** has been built using **OEToolkits 2020.0**.

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

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

* **OMEGA** in the ``macrocycle`` mode has been rewritten to take advantage of
  the newly extended corresponding functionality in the 2020.0 release of
  **Omega TK**.  With this update, some of the previous application-specific
  functionality, including duplicate removal and overlaying of the generated conformers,
  are now directly taken care of by the underlying toolkit functionality. From a performance
  point of view, **OMEGA** ``macrocycle`` is now more efficient for finding new conformers
  during conformer generation.

* The ``-dielectric_constant`` is no longer available as an option for torsion driving
  based **OMEGA** modes.  This flag has been removed since it had little effect on conformers 
  generated using torsion driving. The ``-dielectric_constant`` flag is still available as an 
  option for **OMEGA** in ``macrocycle`` mode.


.. _omega_releasenotes_221:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OMEGA 2.2.1
================================================================================

Bug fixes
--------------------------------------------------------------------------------

*  The new build algorithm introduced in v2.2.0 could, on rare
   occasions, generate a structure with heavy atom clashes. This
   release is mainly a bug fix for this problem.


.. _omega_releasenotes_222:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OMEGA 2.2.2
================================================================================

Bug fixes
--------------------------------------------------------------------------------

*  Fixed a major bug that would cause highly-symmetric,
   highly-fluorinated compounds to crash the program or hang a slave
   in PVM mode.

*  Fixed a bug in atom typing when building fragments from scratch
   that, in some rare cases, could result in differing fragment
   geometries depending on the order of input of the molecules.

*  Added more places that check for time exceeding max time. This is more
   just to prevent overly large molecules from appearing to hang. 

*  If OMEGA is called with a fixed predicate, this now implies that
   FromCT is false. In other words, if you want to use a predicate to
   fix atoms, you need to use a 3D structure as input.


.. _omega_releasenotes_230:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OMEGA 2.3.0
================================================================================

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

*  The distribution and installation of **OMEGA** has been modified.  The
   Windows distribution is now a standard .exe installer, and the macOS
   distribution is a dmg containing a standard pkg installer.  The
   executables are now scripts that chose the correct version of the
   program at runtime.  Please see the Installation and Platform Notes
   for details.

*  The defaults for MaxConfs and RMSThreshold are changed in this
   version.  The default for MaxConfs is reduced from 400 to 200,
   while the value for RMSThreshold goes from 0.8 down to 0.5. These
   changes are based on maintaining good reproduction of the crystal
   structure test set, virtual screening tests with **ROCS** and **FRED**, and
   pose prediction tests with **FRED**.

*  The method ``OEConfGen::OEOmega::ClearFixFile`` is added to
   the **OMEGA** library.  This allows an ``OEConfGen::OEOmega``
   instance to be reused for an unrestrained search after it has
   previously been used for a fixed search.

*  Untitled molecules are given unique titles of omega_1, omega_2, and
   so on.  Titles allow molecules to be located in the log files.

Bug fixes
--------------------------------------------------------------------------------

*  Fixed a major bug where molecules that have missing torsion rules
   caused **OMEGA** to crash.  Molecules with missing torsion rules are
   now sent to the *omega2.fail* file and are not processed.  Missing
   torsion rules are typically caused by highly unusual molecules for
   which OEChem cannot properly assign valence to all atoms.

*  Fixed a bug in duplicate conformer removal that caused some
   conformers that should have been removed to pass through as unique.
   This bug also caused occurrences where a reduction in maxconfs led
   to an increase in the number of conformers returned.

*  Fixed a bug that caused SD data on single conformer molecules to be removed.

*  Fixed a bug in the *flipper* library that left 3D coordinates intact,
   which caused stereo chemistry to be ambiguous.  The *flipper* library
   now replaces 3D coordinates with zeros.

*  Fixed a bug where the ``SyM`` tag from previous **OMEGA**
   calculations caused problems when those molecules where passed back
   in.  Also, the ``O2MolId`` tag is now removed from molecules
   before they are sent to the output.

*  When the number of stereo centers exceeds the number of -maxcenters
   M, *flipper* now generates :math:`2^{M}` random non-repeating flips.
   Previous versions generated :math:`2^{M}` random flips, leading to
   molecules with the same stereochemistry being returned multiple
   times.


.. _omega_releasenotes_231:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OMEGA 2.3.1
================================================================================

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

*  The **OMEGA** application now includes a utility named oeb2sdconf that
   allows **OMEGA** generated conformers to be used with the MOE program.
   Please contact Chemical Computing Group support if you require
   assistance with this utility.

Bug fixes
--------------------------------------------------------------------------------

*  Fixed a bug where the omega2 PVM features would not work on some platforms.

*  Fixed a bug where the omega2 script would not function properly with filenames that had spaces in them.


.. _omega_releasenotes_232:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OMEGA 2.3.2
================================================================================

Bug fixes
--------------------------------------------------------------------------------

*  Fixed a bug where molecules containing boron or selenium could
   cause a crash.  These molecules now are written to the *'.fail'* file
   due to missing force field parameters and the program will proceed
   to the next molecule.


.. _omega_releasenotes_233:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OMEGA 2.3.3 
================================================================================

*(March 2009)* (Toolkit only)

This release was for the toolkit only.  For more details please refer to the OmegaTK documentation.


.. _omega_releasenotes_240:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OMEGA 2.4.0  
================================================================================

*(November 2009)* (Toolkit only)

This release was for the toolkit only.  For more details please refer to the OmegaTK documentation.

.. _omega_releasenotes_241:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OMEGA 2.4.1
================================================================================

*(June 2010)*

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

*  FILTER is now bundled with the **OMEGA** distribution and will run with a valid **OMEGA** license.

*  **OMEGA** and :ref:`MakeFraglib <chapter_makefraglib>` may now be run with MPI using the `oempirun` script.  (Not available on all platforms)

*  The default for **OMEGA** has been changed to require all stereocenters to be specified.  Molecules with unspecified 
   stereo will fail, except for unspecified invertible nitrogens which are allowed and will not cause the molecule to fail.  The previous
   behavior was for **OMEGA** to choose a random stereoisomer.  This default can be changed back to the previous behavior 
   by setting `-strictstereo` to ``false``.

*  By default, **FLIPPER** will no longer flip invertible nitrogens.  The default path is for **FLIPPER** to leave them unspecified
   and allow **OMEGA** to enumerate them.  Flipping invertible nitrogens in both **FLIPPER** and then **OMEGA** will lead to duplication.  These
   options can be changed with the `-enumNitrogen` flag available in both applications.

*  The default for **OMEGA** has been changed to no longer use 'close enough' atom typing.  If a proper MMFF atom type 
   cannot be found for 
   an atom then the molecule will fail.  Previous versions would use a different atom type of the same element if it 
   was available.  
   The previous behavior for atom type substitution can be enabled by setting `-strictatomtyping` to ``false``.

*  **OMEGA** now has the option to require on-the-fly generation of fragments to be the same as the :ref:`MakeFraglib <chapter_makefraglib>` utility
   by setting `-strictfrags` to ``true``. 
   This fragment generation is more rigorous but also more time consuming.

*  The convenience flag `-strict` has been added to turn on or off all of the strict options.  These include 
   `-strictstereo`, `-strictatomtyping` and `-strictfrags`.

*  On-screen progress has been enabled for OMEGA and :ref:`MakeFraglib <chapter_makefraglib>` using the `-progress` flag.
   The options are `none`, `dots`, `log`, and `percent`.

*  The `-maxconfgen` and `-maxpoolsize` flags have been removed.  These options are set internally and adjusted automatically 
   subject to the user
   defined variable of `-maxconfs`.  Additionally, hard limits have been removed from
   these variables and they are now only limited by available memory. 

*  Improper formatting of the `-erange`, `-maxConfRange`, and `-rmsrange` parameters will cause OMEGA to exit immediately.  Previously
   the application would throw a warning but continue the calculation without using the parameters.

*  The flag `-fixsmarts` has been created to allow a smarts pattern to be used to fix
   a portion of the molecule.  This requires 3D coordinates to be available from either 
   a 3D input file with `-fromCT` set to ``false`` or from a molecule set using `-fixfile`.

Bug fixes
--------------------------------------------------------------------------------

*  A bug was fixed in :ref:`MakeFraglib <chapter_makefraglib>` where the setting `-fromCT false` could give nonsense fragments.

*  Crashes have been fixed that could occur when the `-fixfile` could not find a valid match or did not have 
   enough atoms to match against in a ring system.

*  Program no longer crashes if there is not enough memory for duplicate removal.  If there is not enough memory 
   available for allocation then the application will exit immediately.


.. _omega_releasenotes_243:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OMEGA 2.4.3 
================================================================================

*(August 2010)*

Bug fixes
--------------------------------------------------------------------------------

*  A bug was fixed where slave nodes required a license.  This has been fixed and now only the master requires a license.

*  The -warts flag did not work when writing to formats other than .oeb or .oeb.gz.  This has been corrected in version 2.4.3.



.. _omega_releasenotes_246:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OMEGA 2.4.6
================================================================================

*(February 2012)*

New features
--------------------------------------------------------------------------------
*  Now uses an extension of the MMFF94 force field for tricoordinate boron compounds. 
   Most compounds containing B-X bonds where X=C,N,O,S,
   and H are covered with the following exceptions: X=N(imine),N(sulfonamide),
   N(pyridinium) and N(quaternary). Also not supported are compounds in which
   boron is bonded to X=F,Cl,Br,I,B and Si, or makes a bond angle BYX.
   Compounds in which boron is a part of four-membered rings of B1CCC1 type are also
   not available in the current parameterization because their existence is questionable:
   Ab initio calculations at the MP2/6-31G** level failed to identify stable structures
   for them (highly polar structures in which boron is four-coordinated are formed).

Bug fixes
--------------------------------------------------------------------------------

*  Fixed a bug where **OMEGA** wasn't checking if 3D construction of fragment generation was successful.

*  Fixed a bug where output from flipper could still fail in **OMEGA** for missing stereo chemistry.  Now the rules for required stereo chemistry are consistent.

*  Fixed a bug where setting stereo chemistry in too small of a ring could cause a crash.  Now only rings greater than 7 members and only one double bond will be set with flipper.

*  Fixed a bug where **OMEGA** wasn't checking if user generated fragment libraries were in OEB format.  Fragment libraries must be in OEB format.

*  Fixed bugs related to nonsense values for command line parameters.  User-supplied parameters must be a legal value.  The '--help <parameter>' command will print out the legal values.

*  Fixed a bug where SD tagged data wasn't passed along to output molecules.


.. _omega_releasenotes_251:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OMEGA 2.5.1
================================================================================

*(May 2013)*

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

* **FILTER** is now completely bundled into the **OMEGA** package.  The manuals have been consolidated into this single manual
  and **FILTER** has taken on the **OMEGA** version number.

* An option has been added to allow hydrogen atoms in -OH, -SH, and amines to take part in conformational sampling.  This
  new option can be enabled via the `-sampleHydrogens` parameter.
  By default, hydrogen atoms are not sampled.

* A `-warts` option has been added to `flipper`.

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

* Now using `-fixsmarts` without `-fixfile` will
  rematch for every input structure.  Previously, this would only match the first input structure and reuse
  that match for the rest of the calculation.  Using both `-fixsmarts` and 
  `-fixfile` will continue to match against the fixfile and use that match for the
  entire calculation.

* Partial ring matching with `-fixsmarts` or `-fixfile` could
  cause a crash.  Now only full ring systems may be specified and any attempt at matching a partial ring system will fail
  gracefully.

* Planar molecules could have problems sprouting hydrogens when using `-fromCT false` 
  because **OMEGA** was treating them as 2D.  Now **OMEGA** will assume that planar molecules are properly 
  defined 3D coordinates in this situation.

* Stereochemistry at the attachment points of rings with four or less atoms could be lost.  Now stereochemistry
  is saved for rings of all sizes.

* A bug has been fixed where exceptionally long torsion rules could get cutoff early.

* A bug has been fixed where older TK licenses in the license file could cause the OMEGA application to fail. [Case #13466]

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

* Only 3D coordinates were being cleared in **FLIPPER**.  Now 2D coordinates are cleared as well.

* Fragment generation during an **OMEGA** calculation with `strictfrags` parameter 
  enabled could yield slightly different fragments than the :ref:`MakeFraglib <chapter_makefraglib>` app.  This has been corrected
  for consistency.

* Tags for rotor compression are no longer attached to the output molecules when rotoroffsetcompress is false.  
  It was discovered that these tags confuse VIDA when they are attached but not used.

* The torsion library has been updated with better angles for a biphenyl torsion. 
  The entry for 90 degrees has been removed and +/-30 degrees has been added.

* FILTER has been fixed to no longer have an atom order dependence when setting a pH model.

Other changes
---------------------------------------------------------------------------------

* PVM (parallel virtual machine) is no longer supported. OpenMPI version 1.6 is supported
  on all platforms.  The `-mpi_np` and `-mpi_hostfile` flags are now used to run **OMEGA** and `makefraglib` in MPI mode.
  These new flags replace the `oempirun` script.

* This will be the last release to support SuSe 10.


.. _omega_releasenotes_300:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OMEGA 3.0.0 
================================================================================

*(February 2018)*

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

* A method for sampling macrocyclic conformational space (see ``macrocycle`` mode
  below) has been added to **OMEGA**. This method uses a distance geometry approach
  to generate conformer ensembles for macrocyclic molecules.  It can also be applied
  to linear and small ring-containing molecules but is substantially slower than
  **OMEGA** ``classic``.

* **OMEGA** now includes five modes:
 
  -	``classic``: the original customizable **OMEGA** interface
  -	``macrocycle``: the conformer generator for macrocycles
  -	``rocs``: the optimal conformer generator for **ROCS**
  -	``pose``: the optimal conformer generator for pose prediction or docking
  -	``dense``: the optimal conformer generator for **FREEFORM**

  The classic mode is the original customizable **OMEGA** interface and the
  ``macrocycle`` mode uses an adaptation of the distance geometry method of
  Spellmeyer et al. [Spellmeyer-1997]. All other modes use fixed optimal parameters
  of the original **OMEGA** interface for various downstream applications:

    ::

      rocs:  -maxconfs = 50
      pose:  -maxConfRange = "200,800", -rangeIncrement = 8
      dense: -strictstereo = false, -ewindow = 15, -maxtime = 3600, -rms = 0.3,
             -maxrot = 20, -maxconfs = 20000

* A new command, ``oeomega``, has been added to invoke these modes. In addition, the
  original ``omega2`` command has been retained for backward compatibility. In all
  modes except ``macrocycle``, **OMEGA** automatically detects macrocycles and sends
  them to the fail file. The following are examples of ``oeomega`` commands to run
  these modes:

    ::

      oeomega classic -in drugs.smi -out drugs_classic.oeb.gz
      oeomega macrocycle -in drugs.smi -out drugs_macrocycle.oeb.gz
      oeomega rocs -in drugs.smi -out drugs_rocs.oeb.gz
      oeomega pose -in drugs.smi -out drugs_pose.oeb.gz
      oeomega dense -in drugs.smi -out drugs_dense.oeb.gz

* There are now two built-in torsion libraries in **OMEGA** in ``classic`` mode: the
  original PDB-derived torsion library and a new CSD-derived library, “Guba,” based on
  work from Roche using the frequency of particular angles found in the CSD for common
  torsion types [Guba-2016]. Introduced in the
  `2017.Oct Toolkits Release <https://docs.eyesopen.com/toolkits/cpp/releasenotes/releasenotes/index.html>`_,
  this torsion library contains more than 500 new entries and complements the existing
  library, which is primarily based on an analysis of structures found in the Protein
  Data Bank (PDB). A new flag, ``-torlibtype``, has been added to the **OMEGA**
  ``classic`` mode that allows users to specify which of the two libraries should be used.

* Two new options, ``macrocycle`` and ``nonmacrocycle``, have been added to the ``-filter``
  flag of **FILTER**. ``macrocycle`` is used to remove non-macrocycle molecules in the
  input file; ``nonmacrocycle`` is used to remove macrocycle molecules.

* Four new options, ``mmff94smod``, ``mmff94smod_NoEstat``, ``mmff94smod_Trunc``, and
  ``mmff94smod_Sheff``, have been added to both the ``-buildff`` and ``-searchff`` flags
  of **OMEGA** ``classic``. ``mmff94smod`` modifies the torsion interaction parameters of ``mmff94s``
  to produce the desired equatorial conformers for monosubstituted cyclohexanes.
  ``mmff94smod_NoEstat`` includes all ``mmff94smod`` terms except Coulomb interactions.
  ``mmff94smod_Trunc`` excludes both Coulomb interactions and the attractive part of Van
  der Waals interactions. ``mmff94smod_Sheff`` includes all ``mmff94smod terms``; the
  Sheffield solvation model is used during the calculation of energies for the conformers
  generated. ``mmff94smod_NoEstat`` is now the default for both ``-buildff`` and ``-searchff``.

* A Pan Assay Interference Compounds (``PAINS``) filter has been added to the ``-filter``
  flag of **FILTER** by adapting the supplementary material from the original [Baell-2010]_
  paper. The ``PAINS`` filter can be used as a prefilter set for screening or, more
  interestingly, as a post-processing filter to identify possible protein-reactive or
  other assay-confounding functionalities within hits. Any hits so identified will require
  more care to determine if the measured activity is valid.

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

* ``GZ`` files are now read correctly when used with ``-fixfile``. Previously,
  ``-fixfile`` would not be set and the command would proceed as a default **OMEGA**
  ``classic`` run.

* Both **FLIPPER** and **OMEGA** ``classic`` no longer flip 3D molecules if stereo is defined when
  using ``-flipper false``.

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

* ``-maxConfRange`` is now limited to 1 million to avoid out-of-memory crashes.

* **FLIPPER** now writes out to SMI files. Previously, stereo information was not
  supported in SMI format.

* **OMEGA** ``classic`` now fails if an empty torsion library is set to ``-settorlib``.

* **OMEGA** ``classic`` no longer removes zeros at the end of a prefix. For example,
  the prefix ``XXX.00100`` previously would be expressed as ``XXX.001``.

* For **FILTER**, ``-SF5`` groups no longer fail due to the ``-typecheck`` check.
  They may still fail for other reasons.

Platform support
---------------------------------------------------------------------------------

* Support for 64 bit Windows has been added.
* 32-bit Windows is no longer supported.
* Support for Ubuntu 14 and 16 has been added.
* Ubuntu 12 is no longer supported.
* Support for RedHat v7 has been added.
* RedHat v5 is no longer supported.
* Support for macOS 10.11, Sierra (10.12), and High Sierra (10.13) has been added.



.. _omega_releasenotes_301:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


OMEGA 3.0.1
================================================================================

*(August 2018)*

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

* A bug that caused memory leaks in **OMEGA** ``classic``, ``dense``, ``pose``,
  and ``rocs`` modes, has been fixed. Previously, a substantial memory leak was
  experienced when running **OMEGA** on a large database.

* **OMEGA** ``macrocycle`` no longer uses excessive memory for molecules with
  terminal heavy atoms.

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

* **OMEGA** ``classic`` no longer omits conformer titles when ``-includeInput``
  is set to true. Previously, the resulting conformers had no titles.

Other changes
---------------------------------------------------------------------------------

* Default values of ``-max_iterations`` and ``-maxconfs`` of **OMEGA**
  ``macrocycle`` have been changed to 2000 and 400 respectively.

OMEGA 3.1.0
================================================================================

*November 2018*

* This version of **OMEGA** has been built using **OEToolkits 2018.Oct**. The previous 
  version was built using **OEToolkits 2017.Feb**.

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

* A new ``fastrocs`` mode has been added to generate conformers for use in **FastROCS**.

* All available options in **OMEGA** ``classic`` mode are now also available in the
  ``pose``, ``rocs``, ``fastrocs``, and ``dense`` modes.

* Four new options, ``mmff94smod``, ``mmff94smod_NoEstat``, ``mmff94smod_Trunc``, and
  ``mmff94smod_Sheff``, have been added to the ``-buildff`` flag of :ref:`MakeFraglib <chapter_makefraglib>`.
  ``mmff94smod`` modifies the torsion interaction parameters of ``mmff94s``
  to produce the desired equatorial conformers for monosubstituted cyclohexanes.
  ``mmff94smod_NoEstat`` includes all ``mmff94smod`` terms except Coulomb interactions.
  ``mmff94smod_Trunc`` excludes both Coulomb interactions and the attractive part of Van
  der Waals interactions. ``mmff94smod_Sheff`` includes all ``mmff94smod terms`` along
  with the Sheffield solvation model for calculation of energies.

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

* Except for ``macrocycle``, all **OMEGA** modes are now driven by the
  same executable. Previously, each mode had its own executable.

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

* An issue that caused the ``-maxtime`` option to be not honored during 
  torsion search has been fixed.

* An issue that caused the ``-strictatomtyping`` option to fail to return ``False``
  has been fixed.

* An issue related to how the number of newly generated conformers per cycle
  is calculated for the ``macrocycle`` mode has been fixed.



OMEGA 3.1.1
================================================================================

*May 2019*

* This version of **OMEGA** has been built using **OEToolkits 2019.Apr**. The previous
  version was built using **OEToolkits 2018.Oct**.

New Features
--------------------------------------------------------------------------------
Users can now use ``oez`` as the output format for **OMEGA**.

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

* The default for ``-rotorOffsetCompress`` is set to ``true`` for all modes.

* An issue that caused **OMEGA** to generate conformers
  with an occasional Coulombic collapse in the ``macrocycle mode`` for conformations of zwitterionic molecules
  has been fixed.

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

* The default for ``-enumNitrogen`` has been changed from ``true`` to ``unspecified``
  so that any user-specified stereo information is not lost by default.

* The flag ``-skip`` has been removed from :ref:`MakeFraglib <chapter_makefraglib>`.

* **OMEGA** calculations no longer repeat an error message.


OMEGA 3.1.2
================================================================================

*Nov 2019*

* This version of **OMEGA** has been built using **OEToolkits 2019.Oct**. The previous
  version was built using **OEToolkits 2019.Apr**.

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

* An issue that caused :ref:`MakeFraglib <chapter_makefraglib>` to not properly handle fullerene-like molecules
  has been fixed.

* :ref:`MakeFraglib <chapter_makefraglib>` no longer hangs when ``-progress`` is set to ``percent``.

* An occasional segmentation fault in :ref:`MakeFraglib <chapter_makefraglib>` to fail to generate conformers
  for a fragment due to lack of atom typing, has been fixed.

* A memory issue that sometimes caused  :ref:`MakeFraglib <chapter_makefraglib>` to take too much memory has been fixed.

* **FILTER** now properly handles filter files with singular MIN or MAX values.


.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _omega_citation:

************
Citation
************

.. note:: To cite **OMEGA**, please use the following:

    OMEGA |omega_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T.
**Conformer Generation with OMEGA: Algorithm and Validation Using High 
Quality Structures from the Protein Databank and the Cambridge Structural Database.**
*J. Chem. Inf. Model.* **2010**, *50* (4), 572–584. DOI: 10.1021/ci100031x

Hawkins, P.C.D; Nicholls, A. **Conformer Generation with OMEGA: Learning from the Data Set and the
Analysis of Failures.** *J. Chem. Inf. Model.* **2012**, *52*, (11), 2919–2936.
DOI: 10.1021/ci300314k



.. OpenEye Pka-Prospector
.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



#########################################
PICTO |picto_version|
#########################################
             
.. toctree::
   :maxdepth: 2

   introduction
   picto/picto
   releasenotes/index
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt






.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _picto_introduction:

************
Introduction
************

==============
Overview
==============

**PICTO** is a Graphical tool for drawing, editing and depiction of molecules in 2-dimensions.

==============
Applications
==============

The **PICTO** distribution contains 1 application:

  :ref:`PICTO <chapter_picto_introduction>`

  * 2D molecule sketcher and viewer.


.. _chapter_picto:

PICTO
=====

.. toctree::
   :maxdepth: 2

   picto_overview
   2dsketcher
   smarts
   implexplHydro
   atomlabeling


.. |product|        replace:: PICTO

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_picto_introduction:

=============
Overview
=============

**PICTO** is a Graphical tool to sketch new molecules, as well as view and modify 
existing molecules. The focus is primarily on small molecules, but it is not limited to small 
molecules. 2D molecular depictions in **PICTO** are provided using OpenEye’s 
**OEDepict** toolkit. 

**PICTO** is comprised of three sections: A main sketcher with a toolbar, a secondary sketcher 
for SMARTS queries, and a text based input and outputs section. The main sketcher is directly 
correlated to the text based input and output section. 

The input textbox can depict molecules utilizing SMILES, InChI, or a compound name. Beneath the 
input textbox are three outputs: Isomeric SMILES, InChI, and Compound Name. The Compound Name 
output has five naming styles: OpenEye (default), IUPAC, Traditional, Systematic, and CAS. 


.. |product|        replace:: PICTO

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_picto_sketcher:

=============
Sketcher
=============

The **PICTO** sketcher window (populating the left side of **PICTO**) contains an editing 2D sketching environment,  
a 1D text entry mechanism, a textbox displaying the Isomeric SMILES depicted 
on the 2D sketching environment, a textbox displaying the compound name. 
The 1D input mechanism provides a very fast way to specify a new molecule or get started 
with new molecule creation. The 1D input mechanism supports SMILES, IUPAC and common names, as well 
as FASTA sequences for small peptides (sequence must be prefixed by a leading 
angle bracket (>) character). Disconnected fragments can be specified on the 1D 
input line by entering a vertical bar (|) character between the entries.  Once a 
valid molecule has been specified in the 1D area, that molecule will be depicted in 
the 2D sketching area. The 2D sketching environment can also be manipulated using the 
toolbar on the left (this will cause the input in the entry mechanism to display the Isomeric SMILES). 

A basic overview of the 2D sketcher can be seen in 
:ref:`Figure: 2D Sketcher<figure_sketcher>`

.. _figure_sketcher:

.. figure:: /_images/2D_sketcher.png
   :width: 600
   :align: center

   **2D Sketcher**

.. list-table::
  :widths: 15 50
  :header-rows: 1

  * - Icon
    - Description (scroll right with this table's scroll bar)
  * - .. image:: ../images/pencil.png
    - **Pencil:**  This is the default drawing tool.  With the pencil icon selected (highlighted), click in the
      main sketcher window to start drawing a new molecule.

      Clicking on an atom in
      the main sketcher window will incrementally build up a carbon chain.

      The attachment points
      are highlighted in orange.  Clicking on a bond will toggle the bond order.

      This tool can also be used to close rings.  Click on the first 
      atom and drag to the second atom where the ring will close.

      Hovering the mouse over an atom or bond highlights it orange.  Right-click on the highlighted 
      atom to access a right-click menu, which allows the user to
      *Set Element*, *Set Formal Charge* or *Delete* the selected atom/bond.

      If a bond is highlighted, then the
      right-click menu offers an option to *Set Bond Order*.

      There are also options to
      *Attach...* (through an atom) or *Fuse...* (through an atom or bond) a functional group.

      In these cases, a secondary dialog opens
      in which a SMILES string can be input of the group to be attached or fused. 
  * - .. image:: ../images/bond.png
    - **Bond order:**  
      Clicking on a bond in the main sketcher window will cycle through the
      available bond orders for that bond.

      Bond order can also be set through the *Set Bond Order* option of the right-click menu.

      Hovering the mouse over an individual bond will temporarily highlight it orange
      and the right-click menu will operate on that bond only.

      If multiple bonds are
      selected (and therefore highlighted orange) using the *Selection* tool (below), then they
      will **all** be set to the new bond order using *Bond Order* in the right-click menu.

      Available options are 0–4, where 0 will break the bond.
  * - .. image:: ../images/element.png
    - **Element:**  
      Click on the small arrow to open a dropdown menu and select from some commonly 
      used elements.

      Clicking on an atom in the main 2D sketcher window will cause
      that atom to be changed to the selected atom type.

      In addition to the
      commonly used atoms there is an "X" dummy atom type.

      Clicking the "..." option in
      the list opens a full periodic table of the elements from which any element 
      can be selected.

      This icon shows an image of the currently active atom type.  The default is 
      "C".

      Atoms types can also be set through the *Set Element* option of the right-click menu.

      Hovering the mouse over a single atom will temporarily highlight it orange
      and the right-click menu will operate on that atom only.

      If multiple atoms are
      selected (and therefore highlighted orange) using the *Selection* tool (below), then they
      will **all** be set to the same atom type using *Set Element* in the right-click menu.
  * - .. image:: ../images/charge.png
    - **Charge:**  Click on the small arrow to open a dropdown and select the formal 
      charge for an atom.  Options available are -2, -1, 0, +1, +2.

      With the
      charge icon active (highlighted white), clicking on any atom in the main
      sketcher window will modify the atom to have the currently selected charge.

      This icon displays an image of the currently active charge.  
      The default is "-2".

      Formal charge can also be set through the *Set Formal Charge* option of the right-click menu.

      Hovering the mouse over an individual atom will temporarily highlight it orange,
      and the right-click menu will operate on that atom only.

      If multiple atoms are
      selected (and therefore highlighted orange) using the *Selection* tool (below) then they
      will **all** be set to the new formal charge using *Set Formal Charge* in the right-click menu.
      This method provides a wider range of charge values than can be accessed using the *Charge* icon.
  * - .. image:: ../images/rings.png
    - **Rings:**  
      Click on the small arrow to open a dropdown menu and select from some commonly 
      used rings, such as benzene, cyclopropane and cyclohexane.

      The selected
      ring can be added to the growing molecule multiple times.

      The attachment atom or fusion bond
      is highlighted in orange, and alternative fusion options can be accessed using
      the mouse scroll wheel.  

      This icon shows an image of the currently active ring template.  The default is benzene.
  * - .. image:: ../images/templates.png
    - **Templates:**  
      Click on the small arrow to open a dropdown menu and select from numerous 
      predefined template functional groups, linkers and rings.

      There is also an
      option to define a Custom functional group.  This opens a new dialog into 
      which a SMILES string can be input.

      The selected functional group, linker or
      ring can be added to the growing molecule multiple times.

      The attachment atom or fusion bond
      is highlighted in orange and alternative fusion options can be accessed using 
      the mouse scroll wheel.

      This icon shows an image of the currently active functional group, linker or 
      ring.  The default is "C". 

      With the default "C" functional group selected clicking on an atom in the 
      main sketcher window will build up a carbon chain.  This tool can also be 
      used to close rings.  Click on the first atom and drag to the second atom 
      where the ring will close.
  * - .. image:: ../images/stereo.png
    - **Stereochemistry:**  Click on the small arrow to open a dropdown and select 
      atom and bond CIP stereochemistry options.

      Available options are R and S
      for chiral atoms and E or Z for chiral bonds.  There is also an option to 
      invert the current stereochemistry.

      This icon displays an image of the currently active option.  
      The default is "Invert".

      If no stereochemistry is already set, then clicking an atom with the *Invert* option
      selected will initially set the stereochemistry to R and subsequent clicks with *Invert* will
      toggle between R and S.

      In the case of bonds where no stereochemistry is already set the
      *Invert* option will initially set the stereochemistry to E and then toggle between E and Z.
      Thus *Invert* can be considered a 'one stop shop'.
  * - .. image:: ../images/select.png
    - **Select:**  With the arrow icon highlighted, drag to draw a loop around the
      atoms to be selected or Shift-click or Ctrl-click to incrementally select 
      multiple atoms and/or bonds.  The selected atoms and bonds will be 
      highlighted in orange.  

      A right-click menu allows the user to *Set Element*, *Set Formal Charge* 
      or *Delete* the selected atom(s).

      This operation acts on **all** the selected atoms, that is, they would all get the same charge.

      If only bonds are selected, then the
      right-click menu offers an option to *Set Bond Order*.

      There are also options to
      *Attach...* (through an atom) or *Fuse...* (through an atom or bond) a functional group.  
      In these cases a secondary dialog opens 
      in which a SMILES string can be input of the group to be attached or fused.
  * - .. image:: ../images/wand.png
    - **Clean up the display:** This tool is useful after portions of the molecule have been 
      deleted, especially if a ring has been cleaved.

      It uses an OEDepict algorithm to
      redraw the molecule according to an internal set of rules.
  * - .. image:: ../images/undo.png
    - **Undo:**  Clicking on this icon will undo the last action in the main sketcher window.  
      Repetitive use will undo actions further back in the history.

      *Ctrl-Z* is a keyboard
      shortcut that can also be used.
  * - .. image:: ../images/eraser.png
    - **Eraser:**  Delete atoms and/or bonds by selecting the eraser tool and clicking on the 
      atom or bond to be deleted.

      Atoms and bonds can also be deleted through the *Delete* option of the right-click menu.

      Hovering the mouse over a single atom or bond will temporarily highlight it orange
      and the right-click menu will operate on that atom/bond.

      If multiple atoms/bonds are
      selected (and therefore highlighted orange) using the *Selection* tool (below), then they
      will **all** be deleted using *Delete* in the right-click menu.
  * - .. image:: ../images/reaction.png
    - **AAMapping:**  This tool allows for AAMapping of atoms in a molecule or reaction-based SMILES.

      When this tool is toggled, the atom labeling will switch over to display the AAMap indices.

      A left click on an atom will add an AAMap index to the molecule, and a right click to any 
      atom will erase the AAMap index from that atom. The input text box and isomeric SMILES output
      will reflect the AAMapping displayed on the sketcher. 

      Atom-to-atom mapping is available when a reaction-based SMILES is depicted.

      Clicking on an atom
      on the reactant side and dragging to an atom on the product side will give both of the atoms 
      the same AAMap index.

      If either of these atoms are already mapped then the other atom will
      reflect that atom's AAMap index, but one of those atoms must not be mapped.

      The stretchy
      straight line that appears when dragging from atom to atom will highlight when a second atom is 
      selected.

      Alternative product mapping can be achieved by dragging a mapped reactant atom to
      a second product atom that is not mapped or by dragging a mapped product atom to another 
      product atom that's unmapped.

      A right click on any atom with atom-to-atom mapping index will
      erase the AAMap index from all atoms with the same AAMap index.

**PICTO** can open multiple files formats for depiction in the sketcher. Depicted molecules in the sketcher 
can be saved to one of various file formats as well. These options can be found in the file tab of the menubar. 



.. |product|        replace:: PICTO

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_picto_smarts:

=============
SMARTS
=============

The **PICTO** SMARTS window (populating the right side of **PICTO**) contains a basic 2D sketching environment, 
a tab mechanism to cycle through the different pattern matching searches, a SMARTS query entry mechanism, a textbox 
displaying the SMARTS pattern, a spinbox for matches, a checkbox to display all matches, and an inverse checkbox to 
see all atoms that did not match. Once a valid SMARTS query is entered, it will be applied to the molecule in the 
main sketcher and the first match will be highlighted. If an invalid SMARTS query is entered, the text will display red. 
SMARTS queries can be generated utilizing **Send Selected to SMARTS** in the Edit tab of the menubar if any portion of 
a molecule is selected in the main sketcher. The matches can be cycled through using the spinbox and pressing the Enter 
key after entering a SMARTS query will set focus to the spinbox, allowing the use of the arrow keys to cycle through matches. 
There are three pattern matching searches available in **PICTO**: Substructure Search, Maximum Common Substructure Search, 
and Clique Search. 

The substructure search (SubSearch) identifies matches by utilizing the query molecule as a submolecule that may be found 
in the molecules depicted in the main sketcher. A basic overview of a SMARTS query using a basic substructure search can be seen in 
:ref:`Figure: SMARTS<figure_smarts>` 

.. _figure_smarts:

.. figure:: /_images/smarts.png
   :width: 600
   :align: center

Toggling the All Matches checkbox will highlight every match produced by the search and give access to the Inverse checkbox. 

.. _figure_allmatches:

.. figure:: /_images/allMatches.png
   :width: 600
   :align: center

Every atom that didn't match will be highlighted when the Inverse checkbox is checked. 

.. _figure_inverseallmatches:

.. figure:: /_images/inverseAllMatches.png
   :width: 600
   :align: center

**PICTO** defaults to display unique matches, but all matches including duplicates will populate the matches spinbox when 
unchecking the Unique Search checkbox. The Unique Search checkbox is only available in Substructure Search and Maximum Common 
Substructure Search.

Maximum Common Substructure (MCS) Search identifies the largest match between the query molecule and the molecules depicted in the main 
sketcher. The MCS tab contains a dropdown for the search method, a dropdown for the scoring method, a spinbox to specify the minimum atoms 
needed for a match, and the unique search checkbox. The default search method is Exhaustive, which is a more comprehensive method. The other 
search method available is approximate, which is very fast. 

A basic overview of a SMARTS query using a basic maximum common substructure search can be seen in 
:ref:`Figure: MCS Search<figure_smartsMCS>`

.. _figure_smartsMCS:

.. figure:: /_images/smartsMCS.png
   :width: 600
   :align: center

The approximate method is based on traversing through pre-defined paths of the query structure and trying to map the visited query atoms 
into target atoms. Because these pre-defined paths represent only a fraction of all possible paths of a compound, it is not guaranteed that 
the approximate method can find the largest and all common substructures. Significant difference between the detected matches of the two methods 
could exist in cases when the query or target structure contains complex ring systems (fused or bridged) or stereo centers. However, comparing 
the two methods for thousands of structures revealed that these cases are rare and the approximate method provides a good trade-off between 
identifying MCS matches accurately and doing it 3 to 6 times faster than the exhaustive method.

.. _figure_mcss_approximate:

.. figure:: /_images/OEMCSSearchApproximate.png
   :scale: 100
   :align: center

   **Approximate MCSS**

.. _figure_mcss_exhaustive:

.. figure:: /_images/OEMCSSearchExhaustive.png
   :scale: 100
   :align: center

   **Exhaustive MCSS**

There are four scoring methods available in **PICTO** are Max Atoms, Max Bonds, Max Atoms Complete Cycle, and Max Bonds Complete Cycle (default).

**Max Atoms** orders the maximum common substructure matches by the maximum number of atoms included in the graph match. If two matches have the same 
number of atoms, then the tie is split based on the number of bonds contained in the match.

.. _figure_mcss_maxatoms:

.. figure:: /_images/OEMCSSearchOEMCSMaxAtoms.png
   :scale: 100
   :align: center

   **Max Atoms**

**Max Bonds** orders the maximum common substructure matches by the maximum number of bonds included in the graph match. If two matches have the same 
number of bonds, then the tie is split based on the number of atoms contained in the match.

.. _figure_mcss_maxbonds:

.. figure:: /_images/OEMCSSearchOEMCSMaxBonds.png
   :scale: 100
   :align: center

   **Max Bonds**

**Max Atoms Complete Cycle** is the same as Max Atoms with the addition of penalizing cyclic query bonds that are not mapped to any target bonds, 
thereby giving priority to matches which contain complete cycles common to both the pattern and the target structure. 

.. _figure_mcss_maxatomscc:

.. figure:: /_images/OEMCSSearchOEMCSMaxAtomsCompleteCycles.png
   :scale: 100
   :align: center

   **Max Atoms Complete Cycle**

**Max Bonds Complete Cycle** is the same as Max Bonds with the addition of penalizing cyclic query bonds that are not mapped to any target bonds, 
thereby giving priority to matches which contain complete cycles common to both the pattern and the target structure. 

.. _figure_mcss_maxbondscc:

.. figure:: /_images/OEMCSSearchOEMCSMaxBondsCompleteCycles.png
   :scale: 100
   :align: center

   **Max Bonds Complete Cycle**

The **Min Atoms Matched** spinbox is utilized to add a constraint which sets the minimum number of atoms required of a match to be returned. 

Clique Search (CS) identifies all possible corresponding matches between the query molecule and molecules depicted in the main sketcher. The CS 
tab contains a dropdown for the scoring method and a spinbox to specify the minimum atoms needed for a match. A basic overview of a SMARTS query 
using a basic clique search can be seen in :ref:`Figure: Clique Search<figure_smartsCS>`. The main difference between this figure and the one above 
is the amount of matches.

.. _figure_smartsCS:

.. figure:: /_images/smartsCS.png
   :scale: 40
   :align: center

.. |product|        replace:: PICTO

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_picto_implexplHydro:

============================
Implicit/Explicit Hydrogens
============================

Implicit hydrogens are the hydrogens that are associated with the parent atom, they are not stored as an atom. 
Explicit hydrogens are the hydrogens that are specified by the user, they are stored as atoms. 
The default search for SMARTS is conducted using implicit hydrogens. The two options can be toggled at the bottom of **PICTO** 
by checking the Retain Explicit Hydrogens checkbox. Using explicit hydrogens allows the user to refine their search for a specific substructure, 
while implicit hydrogens gives more of a broad search. 

An example of a benzene and a SMARTS query with implicit hydrogens can be seen in 
:ref:`Figure: Implicit Hydrogens<figure_impl>`

.. _figure_impl:

.. figure:: /_images/impl.png
   :width: 600
   :align: center

There are two way to input explicit hydrogens in SMILES notation (**[H]** and **([H])**), each one is dependent on where the hydrogen is added into the input. 
An example of a chloroethane and a SMARTS query with explicit hydrogens presented in the SMILES input can be seen in 
:ref:`Figure: SMILES inputted Explicit Hydrogens<figure_explSMILES>`

.. _figure_explSMILES:

.. figure:: /_images/explSMILES.png
   :width: 600
   :align: center

Changes to the sketcher will take in account any existing explicit hydrogens depicted, and hydrogens can be added using the **Element** tool which will 
be reflected in the Input text box and the Isomeric SMILES output when the Retain Explicit Hydrogens checkbox is checked. 

When opening a file with explicit hydrogens, **PICTO** will automatically check the Retain Explicit Hydrogens checkbox. 
:ref:`Figure: File opened Explicit Hydrogens<figure_explFile>` displays what occurs after opening a file with explicit hydrogens. The explicit hydrogens will 
be visible in the sketcher, the SMILES input, and Isomeric SMILES output. 

.. _figure_explFile:

.. figure:: /_images/explFile.png
   :width: 600
   :align: center

When selecting the atoms of a molecule in the Isomeric SMILES output, the SMILES input will :ref:`reset to the implicit hydrogen based isomeric SMILES<SMILES_reset_summ>` 
of the molecules depicted. The depiction in the sketcher will also reset to display the molecule without explicit hydrogens, and the Retain Explicit Hydrogens 
checkbox will be unchecked. 

.. _SMILES_reset_summ:

.. list-table::
  :widths: 50 50
  :header-rows: 0

  * - .. image:: ../images/explSMILES.png
    - .. image:: ../images/explSmilesToImpl.png
  * - **Molecule with Explicit Hydrogens in SMILES Input**
    - **Molecule Reset due to Selection**
  * - .. image:: ../images/explFile.png
    - .. image:: ../images/explFileToImpl.png
  * - **Molecule with Explicit Hydrogens in a File**
    - **Molecule Reset due to Selection**


.. |product|        replace:: PICTO

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_picto_atomlabeling:

==============================================================================
Atom Labeling, Aromatic Displays, Aromatic Modeling, and other Displays
==============================================================================

There are multiple ways to display different aspects of chemistry and other ways to manipulate the molecule display in **PICTO**. In the view menu of **PICTO** 
the depiction of aromatics can be swapped between Kekule, Circle, and Dashed, and the molecule can be labelled based off certain 
atomic labels: No Atom Labeling, Atom Stereochemistry, Atom Locants, Atom Indices, and Atom AAMaps. Aromatic modeling can be cycled through OpenEye, Daylight, 
Tripos, MMFF, and MDL when the aromatic display is set to either Circle or Dashed. The different aromatic displays can be seen in :ref:`Figure: Aromatic Displays<aromaticDisplay>`. 

.. _aromaticDisplay:

.. list-table::
  :widths: 50 50
  :header-rows: 0

  * - .. image:: ../images/aromaticKekule.png
    - .. image:: ../images/aromaticCircle.png
  * - **Kekule**
    - **Circle**
  * - .. image:: ../images/aromaticDashed.png
    -
  * - **Dashed**
    -

The different atom labels can be seen in :ref:`Figure: Atom Labels<atomLabel>`. 

.. _atomLabel:

.. list-table::
  :widths: 50 50
  :header-rows: 0

  * - .. image:: ../images/noAtomLabel.png
    - .. image:: ../images/atomStereo.png
  * - **No Atom Labeling**
    - **Atom Stereochemistry**
  * - .. image:: ../images/atomLocant.png
    - .. image:: ../images/atomIndices.png
  * - **Atom Locants**
    - **Atom Indices**
  * - .. image:: ../images/atomAAMap.png
    -
  * - **Atom AAMapping**
    -

The different aromatic models can be seen in :ref:`Figure: Aromatic Models<aromaticModel>`. 

.. _aromaticModel:

.. figure:: /_images/OEAssignAromaticFlags_Difference.png
   :scale:  100
   :align:  center

Since these models define aromaticity rules differently, the Isomeric SMILES output will vary based off the applied aromatic model. 
When cycling through the different aromatic models for the molecule above the Isomeric SMILES will output the following: 

.. code-block:: bash

   OpenEye  : c1c[nH]c(cc1=O)c2cocc2c3cncnc3
   Daylight : c1c[nH]c(cc1=O)c2cocc2c3cncnc3
   Tripos   : c1c(cncn1)C2=COC=C2C3=CC(=O)C=CN3
   MMFF     : c1c(cncn1)c2cocc2C3=CC(=O)C=CN3
   MDL      : c1c(cncn1)C2=COC=C2C3=CC(=O)C=CN3

The following table demonstrates the differences between the five available aromaticity models. 

.. figure:: /_images/OEAssignAromaticFlags_Table.png
   :scale:  100
   :align:  center

There are three other displays that can be used together to manipulate the molecule display in the sketcher. 
:ref:`Figure: Fit in Window<figure_fitInWindow>` displays the molecule when Fit in Window is toggled. :ref:`Figure: Super Atom<superAtom>` 
displays the difference in the sketcher between Super Atom being toggled. :ref:`Figure: Hide/Show Hydrogens<showHideHydro>` displays the molecule 
with and without the hydrogens depicted in the sketcher. The hydrogens can be toggled with the checkbox at the bottom of **PICTO** labelled 
Hide Hydrogens. 

.. _figure_fitInWindow:

.. figure:: /_images/FitToWindow.png
   :width: 600
   :align: center

.. _superAtom:

.. list-table::
  :widths: 50 50
  :header-rows: 0

  * - .. image:: ../images/noSuperAtom.png
    - .. image:: ../images/superAtom.png
  * - **Without Super Atom**
    - **With Super Atom**

.. _showHideHydro:

.. list-table::
  :widths: 50 50
  :header-rows: 0

  * - .. image:: ../images/showHydro.png
    - .. image:: ../images/hideHydro.png
  * - **Showing the Hydrogens**
    - **Hiding the Hydrogens**

.. _picto_releasenotes:

Release History
===============

.. toctree::

   version5_1_5
   version5_1_4
   version5_1_3
   version5_1_2
   version5_1_1
   version5_1_0
   version4_6_0
   version4_5_4
   version4_5_3
   version4_5_2
   version4_5_1
   version4_5_0


#################
PICTO 5.1.4
#################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************



OEDepict TK 2.6.0
================================================================================

Minor internal improvements have been made.



#############################
PICTO 5.1.3
#############################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


OEDepict TK 2.5.6
================================================================================

Minor internal improvements have been made.



PICTO  5.1.2
================================================================================

New features
--------------------------------------------------------------------------------
* A feature has been added that allows a user, in the view preferences, to increase the limit on
  the maximum number of atoms in a molecule when reading or writing 
  in molecule-specific file formats.



OEDepict TK 2.5.5
================================================================================

Minor internal improvements have been made.




PICTO  5.1.1
================================================================================

Minor internal improvements have been made.



OEDepict TK 2.5.4
================================================================================

Minor internal improvements have been made.




PICTO  5.1.0
================================================================================

New features
--------------------------------------------------------------------------------
* The inverse checkbox can now be toggled with individual matches, 
  highlighting all atoms that were not a hit on a singular molecule.

* A new chemistry drop-down menu adds support for reaction automapping
  of the reactants and products based on Maximum Common Substructure Search.

Major bug fixes
--------------------------------------------------------------------------------
* **PICTO** now properly handles reaction changes through the sketcher.

* An issue where **PICTO** highlighted bonds that didn't have matches
  with the substructure search was fixed.

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

* Minor changes were made to the pop-up window for a missing license file.



OEDepict TK 2.5.3
================================================================================

Minor internal improvements have been made.




PICTO  4.6.0
================================================================================

*Fall 2022*

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

* The ability to display explicit hydrogens in the sketcher from input :term:`SMILES`, and when opening files with explicit hydrogens, has been added.

* Aromatic views for Kekule, Circle, and Dashed has been added.

* A "Fit in Window" feature has been added.

* The ability to toggle display hydrogens has been added.

* A toggle to display super atoms has been added.

* The ability to display atom labels based on stereo, locants, indices, and atom annotation maps has been  added.

* When an atom is clicked in the sketcher, the input cursor will move to that atom in the :term:`SMILES`  to allow easier modification of the :term:`SMILES`  
  input at a specific location of the molecule.

* Deleting mulitple molecules when selecting with the eraser is now available.

* The ability to highlight multiple molecules when selecting through :term:`SMILES`  input has been added.

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

* PICTO now properly highlights selected :term:`SMILES`  input in sketcher.

* :term:`SMARTS` queries and Send to :term:`SMARTS` now works with separate molecules (separated by a pipe in the :term:`SMILES` input).

* Files with explicit hydrogens will now display the explicit hydrogens and allows a query to match with the explicit hydrogens.

Minor bug fixes
--------------------------------------------------------------------------------
* An issue where Compound Name displays were not properly formatted has been fixed.

* An issue where atoms with an atomic number of 119 and above were not displayed with their atomic number has been fixed.

* Highlighted atoms from :term:`SMARTS` query matches now resets after the :term:`SMARTS` query is deleted.

* When the selection in sketcher is unselected, the corresponding input selection in the :term:`SMILES` will now be unselected.

* The checkbox for retaining explicit hydrogens now resets when the molecule displayed as :term:`SMILES` has explicit hydrogens converted to implicit, which happens when selections are made in the :term:`SMILES` .


OEDepict TK 2.5.1
======================

Minor internal improvements have been made.





PICTO  4.5.4
================================================================================

*Spring 2022*

* Minor internal improvements have been made.


OEDepict TK 2.5.0
================================================================================

* Minor internal improvements have been made.




PICTO  4.5.3
================================================================================

*Fall 2021*

* Minor internal improvements have been made.



OEDepict TK 2.4.7
================================================================================

*Fall 2021*

* Minor internal improvements have been made.
  



PICTO  4.5.2
================================================================================

*July 2021*

* Minor internal improvements have been made.


OEDepict TK 2.4.6
================================================================================

*July 2021*

Minor internal improvements have been made.






PICTO  4.5.1.0
================================================================================

*Fall 2020*

* Minor internal improvements have been made.

OEDepict TK 2.4.5
================================================================================

*Fall 2020*

New features
--------------------------------------------------------------------------------
* A new function, :ref:`OEGetLabelPosition <OEDepict_OEGetLabelPosition>`, that identifies the position where atoms labels are added.

* Approximately 40 new protective groups have been added to the namespace
  :ref:`OEProtectiveGroupStyle <OEDepict_OEProtectiveGroupStyle>`.

* A new function, :ref:`HasProtectiveGroupStyle <OEDepict_HasProtectiveGroupStyle>`, has
  been added that determines whether a given protective group style has been set
  in :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>`.

* The function :ref:`GetProtectiveGroupStyle <OEDepict_GetProtectiveGroupStyle>`
  has been deprecated. It can no longer be used to determine if multiple protective
  group styles from :ref:`OEProtectiveGroupStyle <OEDepict_OEProtectiveGroupStyle>` have been set.
  :ref:`HasProtectiveGroupStyle <OEDepict_HasProtectiveGroupStyle>`
  can now be used instead.

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

* An issue that caused :ref:`OEPrepareAlignedDepiction <OEDepict_OEPrepareAlignedDepiction>` to generate incorrect stereo depictions when
  :ref:`SetClearCoords <OEDepict_SetClearCoords>`
  was set to ``false`` has been fixed.

* Figures have been added to show depiction with and without the new protective groups
  to :ref:`OEProtectiveGroupStyle <OEDepict_OEProtectiveGroupStyle>`.


.. _picto_releasenotes_450:

PICTO 4.5.0
================================================================================

*Spring 2020*

* This version of **PICTO** has been built using **OEToolkits 2020.0**.

* This is the first release of **PICTO** as an independent application suite and
  as part of the **OpenEye Applications** bundle.  Previously, **PICTO**
  was an integral part of **VIDA**.


.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _picto_citation:

**************
Citation
**************

.. note:: To cite PICTO please use the following:

    PICTO |picto_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



.. OpenEye Pka-Prospector
.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



#########################################
pKa-Prospector |pka-prospector_version|
#########################################
             
.. toctree::
   :maxdepth: 3

   introduction
   pka/pka
   releasenotes/index
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt






.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _pka_introduction:

************
Introduction
************

==============
Overview
==============

**pKa-Prospector** is a tool for obtaining the pKa value of compounds
based on the primary data available in the database.

==============
Applications
==============

The **pKa-Prospector** distribution contains 1 application:

  :ref:`pKa-Prospector <chapter_pka_prospector>`

  * Assesses the pKa value of compounds.


.. _chapter_pka_prospector:

pKa-Prospector
==============

.. toctree::
   :maxdepth: 2

   pka_overview
   pka_quickstart
   pka_query
   pka_property
   pka_search
   pka_results
   pka_prefs
   pka_report
   pka_menu
   pka_data
   pka_import_db


.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_pka_introduction:

=============
Overview
=============

These pKa databases represent the extremely careful conversion of IUPAC's extensive compilations of experimental pKa values of organic acids and bases (in aqueous solution) from book form into fully curated computer-readable data.

**Data Sources**

   * Base 1 (3775 molecules, 8766 pKas) Dissociation Constants of Organic Bases in Aqueous Solution, by D.D. Perin
   * Acid 1 (1063 molecules, 2893 pKas) Dissociation Constants of Organic Acids in Aqueous Solution, by G. Kortum, W. Vogel and K. Andrussow
   * Base 2 (4275 molecules, 7844 pKas) Dissociation Constants of Organic Bases in Aqueous Solution, Supplement 1972, by D.D. Perin
   * Acid 2 (4584 molecules, 10912 pKas) Ionisation Constants of Organic Acids in Aqueous Solution, by E.P. Serjeant and Boyd Dempsey

The actual conversion process was done entirely by hand by Tony Slater 
(http://www.pkadata.com/) of pKaData Limited to ensure accuracy and consistency.

.. figure:: /_images/splash.png
   :scale: 75
   :align: center
   :alt: pKa Prospector
   
   **pKa Prospector**

The **pKa-Prospector** application provides a tool for users primarily interested in their own compound to find what the primary data may say about their compound or model compounds closely analogous to their molecule of interest.



.. _chapter_pka_quickstart:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


*****************************
QuickStart
*****************************

Open a molecule
---------------

.. _figure_openfile:

.. figure:: /_images/openfile.png
   :scale: 75
   :align: center
   :alt: Open a File
   
   **Open a file**

Click the button next to where it says "Open a file..." :ref:`Figure: Open a file<figure_openfile>`.
It does the default search, which is an "Analog Search", automatically. Or you can paste a SMILES
string directly into the query window and it will again run the "Analog Search" automatically.

Edit the Molecule
-----------------

.. _figure_editor:

.. figure:: /_images/sketcher.png
   :scale: 50
   :align: center
   :alt: Editor

   **Editor**

Double click the query molecule in the upper left corner of the application.
This will open the Editor.
You can edit the molecule with the building blocks or you can type in a SMILES 
or common name of a molecule.
Hitting the OK button will make this your new query molecule and perform an
Analog Search. :ref:`Figure: Editor <figure_editor>`.

Perform a Substructure Search
-----------------------------

.. _figure_lasso:

.. figure:: /_images/lasso.png
   :scale: 50
   :align: center
   :alt: Lasso a Substructure
   
   **Lasso a Substructure**

.. _figure_subsearch:

.. figure:: /_images/subsearch.png
   :scale: 50
   :align: center
   :alt: Sub Structure Search
   
   **Substructure Search**

Lasso with the mouse a sub portion of the molecule you wish to use for a Substructure Search. :ref:`Figure: Lasso a Substructure<figure_lasso>` 
The results will now be highlighted with the matching substructure. :ref:`Figure: Substructure Search<figure_subsearch>`

Open up a Result Report 
-----------------------

.. _figure_report:

.. figure:: /_images/report.png
   :scale: 50
   :align: center
   :alt: Result Report
   
   **Result Report**

Double click a results table on the right hand column of the results viewer.
This will display a result report. Clicking the blue links will jump to the detailed
report of that particular measurement. :ref:`Figure: Result Report<figure_report>`

Save it to PDF
--------------

Click the Save to PDF button to save the report to a PDF file.
There are additional export options under the file menu.



.. _chapter_pka_query:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


================
Query Molecule
================

.. index:: Query Molecule

The upper left contains a depiction of the current query molecule. A query molecule can be loaded by opening
a file from the file combo box directly below the depiction, pasting from your favorite molecule editor, 
or by double clicking the depiction which launches the editor. The editor can accept
both common molecule names and SMILES strings.

.. figure:: /_images/sketcher.png
   :scale: 50
   :align: center
   :alt: Editor

   **Editor**

Once a molecule is loaded the application performs an "Analog Search." The individual ionizable regions of the query
molecule are highlighted. After the "Analog Search" is performed the ionizable regions become clickable, indicated by
the highlighting color becoming more saturated when the mouse is hovered above. Clicking on a given ionizable region 
will limit the results to molecules that match that particular ionizable substructure. Clicking in the negative white
space will return the full list of results.

The Query Molecule will persist between sessions.

Tautomers
---------

.. index:: Tautomers

.. figure:: /_images/tautomer.png
   :scale: 75
   :align: center
   :alt: Tautomer Selection
   
   **Tautomer Selection**

If pKa-Prospector detects a more common tautomer for a given query molecule it will prompt the user to
use the more common tautomer. Often search results will improve if the more common tautomer is used as 
the query molecule.


.. _chapter_pka_property:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


==================
Property Filters
==================

.. index:: Property Filters

.. figure:: /_images/filters.png
   :scale: 75
   :align: center
   :alt: Property Filters
   
   **Property Filters**

pKa and Temperature
-------------------

The property filters below the query molecule depiction allow for filtering of the results that are displayed.
Checking the "pKa Range" check box and setting the range sliders will limit the results displayed to only
those measurements which fall within that range; likewise the "Temp Range" check box will also filter out measurements 
that do not fall between the provided ranges. The ranges can be set by either moving the range sliders or entering 
the desired numeric values in the spin boxes. The pKa filter range is limited between 0 and 14, the temperature filter
range is limited from 0 and 50. Although there may be some data points that fall beyond these ranges these endpoints
were chosen to allow for the maximum filter granularity of the vast majority of the data.

Ionization Types
----------------

By checking a subset of Acids, Bases, and Excited the results can be limited to showing measurements which have been
assigned as falling into one of these categories. 

Quality Minimum
---------------

.. figure:: /_images/quality.png
   :scale: 50
   :align: center
   :alt: Quality Quantities
   
   **Quality Quantities**

The data has been annotated based upon the author's assessment of quality, and the radio buttons allow for limiting 
the displayed results. There are a great deal more measurements on the lower end of the quality scale, so if ever
it seems that the results list does not contain molecules that you believe should be there it helps to lower this 
threshold to hit upon a greater set of molecules.


.. _chapter_pka_search:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


================
Search Buttons
================

There are a total of five search options.

.. figure:: /_images/buttons.png
   :scale: 75
   :align: center
   :alt: Search Buttons
   
   **Search Buttons**

Analog Search
-------------

.. index:: Analog Search

This is the default search, which is performed whenever a new molecule is loaded into the application.
It attempts to find the best model compounds in the database by exhaustively searching in a chemically 
aware manner. Firstly if there is an exact match in the database the measurements associated with 
that molecule are reported first. Then the application performs a rooted maximum common
subgraph search beginning at each ionizable region, and applies a positive score for matches and a penalty 
for substitutions, graded based upon the electronic commutative distance to the ionizable atom. The sum 
of these scores for each ionizable region match determines the overall rank of the molecule and its measurements. 
Only molecules with measurements that pass the property filters will be reported back. If you do not wish this
search to be performed every time you load a new molecule simply turn that option off in the preferences.

Exact Search
------------

.. index:: Exact Search

This search attempts to find an exact match in the database, and reports back only those measurements which 
pass the property filters.

Property Search
---------------

.. index:: Property Search

.. _figure_Propery:

.. figure:: /_images/propertysearch.png
   :scale: 25
   :align: center
   :alt: Property Search
   
   **Property Search**

This search ignores any query molecule information and simply reports back those 
molecules which pass the property
filters. The query molecule depiction is deemphasized, and the results view does not
have a query molecule in the first row. :ref:`Figure: Property Search<figure_Propery>`

Substructure Search
-------------------
.. index:: Substructure Search

.. _figure_lasso_sub:

.. figure:: /_images/lasso.png
   :scale: 50
   :align: center
   :alt: Lasso a Substructure
   
   **Lasso a Substructure**

This search will look for molecules that have a common substructure with the query molecule. A subset of the 
query molecule can be used by lassoing with the mouse. :ref:`Figure: Lasso a Substructure<figure_lasso_sub>` 
Again only molecules with measurements that pass the property filter will be reported.

.. _figure_subsearch2:

.. figure:: /_images/subsearch.png
   :scale: 50
   :align: center
   :alt: Sub Structure Search
   
   **Substructure Search**

Similarity Search
-----------------

.. index:: Similarity Search

This search will perform a circular fingerprint search which is generated by exhaustively enumerating all circular fragments grown radially from each heavy atom of the molecule up to a given radius and then hashing these fragments into a fixed-length bit vector. Only measurements which pass both the property filter and are above the Tanimoto cutoff 
value will be reported.


.. _chapter_pka_results:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


=============
Results View
=============

.. index:: Result View

On the right hand side of the application is the results view.

Search Summary
--------------

The first row of the results view contains a depiction of the query molecule and a summary of the search,
including any filters that were applied. If there is an exact match to the query molecule which passes
the property filters this will always be in the second row.

Depiction
---------

The left hand column contains a depiction of the search results molecules. For an "Analog Search" the highlighting indicates the portion of the molecule which matches the ionizable region of the query molecule with the same color. For a "Substructure Search" the highlighting show the matching substructure.
For a "Property Search" the highlighting corresponds to the resulting molecules individual ionizable regions,
and is unrelated to any other molecules highlighting. 

Double clicking the depiction will make the molecule the new query molecule.

Results Table
-------------

The right hand column contains a table enumerating all available measurements that pass the preference
filter for the given molecule. Layout of the Results Table can be changed in the Preferences.

Double clicking the result table will open a detailed report of the selected molecule. More detail is given below.

The results view can be saved to PDF or CSV through the file menu.


.. _chapter_pka_prefs:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

=============
Preferences
=============

.. index:: Preferences

.. figure:: /_images/preferences.png
   :scale: 75
   :align: center
   :alt: Preference Dialog
   
   **Preference dialog**

Results View Customization 
--------------------------

The application's preference dialog allows for the customization of the reported data columns. By checking items from the
list titled "Results Table Headers" will affect how the results table is generated. The individual items can be reordered 
and that order will be respected within the results table.

Search Options
--------------

The "Show Additional Search Options" enables the "Substructure Search," "Similarity Search," "Exact Search," and the 
"Property Search" options. The "Display Aqueous Determination Only" checkbox will cause the results to only ever 
display aqueous pKa values. The "Perform Search Automatically" checkbox will cause the application to perform the
"Analog Search" automatically after any change to the query molecule.


.. _chapter_pka_report:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

==============
Result Report
==============

The Result Report is a detailed listing of all data which passes the property filter for a given result molecule.
This window can remain open while performing other searches.

.. figure:: /_images/report.png
   :scale: 75
   :align: center
   :alt: Result Report
   
   **Result Report**

Depiction
---------

The molecular depiction has highlighting for the individual ionizable regions, independent of any other molecules and
their highlighting. 

Summary
-------

The top right contains a short summary table with a few key fields, along with links to jump to the specific detailed
report. The alternating background color of the summary table rows corresponds to the background color of the full
data listing for that particular measurement. 

Full Listing
------------

The full listing contains all available data for that particular molecule. If data field is missing then that row will
be omitted. The data fields are always in a fixed order.

Saving
------

The "Save to PDF" button will save the table to an easily printable PDF file including the depiction. 


.. _pka_menu:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


=============
Menu Items
=============

.. index:: Menu Items

Saving Data
-----------

Under the "File" menu there are various options to save your results to PDF or CSV. "Save Selected as PDF" saves only
those rows which have been selected in the results view. Shift clicking and control clicking will select range and individual rows respectively.

Session History
---------------

The "Session History" menu keeps track of all searches performed during a session. The search results are stored in
memory so they can be retrieved quickly, without having to search again.

Query Bookmarks
------------------

The "Query Bookmark" menu provides a means of saving individual query molecules and current property filter settings.
These bookmarks persist between sessions.



.. _pka_data:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


===============
Appending Data
===============

.. index:: Appending Data

For institutions with their own pKa data, pKa-Prospector provides a means of folding that data into the user interface. It can live side by side with the IUPAC data.

Under the "File" menu there is an "Import Data..." dialog which will guide the user through the import process.
The user has the option to name the imported database.

.. figure:: /_images/dataloader.png
   :scale: 75
   :align: center
   :alt: Data Loader
   
   **Data Loader**

Data Formatting
---------------

In order for pKa-Prospector to properly import institutional data, the data must first be in an oeb or sdf file format with the desired measurement data set in SD data fields. The file is initially loaded through the
dialogs "Open a file..." combo box. The application will then inspect the first 10 molecules to get a list SD data
tags.

Data Mapping
------------

The application requires that the various file SD data tags get associated to their corresponding properties.
This is accomplished by using the pull down combo boxes. As any given data tag is assigned it will be removed
from the lists under the other properties.

**pKa Value:** This is the only required data field; all others can have assumed default values. This field must be 
in a decimal format such that it can be converted using "``float pka = atof(...);``"

**Temp:** Much like "pKa Value" this field must be easily converted to a float. The "Default Value" column is 
the value which will be assigned if there is no data tag assigned or if the assigned data tag is missing.

**Ionization:** This field must match the literal strings "Acid", "Base", "Excited" or "Unknown". Much like temperature
the default value can be set as well.

**Assessment:** This field must match the literal strings "reliable", "uncertain", or "approximate". The default 
assignment can be set as well.

**Aqueous:** This fields indicates whether or not the pKa measurement was determined in aqueous solution. This field
must be "0" or "1" for false or true satisfying "``bool aqueous = (bool) atoi(...);``"

Extra Data
----------

pKa-Prospector also allows for importing of extra data tags to be displayed along within results table. This may be useful in some cases, for example
if a molecule or measurement is associated with a particular corporate id.


.. _pka_import_db:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


================================
Selecting an Imported Database
================================

.. figure:: /_images/loadeddata.png
   :scale: 75
   :align: center
   :alt: Select Database
   
   **Select Database**

Select Database
---------------

Once all the data fields are assigned and "OK" is clicked, pKa-Prospector will process the file and create an internal 
data file from where it can be loaded upon future sessions. After the conversion process is finished a
dialog is displayed where various data bases can be selected. Currently the application allows for IUPAC and the user data or just the user data. If two imported databases have the same name the application will
distinguish them by applying a time stamp. Also the user can delete an imported database by right clicking
the database and selecting "Delete..." from context menu.

After the desired databases are selected the application will need to be restarted for the changes
to take effect.



.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _pka_citation:

**************
Citation
**************

.. note:: To cite pKa-Prospector please use the following:

    pKa-Prospector |pka-prospector_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



.. QUACPAC documentation master file
.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



#################################
QUACPAC |quacpac_version|
#################################

.. toctree::
   :maxdepth: 3

   introduction
   fixpka/fixpka
   molcharge/molcharge
   pkatyper/pkatyper
   tautomers/tautomers
   theory/molcharge_theory
   releasenotes/index
   appendix
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt





.. _quacpac_introduction:

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


************
Introduction
************

==============
Overview
==============

The  chemistry  of  molecular  interactions  is  a matter of shape and
electrostatics, but doing electrostatics poorly is worse than doing none at
all; accurate charges are required. Even the best charge models are useless
if  protonation states are wrong. **QUACPAC** attempts to offer everything
necessary to do charges correctly. It includes pKa and tautomer enumeration
in order to get correct protonation states, partial charges using multiple
models that cover a range of speed and accuracy, and electrostatic potential
map construction and storage.

==============
Applications
==============

The **QUACPAC** distribution comprises 4 applications:

  :ref:`FixpKa <chapter_fixpka>`

  * Sets the ionization state of input molecules using a rule based system.

  :ref:`MolCharge <chapter_molcharge>`

  * Assigns appropriate atomic partial charges, both to small molecule ligands and to biopolymers.

  :ref:`pKaTyper <chapter_pkatyper>`

  * Enumerates the protonation states and assess ligand pKas.

  :ref:`Tautomers <chapter_tautomers>`

  * Canonicalizes and enumerates the tautomeric forms of a small molecules.


.. _chapter_fixpka:

FixpKa
======

.. toctree::
   :maxdepth: 2

   fixpka_overview
   fixpka_example
   fixpka_help
   fixpka_req_params
   fixpka_opt_params


.. _fixpa_overview:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: fixpa 

======================
Overview
======================

**FixpKa** has a rule-based system to set the ionization state of input
molecules. If pKa normalization is turned on, the molecule is set to
its most energetically favorable ionization state for ``pH=7.4``. The
rule-based nature of this calculation allows it to be very
fast. Further, despite being rule-based, this approach takes into
account many secondary charge interactions.

While more advanced levels of theory can be found for predicting
ionization states, this method is very well suited to
virtual-screening database preparation. However, **FixpKa** may not be
appropriate for hit-to-lead or lead optimization.


.. _fixpa_example:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: fixpa 

======================
Example Commands
======================

The following section shows a common command-line execution of
`fixpka`. 

.. code-block:: bash

   prompt> fixpka drugs.sdf fixpka_drugs.smi

Reads the file `drugs.sdf` in SD format, sets the pKa state of
each molecule and writes them into the file `fixpka_drugs.smi`.



.. _fixpa_help:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: fixpa 

======================
Command Line Help
======================
A description of the commandline interface can be obtained by executing **FIXPKA**
with the `--help` option.

.. code-block:: bash
   
   prompt> fixpka --help

will generate the following output:

::

   Help functions:
     fixpka --help simple      : Get a list of simple parameters (as seen above)
     fixpka --help all         : Get a complete list of parameters
     fixpka --help defaults    : List the defaults for all parameters
     fixpka --help <parameter> : Get detailed help on a parameter
     fixpka --help html        : Create an html help file for this program
     fixpka --help versions    : List the toolkits and versions used in the application


.. _fixpka_req_params:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: fixpka

======================
Required Parameters
======================

.. option:: -in

   File containing one or more molecules from which pKa normalization will be done.
   An input file is required, but the
   `-in` flag is optional.  The first parameter listed with no flag will be
   automatically mapped to the input file.  Unflagged parameters must occur
   last in the parameter list.  Any OpenEye supported molecule format can be used for input.


.. _fixpka_opt_params:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: fixpka

======================
Optional Parameters
======================

.. option:: -ionize

   Specifies ionization environment, either neutral pH or un-ionize, to remove all ions
   possible. Legal values are neutral, 7.4, un-ionize, and unionize. [Default=neutral]

   .. seealso::

      * :ref:`OEProton::OESetNeutralpHModel <OEProton_OESetNeutralpHModel>`
      * :ref:`OEProton::OERemoveFormalCharge <OEProton_OERemoveFormalCharge>`

.. option:: -out

   File for writing output. Both the output file and the `-out` flag are optional.
   The second parameter listed with no flag will be automatically mapped to the
   output file.  Unflagged parameters must occur last in the parameter list.  Any
   OpenEye supported molecule format can be used for output but `.smi` or `.ism`
   is recommended. [Default=.ism]

   [Aliases=**-o**]

.. option:: -prefix

   The argument for this flag defines the prefix to be used for parameter
   and log files. The parameter and log files will be written to what follows
   this flag plus the extension `.param` or `.log`. [Default=fixpka]

.. _chapter_molcharge:

MolCharge
=========

.. toctree::
   :maxdepth: 2

   molcharge_overview
   molcharge_example
   molcharge_help
   molcharge_req_params
   molcharge_opt_params


.. _molcharge_overview:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: molcharge

======================
Overview
======================

`molcharge` uses the *-method* flag to determine what method to use to
generate partial charges. Some methods can be applied to 2D input structures, others
require 3D input structures; for the latter the run will fail if a 3D
structure is not provided. Hydrogens will be sprouted on the molecules if
they are not present already.

With default parameters, `molcharge` will sprout explicit hydrogens and assign MMFF94 partial charges.


.. _molcharge_example:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: molcharge 

======================
Example Commands
======================

An example run of the `molcharge` program is given below.

.. code-block:: bash

   prompt> molcharge -method mmff drugs.sdf drugs.mol2

This executes `molcharge` with the default parameters, to sprout explicit
hydrogens and assign MMFF94 partial charges.  The file `drugs.sdf`
is opened in SD format for input, and the output is written to the file
`drugs.mol2` in Sybyl .mol2 format.

.. code-block:: bash

   prompt> molcharge -method amberff99sb 2iko_prot.pdb 2iko_prot.oeb

In this sample execution, a protein is charged using the Amber charge set and written
to OEB format.




.. _molcharge_help:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: molcharge 

======================
Command Line Help
======================

A description of the commandline interface can be obtained by executing **molcharge**
with the `--help` option.

.. code-block:: bash
   
   prompt> molcharge --help

will generate the following output:

::

   Help functions:
     molcharge --help simple      : Get a list of simple parameters (as seen above)
     molcharge --help all         : Get a complete list of parameters
     molcharge --help defaults    : List the defaults for all parameters
     molcharge --help <parameter> : Get detailed help on a parameter
     molcharge --help html        : Create an html help file for this program
     molcharge --help versions    : List the toolkits and versions used in the application


.. _molcharge_req_params:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: molcharge 

======================
Required Parameters
======================

.. option:: -in

   This is the input file.  This file can contain molecules in a
   wide-variety of molecular formats. 
   Some of the partial charging models, such
   as AM1 and AM1BCC require coordinates in order to calculate charges.  While
   the input file is required, the `-in` flag is optional.  If no `-in`
   flag is specified, the first unflagged parameter is used as the input file.

   [Aliases=**-i**]

.. option:: -out

   This is the output file and it is a required parameter.  Since
   the object of `molcharge` is to generate partial charges, it will only write
   to formats that can specify a partial charge.  These formats currently
   include `.mol2`, `.mol2H`, `.mol2.gz`, `.oeb`, and `.oeb.gz`.
   While the output file is required, the `-out` flag is optional.
   If no `-out` flag is specified, the second unflagged parameter is used as
   the output file.

   [Aliases=**-o**]


.. _molcharge_opt_params:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: molcharge 

======================
Optional Parameters
======================

.. option:: -method {option}

   Selects the charging method to be applied to the input molecule(s). [Default=mmff]
   Choose
   one of the following recommended options:

   **am1bccsym** applies AM1BCC charges as published, including partial semiempirical
   AM1 geometry optimization and averaging bond-topologically symmetric charges.
   It requires a 3D geometry associated with an input structure. These are good-quality
   charges for pharmaceutical organic molecules for intermolecular interactions.

   **mmff** applies MMFF94 charges. It will work with only a 2D geometry. This method is
   the best choice for use with the MMFF forcefield and these charges are of
   passable quality for intermolecular interactions. This is the default method.

   **amberff99sb** applies to proteins the RESP charge set used for Amber forcefields
   ff94, ff96, ff98, ff99, ff99sb, and ff99sbc0 (the same charge set is used in
   all these cases). This method only works for standard amino acids. These are
   very good-quality charges for proteins for intermolecular interactions.

   **gasteiger** applies gasteiger charges (a charge-equilibration method).
   **NOTE:** This method *should not be used for intermolecular interactions.*
   This method was intended for comparing relative reactivity of related
   organic chemical functional groups within different molecular contexts. 
   It will work with only a 2D geometry. 

   There are a number of other options for charge methods, but none are
   recommended. They are listed in the  *molcharge* appendix.

   .. seealso::

      * :ref:`OEProton::OEAssignCharges <OEProton_OEAssignCharges>`

.. option:: -param

   The argument for this flag is the name of a
   file containing control parameters.  The control parameter file acts
   to either replace or augment the command line interface.  All
   parameters necessary for program execution may be provided in the
   control parameter file, although any command given explicitly on the
   command line will supersede options found in the parameter file.
   *molcharge* generates a new parameter file containing the full set of
   execution parameters upon every execution.  The name of the
   parameter file written by *molcharge* is created by combining the prefix
   base name with the *'.parm'* extension.

.. option:: -paramfile

   The filename for the output parameter file can be set with this flag and
   it overrides -prefix flag for the name of parameter file.

.. option:: -prefix

   The argument for this flag defines the prefix to be used for parameter
   and log files. The parameter and log files will be written to what follows
   this flag plus the extension `.param` or `.log`.
   [Default=molcharge]

.. _chapter_pkatyper:

pKaTyper
========

.. toctree::
   :maxdepth: 2

   pkatyper_overview
   pkatyper_example
   pkatyper_help
   pkatyper_req_params
   pkatyper_opt_params

.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _pkatyper_overview:

.. program:: pkatyper

======================
Overview
======================

Assessment of ligand pKas can be broken into two phases. The first phase is
enumeration of the protonation states of interest, and the second phase is
assigning a pKa value to each of these states. An intermediate phase of
assigning microscopic pKas to each of the atomic-deprotonations may also be
considered.

It  is common in the course of modeling small-molecules to explore the
conformational ensemble of the small molecule. Often structures as high as
5-8 kcal/mol above the aqueous ground-state can be important to biological
processes. It is also appropriate to enumerate a protonation-state ensemble
of the small molecule.

Similar to `tautomers`, OpenEye has a solution for enumerating reasonable
protonation states, but not for assessing the energetics of the state (e.g.
assigning a pKa value). OpenEye's solution for pKa enumeration seeks to
enumerate all of the pKa states that fall roughly in the pH range of 2-14 in
aqueous  solvent.  This range of pKa values generates an ensemble that
includes the ground-state plus all charge states within 8 kcals/mol :math:`\Delta G`.
This value was chosen to correspond to the similar range that is often used
for generating conformational ensembles of small molecules.

**pKaTyper** enumerates charge states based on primary, secondary and tertiary
atom types of each atom in a molecule. The primary atom type is based on the
atom's group and its valence. The primary atom-type defines the atom's basic
propensity to support a formal charge. The secondary atom-type is defined by
the atom-type of the neighbors for each atom. These secondary atom-types,
such as aromaticity, alpha-beta unsaturation, or electronegative-groups,
modulate  each  atom's basic propensity to support formal charges. The
tertiary atom-types assess the effects of nearby formal charges on a given
atom's formal charge. The combination of the primary, secondary and tertiary
atom-types determine which formal charge states are allowed for each atom in
a molecule. The primary and secondary atom-types are determined once, while
the tertiary atom-types are determined as part of the enumeration process.

**pKaTyper** is a rudimentary approach to pKa prediction. While pkatyper is not
suited for prediction of absolute pKas, it is quite amenable to enumeration
of all reasonable charge states of a very wide variety of small-molecule
chemistries.

**pKaTyper**  is  not  a  conformer generation program and will not create
coordinates for molecules that are read in without coordinates. When used on
molecules with three-dimensional coordinates, **pKaTyper** attempts to place new
hydrogens in a reasonable manner. However, **pKaTyper** does not modify the
heavy-atom  coordinates  of the molecule. In cases where the change in
protonation-state dictates a change in conformation, one will need to use a
conformer-generation  tool  (such  as  OMEGA)  to  generate reasonable
conformations  for  the  output  from  **pKaTyper**. We recommend that in
preparation  of  small-molecules  for study, charge-state and tautomer
enumeration be performed before conformer generation.




.. _pkatyper_example:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: pkatyper 

======================
Example Commands
======================

The following section shows several common command-line executions of
**pkatyper**.  Each example is followed by an explanation of what the
program will do.

.. code-block:: bash

   prompt> pkatyper drugs.sdf enumerated_drugs.smi

Reads the file `drugs.sdf` in SD format, enumerates the pKa states of
each molecule and writes them into the file `enumerated_drugs.smi`.
Molecules with only one identified pKa state are passed through to the output
file.

.. code-block:: bash

   prompt> pkatyper -in drugs.sdf -out enumerated_drugs.smi

This command generates the exact same behavior as described above.

.. code-block:: bash

   prompt> pkatyper -count drugs.sdf drugCounts

This command reads each of the molecules in `drugs.sdf` and counts the
number of pKa states.  For each molecule, a single line is added to the
`drugCounts` output file that contains the molecule title and the
number of states.



.. _pkatyper_help:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: pkatyper 

======================
Command Line Help
======================

A description of the commandline interface can be obtained by executing **pkatyper**
with the `--help` option.

.. code-block:: bash
   
   prompt> pkatyper --help

will generate the following output:

::

   Help functions:
     pkatyper --help simple      : Get a list of simple parameters (as seen above)
     pkatyper --help all         : Get a complete list of parameters
     pkatyper --help defaults    : List the defaults for all parameters
     pkatyper --help <parameter> : Get detailed help on a parameter
     pkatyper --help html        : Create an html help file for this program
     pkatyper --help versions    : List the toolkits and versions used in the application


.. _pkatyper_req_params:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: pkatyper

======================
Required Parameters
======================

.. option:: -in

   Input file of molecules.  An input file is required, but the
   `-in` flag is optional.  The first parameter listed with no flag will be
   automatically mapped to the input file.  Unflagged parameters must occur
   last in the parameter list.

   [Aliases=**-i**]

.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _pkatyper_opt_params:

.. program:: pkatyper

======================
Optional Parameters
======================

.. option:: -count

   Only count the number of pKa states rather than enumerating
   each of the states.  If the `-count` flag is specified true, then the
   output file will contain the name of each compound followed by the number
   states of that molecule.  This options writes to a text file or stdout. [Default=false]

   [Aliases=**-c**]

.. option:: -max

   This integer parameter is the maximum number of pKa states
   which will be enumerated for any single molecule.  If a value of zero is
   passed to this parameter, no limit will be set. [Default=100]

   .. seealso::

      * :ref:`OEProton::OETyperMolFunction <OEProton_OETyperMolFunction>`

.. option:: -out

   Output file of molecules.  Both the output file and the
   `-out` flag are optional.  The second parameter listed with no flag will
   be automatically mapped to the output file.  Unflagged parameters must
   occur last in the parameter list.  If no output is specified at all, output
   will be written to `std::out` in SMILES format.  Any OpenEye supported
   molecule format can be used for output. If the `-count` flag is specified
   true, then molecular format is no longer relevant to the output file.
   [Default=.ism]

   [Aliases=**-o**]

.. option:: -param

   The argument for this flag is the name of a
   file containing control parameters.  The control parameter file acts
   to either replace or augment the command line interface.  All
   parameters necessary for program execution may be provided in the
   control parameter file, although any command given explicitly on the
   command line will supersede options found in the parameter file.
   **pkatyper** generates a new parameter file containing the full set of
   execution parameters upon every execution.  The name of the
   parameter file written by `pkatyper` is created by combining the prefix
   base name with the `.parm` extension.

.. option:: -paramfile

   The filename for the output parameter file can be set with this flag and
   it overrides -prefix flag for the name of parameter file.

.. option:: -prefix

   The argument for this flag defines the prefix to be used for parameter
   and log files. The parameter and log files will be written to what follows
   this flag plus the extension `.param` or `.log`.    [Default=pkatyper]

.. option:: -warts

   Add wart number with _ to each state. [Default=true]


.. _chapter_tautomers:

Tautomers
=========

.. toctree::
   :maxdepth: 2

   tautomers_overview
   tautomers_example
   tautomers_help
   tautomers_req_params
   tautomers_opt_params

.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _tautomers_overview:

===================
Overview
===================

OpenEye's **Tautomers** program is used for canonicalizing and/or enumerating the tautomeric forms of a small molecule. Canonicalization converts any of the tautomeric forms of a given molecule into a single unique representation. This is useful for database registration where alternate representations of tautomeric compounds often leads to duplicate entries in a database.

Some effort is made by the **Tautomers** program to direct the ``canonical`` representation to be a physiologically preferred form. However, there are no guarantees the tautomer selected is indeed the lowest energy and, indeed, solvent effects, etc., preclude there being a single ``best`` form of a tautomer. Fortunately, this is not necessary for database work.

**Tautomers** is not a conformer generation program and will not create coordinates for molecules that are read in with no coordinates. When used on molecules with three-dimensional coordinates, **Tautomers** attempts to place hydrogens in a reasonable manner. However, **Tautomers** does not modify the heavy-atom coordinates of the molecule. In cases where the change in tautomer-state dictates a change in conformation, one will need to use a conformer-generation tool (such as **OMEGA**) to generate reasonable conformations for the output from **Tautomers**. We recommend that in the preparation of small-molecules for study, charge-state and tautomer enumeration be performed before conformer generation.



.. _tautomers_example:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: tautomers

======================
Example Commands
======================

The following section shows several common command-line executions of
**tautomers**.  Each example is followed by an explanation of what the
program will do.

Consider the following input file, `guanine.smi`, that contains
just the following line: `c1[nH]c2c(=O)[nH]c(nc2n1)N`

.. code-block:: bash

   prompt> tautomers guanine.smi output.smi

Which should write the following 15 structures to the file `output.smi`.

.. code-block:: bash

   c1[nH]c2c(=O)[nH]c(nc2n1)N untitled1_1
   c1[nH]c2c(n1)c(=O)[nH]c(n2)N untitled1_2

Please note that if **tautomers** fails to find tautomers for a molecule, it
will output the molecule to a fail file. This occurs if the algorithm times
out. e.g. benzene would not be in the fail file but a very large peptide might
be. Name of the fail file is either 'tautomers.fail' or 'prefix.fail' if
prefix is specified by `-prefix` flag.


.. _tautomers_help:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: tautomers 

======================
Command Line Help
======================

A description of the commandline interface can be obtained by executing **tautomers**
with the `--help` option.

.. code-block:: bash
   
   prompt> tautomers --help

will generate the following output:

::

   Help functions:
     --help simple      : Get a list of simple parameters (as seen above)
     --help all         : Get a complete list of parameters
     --help defaults    : List the defaults for all parameters
     --help <parameter> : Get detailed help on a parameter
     --help html        : Create an html help file for this program
     --help versions    : List the toolkits and versions used in the application


.. _tautomers_req_params:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: tautomers

======================
Required Parameters
======================

.. option:: -in

   File containing one or more molecules for which tautomers will be generated.
   An input file is required, but the
   `-in` flag is optional.  The first parameter listed with no flag will be
   automatically mapped to the input file.  Unflagged parameters must occur
   last in the parameter list.  Any OpenEye supported molecule format can be used for input.


.. _tautomers_opt_params:
.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: tautomers

======================
Optional Parameters
======================

.. option:: -ch3

   Allows carbon atoms that are close by appropriate heteroatoms to change hybridization state.
   This permits structures such as
   cyclohexa-2,4-dien-1-one to be considered a tautomer of phenol, and
   other examples of keto-enol tautomerism.
   Unfortunately, the `-ch3` flag may cause the calculation 
   time to increase by many orders of magnitude for some molecules.  [Default=true]

   [Aliases=**-ch2**,**-methyl**,**-methylene**]

   .. seealso::

      * :ref:`OEProton::OETautomerOptions::SetCarbonHybridization <OEProton_OETautomerOptions_SetCarbonHybridization>`

.. option:: -maxtoreturn

   Specify a maximum number of tautomers to enumerate for
   a single input structure.  Over 99% of compounds require less than
   100 tautomers, indeed most organic compounds gave only a single
   tautomer, however some pathological dyes and chromophores may individually
   have nearly a million possible tautomeric forms.  The current default
   is a limit of 256 tautomers per input structure.  [Default=256]

   [Aliases=**-m**]

   .. seealso::

      * :ref:`OEProton::OETautomerOptions::SetMaxTautomersToReturn <OEProton_OETautomerOptions_SetMaxTautomersToReturn>`

.. option:: -maxgenerated

   Specify a maximum number of tautomers that may be generated
   per input molecule..  [Default=4096]

   .. seealso::

      * :ref:`OEProton::OETautomerOptions::SetMaxTautomersGenerated <OEProton_OETautomerOptions_SetMaxTautomersGenerated>`

.. option:: -maxtautomericatoms

   Specify a maximum number of tautomeric atoms allowed in a
   molecule. [Default=70]

   .. seealso::

      * :ref:`OEProton::OETautomerOptions::SetMaxTautomericAtoms <OEProton_OETautomerOptions_SetMaxTautomericAtoms>`

.. option:: -maxtime

   This flag limits the amount of time (in seconds) spent generating
   tautomer for each molecule.
   [Default=120.0]

   [Aliases=**-maxsearchtime**]

   .. seealso::

      * :ref:`OEProton::OETautomerOptions::SetMaxSearchTime <OEProton_OETautomerOptions_SetMaxSearchTime>`

.. option:: -maxzonesize

   Specify a maximum number of atoms allowed in a continuous
   tautomerization zone. [Default=35]

   .. seealso::

      * :ref:`OEProton::OETautomerOptions::SetMaxZoneSize <OEProton_OETautomerOptions_SetMaxZoneSize>`

.. option:: -out

   Output filename, where the file extension indicates the output format.  All OpenEye supported molecule formats are allowed but .smi and .ism are recommended.  
   The default setting will print .ism format to standard out. [Default=.ism]

.. option:: -param

   The argument for this flag is the name of a
   file containing control parameters.  The control parameter file acts
   to either replace or augment the command line interface.  All
   parameters necessary for program execution may be provided in the
   control parameter file, although any command given explicitly on the
   command line will supersede options found in the parameter file.
   `tautomers` generates a new parameter file containing the full set of
   execution parameters upon every execution.  The name of the
   parameter file written by **tautomers** is created by combining the prefix
   base name with the `.parm` extension.

.. option:: -paramfile

   The filename for the output parameter file can be set with this flag and
   it overrides -prefix flag for the name of parameter file.

.. option:: -pkanorm

   This flag determines whether to apply pKa normalization. If it is true
   the ionization state of each tautomer will be assigned to a predominate
   state at pH~7.4. [Default=true]

   .. seealso::

      * :ref:`OEProton::OEGetReasonableTautomers <OEProton_OEGetReasonableTautomers>`

.. option:: -prefix

   The argument for this flag defines the prefix to be used for parameter
   and log files. The parameter and log files will be written to what follows
   this flag plus the extension `.param` or `.log`.   [Default=tautomers]

.. option:: -rank

   Specify whether or not tautomers are ranked and ordered before
   being returned. If this is false, i.e., the canonical tautomer is
   returned as the first molecule in the iterator. As opposed to the
   most “reasonable” tautomer being returned first.
   [Default=true]
   .. seealso::

      * :oe:meth:`OEProton::OETautomerOptions::SetRankTautomers`
.. option:: -stereo

   Specify a stereo loss behavior for the tautomer algorithm. There are
   three valid values: `None` means that atoms and bonds with
   labeled stereochemistry are fixed to participate in tautomerization;
   `LocalSampled` means that individual tautomers that have double
   bonds to tetrahedral stereocenters will have the stereo removed;
   `EverSampled` means that if an atom which are tetrahedral
   stereocenters has a double bonds in any of the tautomers returned
   by the function, then those tetrahedral stereocenters will have
   the stereo removed in ALL of the returned tautomers.
   [Default=LocalSampled]

   .. seealso::

      * :ref:`OEProton::OETautomerOptions::SetSaveStereo <OEProton_OETautomerOptions_SetSaveStereo>`
      * :ref:`OEProton::OETautomerOptions::SetRacemicType <OEProton_OETautomerOptions_SetRacemicType>`

.. option:: -warts

   Add wart number with _ to each tautomer. [Default=true]

   .. seealso::

      * :ref:`OEProton::OETautomerOptions::SetApplyWarts <OEProton_OETautomerOptions_SetApplyWarts>`

.. |product|        replace:: FILTER

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _molcharge_theory:

MolCharge Theory
================

Introduction
------------

The assignment of appropriate atomic partial charges, both to small molecule
ligands and to biopolymers (such as proteins and nucleic acids) is essential
to getting meaningful results from any electrostatics calculation.

A molecule may be considered a collection of atomic nuclei and the electrons
that surround them. The number of protons in each nucleus defines its atomic
number/element. If the number of electrons exactly matches the number of
protons in these nuclei, the molecule is neutral and has no net charge. If
there are more electrons than protons, the molecule has a net negative
charge, and if there are less, the molecule has a net positive charge.

It is both the atomic nuclei and the net charge that define the identity of
a molecule. Indeed, this is a representation common to quantum chemistry.
Adding or removing electrons (or atoms) from a molecule produces a different
molecule.

In the discrete world of cheminformatics, valence bond theory allows the
electrons present in a system to be represented in terms of bonds with
formal bond orders, and formal charges assigned to particular atoms. The sum
of the formal charges is equal to the net charge on the molecule, but which
atoms are assigned which formal charges can be to some extent arbitrary due
to resonance delocalization. In such cases
the same molecule may be represented by similar connection tables, but with
formal charges assigned to different sets of atoms.

For example, guanidinium may be expressed as either N[C+](N)N with the
formal charge assigned to the carbon, or as [NH2+]=C(N)N with the formal
charge  assigned  arbitrarily to one of the otherwise equivalent
nitrogens.  A similar example is a thiocarboxylate group, where either
C(=O)[S-] or C(=S)[O-] are both equally appropriate representations of the
same chemical functionality.

A zwitterion is an electrically neutral molecule that is represented as
containing atoms with positive formal charge as well as atoms with negative
formal charge.

Perhaps  the most important fact to appreciate when considering formal
charges on atoms is that they are all artificial constructs by chemists
to accommodate a particular chemical model. A figment of a chemist's fevered
imagination. Like valence bond theory, they are an exceptionally useful and powerful
discretized model of the universe. But as with any model of reality, it has
its limitations. Formal charges, for all their numerous benefits to mankind,
unfortunately, are not localized on an atom.

The limitations of describing formal charges with valence bond theory is
apparent even within cheminformatics. Sydnones, for example, are a class of
heterocyclic compound that cannot be written using normal covalent bonds
without introducing and arbitrarily assigning both positive and negative
charges.  Similarly,  in inorganic chemistry, the ditechnetium cation,
:math:`\mbox{Te}_{2}^{+5}`, causes similar problems where the +5 formal charge
cannot be assigned to both technetium atoms without breaking symmetry.

A  better model, or approximation, of the wave function describing the
distribution of electron density around a molecule is the use of atomic
partial charges. A partial charge is a floating-point value assigned to each
atomic  center  intended to model the distribution of electrons over a
molecule.

Atomic partial charges are yet another approximation, much like the formal
charges described above. However, partial charges provide a much better
model to describe the electric field, dipole moment and other observable
properties of a molecule.

A common limitation of the use of partial charges is the assumption that
they are conformationally invariant. Unfortunately, the distribution of
electrons around a molecule depends upon the spatial configuration of its
nuclei. Some partial charge assignment algorithms, such as the method of
Goddard and Rappe, consider these conformational effects, whilst others that
are based on quantum mechanics, such as the RESP and AM1BCC methods of Bayly
et  al.,  go to great lengths to eliminate conformational effects, for
example, by restraining and symmetrizing symmetric atom positions. This is
necessary in order to be able to properly handle multiple conformations and changes
in geometry (e.g. geometry optimization) with a single set of atomic charges.

Marsili-Gasteiger Partial Charges
--------------------------------------------------------------------------------

Marsili-Gasteiger partial charges are assigned using a two stage algorithm.
In the first stage, seed charges are assigned to each atom in the molecule.
For example, carboxylate oxygens are each assigned the value -0.5. During
the second stage, these initial charges are then shared across bonds, moving
a certain amount of charge from one atom to another. The partial charge
moved and its direction is determined by difference in electronegativities
of the atoms on each end of the bond. The relaxation algorithm is then
iterated several times (by default eight passes), attenuating the charge
moved with each iteration. OpenEye does not recommend use of this charge
model for intermolecular interactions; it was never intended for this purpose.
The author of the method (Johann Gasteiger) developed it to compare
relative reactivity of related organic chemical functional groups within
different molecular contexts. Here it is included for comparison purposes.

MMFF94 Partial Charges
--------------------------------------------------------------------------------

The partial charges used by the MMFF94 and MMFF94s force fields are assigned
using a four stage algorithm. In the first stage, each atom of the molecule
is  assigned an MMFF94 atom type. In the second stage, an initial seed
partial charge is assigned to each atom based upon its atom type. For a few
atom  types,  the  initial  partial charge also depends upon the local
environment. In the third stage, the initial charges assigned to aromatic
rings are shared between all atoms of the aromatic ring. Finally, in the
fourth  stage, a table of bond charge increments (BCI) is used to move
charges across bonds based upon the bond type of the bond (single, double,
triple) and the atom types of the atoms at each end. Developed for the
electrostatic interactions within the above-mentioned force fields, they
are the appropriate charges to use with these force fields most notably for
intramolecular interactions of pharmaceutical and bio-organic small molecules.
They are less well-suited (but still passable) for intermolecular interactions
using the common two-body additive Coulomb interactions as used in Amber,
Charmm, Gromacs. For these better choices would be amber99sb charges on
proteins and peptides, and am1bccsym charges on the ligand.

AM1 Charges
--------------------------------------------------------------------------------

AM1 charges are a set of Mulliken-type charges derived from a semi-empirical
quantum-mechanical calculation. For further discussion of this method,
please see Dewar et. al.  These should not be used for intermolecular
interactions of force fields.

AM1BCC Charges
--------------------------------------------------------------------------------

AM1BCC  charges  start  with  Mulliken-type partial  charges  derived  from  the AM1
semi-empirical quantum mechanical (QM) wave-function.
In a second stage, bond-charge corrections (BCCs) are applied
to the partial charges on each atom to generate new partial charges. Many
different variants of AM1BCC charges are offered within our API because of
the significant influences of several different factors on these
QM-derived charges. Specifically, these factors are

* Optimization: whether or not the input geometry is optimized. QM
  wavefunctions in general are quite sensitive to geometry, especially bond
  lengths and bond angles, so this can markedly affect the partial charges.
  In general, optimizing the geometry is recommended. To avoid a collapse
  of the conformation due to strong intramolecular electrostatic interactions,
  light restraints to the starting geometry are applied.

* Symmetrization: whether or not topologically similar atoms (for example
  the two oxygens on a carboxylate) are constrained to have identical
  values. The true QM wavefunction is usually asymmetric around topologically
  similar atoms, leading to asymmetric partial charges. However, if the same
  partial charges are to be used on different conformers (as with general
  fixed-charge force fields) it is important that these charges be symmetrized
  or else interconverting between formally degenerate conformers (e.g. 180
  degree rotation of the carboxylate) will have non-degenerate electrostatic
  energies.  In general, if the partial charges are to be applied to more
  than the single conformer used to generate them, symmetrization is strongly
  recommended.

Another important issue with AM1BCC charges is if highly conformer-specific
charges are generated which are unsuitable for other conformers, leading to
undesirable perturbed electrostatic energies for those other conformers. To
address this problem, we strongly recommend the ELF conformer selection protocol
described below.

"Standard" AM1BCC includes both optimization and symmetrization.

OpenEye  considers  AM1BCC charges to be the best partial charge model
currently available.  For further discussion, please see the work of
Christopher I. Bayly.

ELF Conformer Selection
--------------------------------------------------------------------------------

ELF conformer selection is a method to select one or more conformers having
Electrostatically Least-interacting Functional groups (ELF) from a
large conformer database. The purpose of this method is to resolve
important issues with QM-derived charges in general, including AM1BCC charges.
The issue is that strong short-range intramolecular polarizations
specific to a certain conformation, as with an intramolecular hydrogen bond
or salt bridge, usually leads to strongly perturbed partial charges for the atoms
involved. These charges can be very different from those found for other
conformers which do not have that intramolecular polar interaction. If such
partial charges are applied to all conformers, some of those other conformers
are very likely to have wrongly over-stabilized solvation energies.

A second problem arising from this issue is the precision or sensitivity of
the electrostatic energies resulting from QM-derived charges. By this we mean the variance
in electrostatic relative energies between different conformers depending on what
conformer is used for the QM-derived charges. Imagine two different sets of
QM-derived partial charges for a molecule, each coming from
a conformer having different strong intramolecular hydrogen bonds. Each set of
partial charges will have strongly perturbed partial charges for the internally
hydrogen bonded atoms, but they will be different. The relative energies
between conformers will be different depending which partial charge set is used.

For these reasons it is important to avoid generating QM-derived partial charges from
a conformer having electrostatically strongly interacting functional groups.
This is what ELF conformer selection does.

ELF needs to start with enough conformers so that it can find
a population of conformers that do not have strongly-interacting functional groups.
In the first stage, the Coulomb electrostatic energy is calculated
for every conformer using the absolute value of the MMFF94
partial charges (original negative charges are replaced with
their absolute values). The electrostatic energies with such charges
destabilize all strong polar interactions, and thus the lowest electrostatic
energies correspond to the Electrostatically Least-interacting Functional
groups. The lowest-energy 2% of conformers is selected as the 2% ELF population.
We find that averaging 10 diverse
conformers from the 2% ELF population is sufficient to provide
a well-behaved set of QM-derived partial charges even for highly polar
and charged molecules.

Amber ff94, ff96, ff99, ff99sb, and ff99sbc0 Partial Charges
--------------------------------------------------------------------------------

The partial charges used by the AmberFF94 force field are based on fitting
quantum mechanical electrostatic potentials (esp). They were developed to address
two key issues with earlier esp-fit charge sets: unrealistically high charges on charge
centers and the variation of atomic charges with conformation. While the latter
should have some basis in electronic structure, numerical instability in the
charge fitting process was the source of both these pathologies. AmberFF94 charge
sets use restrained esp-fitting (RESP) to control the numerical instabilities
and simultaneous multi-conformer fitting to lead to conformation-independent charges
that are restricted to individual residues. Particular attention was given to
ensure that backbone amides have consistent charges. The Amber force fields
ff94, ff96, ff99, ff99sb, and ff99sbc0 all use the same set of RESP charges, they
differ in other terms (mostly torsional).


.. _quacpac_releasenotes:

Release History
===============

.. toctree::
   :maxdepth: 3

   version2_3_0
   version2_2_7
   version2_2_6
   version2_2_5
   version2_2_4
   version2_2_3
   version2_2_2
   version2_2_1
   version2_2_0
   version2_1_3
   version2_1_2
   version2_1_1
   version2_1_0
   version2_0_2
   version2_0_1
   version2_0_0
   version1_7_0
   version1_6_3
   version1_5_0
   version1_3_1
   version1_3_0
   version1_1_0


#################
Quacpac 2.2.7
#################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************



Quacpac TK 2.2.7
================================================================================

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

* An issue that retained MDL-enhanced stereogroup information on stereocenters that
  are destroyed by protonation or bond order changes has been repaired.



########################
Quacpac 2.2.6
########################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


Quacpac TK 2.2.6
================================================================================

Minor internal improvements have been made.




QUACPAC  2.2.5
==================
  
Minor internal improvements have been made.

 


Quacpac TK 2.2.5
================================================================================

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

* Some issues with primary amines processing in :ref:`OEMultistatepKaModel <OEProton_OEMultistatepKaModel>`
  have been fixed.




QUACPAC  2.2.4
==================
  
Minor internal improvements have been made.

 


Quacpac TK 2.2.4
================================================================================

Minor internal improvements have been made.




QUACPAC  2.2.3
==================
   

Quacpac TK 2.2.3
================================================================================

Minor internal improvements have been made.





QUACPAC  2.2.2
==================

Minor internal improvements have been made.
   


Quacpac TK 2.2.2
================================================================================

Minor internal improvements have been made.




QUACPAC  2.2.1
==================

Minor internal improvements have been made.
   
Quacpac TK 2.2.1
===================

Minor internal improvements have been made.








QUACPAC  2.2.0
================================================================================

*Spring 2022*

*  Minor internal improvements have been made.
   


Quacpac TK 2.2.0
================================================================================

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

* New preliminary API classes, :ref:`OEMultistatepKaModel <OEProton_OEMultistatepKaModel>` and
  :ref:`OEMultistatepKaModelOptions <OEProton_OEMultistatepKaModelOptions>`, have been added to assess atomic pKa ranges
  for atoms of a given molecule, and to enumerate all possible ionization states of input molecules
  at neutral/physiological pH (7.4) based on a multistate heuristic pKa model.








QUACPAC  2.1.3
================================================================================

*Fall 2021*

*  Minor internal improvements have been made.


Quacpac TK 2.1.3
================================================================================

*Fall 2021*

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

* :ref:`OEChargeParameter <OEProton_OEChargeParameter>` now accepts case-insensitive
  string input values.



QUACPAC  2.1.2
================================================================================

*July 2021*

* Minor internal improvements have been made.


Quacpac TK 2.1.2
================================================================================

*July 2021*

Minor internal improvements have been made.




QUACPAC  2.1.1.0
================================================================================

*Fall 2020*

* Minor internal improvements have been made.


.. _section_quacpac_releasenotes_2112:

Quacpac TK 2.1.1.2
================================================================================

*March 2021*

* :ref:`OEOptimizedAM1 <OEMolAM1_OEOptimizedAM1>` no longer requires a special ``am1bcc`` license.

* The function :ref:`OEBCCPartialCharges <OEAM1BCC_OEBCCPartialCharges>` no longer requires a special ``am1bcc`` license.


.. _section_quacpac_releasenotes_211:

Quacpac TK 2.1.1
================================================================================

*Fall 2020*

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

* A new preliminary class, :ref:`OEChargeParameter <OEProton_OEChargeParameter>`, has been added as
  part of the extended set of :ref:`OEParameter <OESystem_OEParameter>` classes. The new parameter
  class works with predefined charge engines using :ref:`OEChargeEngineBase <OEProton_OEChargeEngineBase>`
  object.




QUACPAC 2.1.0
================================================================================

*Spring 2020*

* This version of **QUACPAC** has been built using **OEToolkits 2020.0**.



.. _quacpac_releasenotes_110:

QUACPAC 1.1.0
================================================================================

*  Special Note: Version 1.4 of **Molcharge** and version 1.2b of the library have
   been released and inserted into version 1.1 of **QUACPAC**.  Both of these have
   removed support for the VC2003 partial charging method.

*  Version 1.1 is the first full stable release of **QUACPAC**.  **QUACPAC** remains a
   heterogeneous release including five primary applications and a programming
   library with a C++ api.

*  **Tautomers** is in version 2.0.  It provides enumeration of energetically
   reasonable tautomers of input molecules.

*  **Pkatyper** is in version 1.1.  **Pkatyper** provides enumeration of protonation
   states (pKa ~2-~14).

*  **Molcharge** is in version 1.3.  **Molcharge** provides MMFF, AM1, AM1BCC, VC2003
   and other partial charges on small molecules.

*  **Protein_pka** is in version 1.3.  **Protein_pka** carries out PB calculations
   to assess the shifts in protein residue pKa's.

*  This release includes the oeproton library.  The oeproton library exposes
   the features of **Pkatyper**, **Tautomers** and **Molcharge** in three high level C++
   api points. The version of the library in this release is 1.1b.  However,
   the beta moniker signifies only that at this time, OpenEye reserves the
   right to modify this api.  We believe the quality of the code in this
   library is very solid and the beta designation does not reflect its
   quality.



.. _quacpac_releasenotes_130:

QUACPAC 1.3.0
================================================================================

This release represents the first major reworking of the **QUACPAC** toolkits and
applications in several years.  Any users of prior versions of **QUACPAC** will
quickly notice several significant changes.  First, this version of **QUACPAC**
does not contain a new release of `protein_pka` program.  We are in the midst of
a major rewrite of the `protein_pka` program.  We hope that this work will bring
major improvements in the usability, science and analysis of the `protein_pka`
program, yet we do not want to delay the release of the entire **QUACPAC** package
waiting for the `protein_pka` program.  The current **QUACPAC** release does not
contain `protein_pka`, but it will be included in a future release when the
rewrite is complete.  In the interim, we hope you find the bug fixes and new
features included in this release useful.

The preps and qpd programs will no longer be supported future versions of
**QUACPAC**.

New features
--------------------------------------------------------------------------------
*  A reasonable looking tautomer may be calculated by using the `-reasonable` flag.
   
*  A multiconformer method has been added for calculating AM1BCC charges

Bug fixes
--------------------------------------------------------------------------------

*  SMILES map indexes and names are no longer lost when outputting molecules.



.. _quacpac_releasenotes_131:

QUACPAC 1.3.1
================================================================================

New features
--------------------------------------------------------------------------------
*  The distribution and installation of **QUACPAC** has been modified.
   The Windows distribution is now a standard EXE installer, and the
   OS X distribution is a dmg containing a standard pkg installer.
   The executables are now scripts that chose the correct version of
   the program at runtime.  Please see the Application Installation
   section for details.

Bug fixes
--------------------------------------------------------------------------------
*  The previous version had a license failure when AM1 charges were calculated.  This bug has been fixed.



.. _quacpac_releasenotes_150:

QUACPAC 1.5.0
================================================================================

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

*  `fixpka` has been added.  This
   application may be used to set a molecule to an energetically
   favorable ionization state for pH=7.4. This is the same pH model
   that was available in the Filter application.  Additionally, the
   perception of acceptable valence states has been improved to
   include phosphorus as well as aromatic oxygen and sulfur with +1
   formal charge.

*  In `tautomers`: Major improvement for carbon hybridization.  Now carbon atoms with bonds to one, two, or three heavy atoms are able to change hybridization state.  
   However, only carbons close to an appropriate heteroatom are allowed to change hybridization state.  Additionally, unreasonable charge states of carbon have been removed.
   Now the enabling the `-ch3` option will only generate tautomers appropriate for the given level.

*  In `tautomers`: Improvement of the `-reasonable` option, particularly involving exocyclic heteroatoms.

*  In `tautomers`: Added stereo preservation flag `-savestereo` with a default value of `false`.  Stereo chemistry can be lost during creation and removal of double bonds, but if the user
   desires a certain stereo setting to be preserved this flag will prevent the associated atoms and bonds from taking part in tautomerization.

*  `pkatyper` now implicitly uses
   the `-reasonable true` setting 
   for its internal call to `tautomers`. This provides a better reference tautomer when
   enumerating pKa states.

*  In `pkatyper`: Improvements to pka states.

*  In `molcharge`: Aromaticity settings on molecules are now unchanged on returned molecules.  Aromaticity
   may be temporarily changed inside the function while charges are
   being calculated, but the molecule will have the same aromaticity
   after the function as before.  

*  In `molcharge`: AmberFF94 charges can now be applied to standard protein residues.

*  In `molcharge`: A new `-altlocs` flag will retain all alternative locations
   in a disordered .pdb structure when charging. This option allows dictionary-based
   charges such as AmberFF94 to be applied to all atoms in a disordered molecule
   (but should not be used with conformation-dependent charges such as AM1BCC).

Bug Fixes
--------------------------------------------------------------------------------

*  In `tautomers`, atom-ordering could in rare instances be inconsistent for output molecules.  This led to cases where even though all
   associated tautomers led to the same unique tautomer, the unique tautomer could have different SMILES representations depending 
   on the input structure.  This has been fixed.



.. _quacpac_releasenotes_163:

QUACPAC 1.6.3
================================================================================

Release August 2013

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

* `molcharge` now uses the `-method` parameter for selecting a charge model.  All
  individual flags for charge models have been removed.

* `tautomers` will now allow interconversion of 
  [NH2+]= and [NH3+]-.

* `tautomers` now has a `-warts` option.  Enabling this
  options will number the output molecules with an `@` symbol.

* The default AM1BCC charge model in `molcharge`
  now lightly restrains the AM1 geometry
  optimization to the starting coordinates. This allows the important relaxation
  of bond and angle degrees of freedom while greatly reducing the potential to
  alter the molecule's conformation away from its starting coordinates. 

* The AM1BCC charge models `-method am1bccsym` and `-method am1bccspt` in `molcharge`
  now symmetrize the partial charges
  over bond-topologically equivalent atoms, e.g. methyl hydrogens, in keeping
  with the original model. This is especially important with conformationally
  flexible molecules. 

* `molcharge` now has a .fail file to output molecules that do not charge correctly. 

* `fixpka` has been refined to reflect 
  feedback from collaborators.  In particular isoxazoles and oxadiazoles were 
  added while pyrazoles and aryl sulfonamides were refined.  Aryl sulfonamide 
  refinement also incorporated changes based on newly obtained experimental data.

Bug Fixes
--------------------------------------------------------------------------------

* `tautomers` will now properly set stereochemistry 
  on planar carbon to `OEAtomStereo::Undefined`.  Previously, planar carbon could
  inherit stereochemistry from an input molecule with stereochemistry set on a 
  tetrahedral carbon.

* A bug has been fixed in `tautomers` where 3D hydrogens where being suppressed.

* `fixpka` now correctly addresses beta di-amino groups
  so that if all other considerations are equivalent, secondary amines are 
  treated as most basic, followed by primary amines, with tertiary amine being
  treated as least basic.

* A few bugs have been fixed in `fixpka` involving
  quaternary nitrogen and protonated aromatic nitrogens.

* `tautomers` has been
  fixed so that 3D molecules have 3D hydrogens instead of implicit
  hydrogens.

* `molcharge` no longer inadvertently
  converts reduced cysteine residues (CYS) to the oxidized form (CYX)
  when assigning
  Amber partial charges to protein residues.

Other changes
---------------------------------------------------------------------------------

* The `-all` flag has been removed from `tautomers`.  Equivalent results can been achieved 
  with the following options: `-level 7 -ch3 true`.  Level 7 will likely yield a plethora
  of very unreasonable tautomers and is not recommended.

* This will be the last release to support SuSe 10.



﻿.. _quacpac_releasenotes_170:

QUACPAC 1.7.0 
================================================================================

Released October 2016

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

* `-maxtime` flag has been added to tautomer enumeration for setting time limits on searching.
  Its default value is 60 seconds.

* `tautomers` has been dramatically improved to provide a low-energy, medicinally relevant,
  “reasonable” tautomeric form that is suitable for depiction for chemists. Significant
  improvements have been made to the reasonable tautomer algorithm that affect its 
  aliphatic and non-aromatic resonance portions. The depictions below are a useful guide
  for recognizing how tautomers are favored as reasonable:

  - Conversion of carboxylates to diols and nitros to di-hydroxy amines is not favored.

    .. image:: /_images/canonical-tautomer-01.png

  - Generation of unnecessary, non-dative, formal charges is not favored.

    .. image:: /_images/canonical-tautomer-02.png

    .. image:: /_images/canonical-tautomer-03.png

  - Exocyclic bonds adjacent to aromatic rings are accounted for.

    .. image:: /_images/canonical-tautomer-04.png

  - Priority is given to aliphatic double-bond positions.

    .. image:: /_images/canonical-tautomer-05.png

* AM1BCC ELF10, a new method for applying partial charges to a molecule, has been
  added to `molcharge`. AM1BCC ELF10 allows up to 10 diverse conformers to be selected
  from those having the Electrostatically Least-interacting Functional groups (ELF).
  These conformers are then charged with the AM1BCCSym method and the charge sets are
  averaged to come up with a single charge set that is applied to all conformers.
  This yields good quality charge sets even for charged molecules.

* TIP3P water charges are now assigned when using Amber charge sets on molecules containing waters.
  The application of the other Amber charge sets to waters with explicit hydrogens will produce
  oxygen charges of -0.834 and hydrogen charges of +0.417.

* The default value of `-can` flag for `tautomers` has been changed to true.

* `tautomers` will output failed molecules to a fail file. The file will be named either `tautomers.fail`
  or, if the prefix is specified by `-prefix` flag, `prefix.fail`.

* A log file has been added for `molcharge`, `tautomers`, and `pkatyper`.

* `tautomers`, `molcharge`, `pkatyper`, and `fixpka` will now label unnamed input molecules as output_1, output_2, etc.

Bug fixes
--------------------------------------------------------------------------------

* `molcharge` now explicitly supports methods AM1BCCSym (a synonym for am1bcc)
  and AM1BCCSymspt (a synonym for am1bccspt).

* Descriptions for `molcharge` methods have been updated in the usage documentation. In addition,
  a description for `-formal` has been added.

* `pkatyper` no longer uses the deprecated OETyperMolFunction API.

* `tautomers` no longer uses the deprecated OETautomerMolFunction API.

* The wart symbol has been changed from "@" to "_" to help with parsing SMILES formatting.

* Unbounded stack allocations have been removed from `tautomers`.

* amberff94 will no longer identify a CYS residue as anionic when it is bonded by a sulfur to something other than another CYS residue.

* `pkatyper` no longer outputs an empty file if the output format is not supported.

Other changes
--------------------------------------------------------------------------------

* opls method has been removed from `molcharge`.


QUACPAC 2.0.0
================================================================================

*November 2018*

* This version of **QUACPAC** has been built using **OEToolkits 2018.Oct**. The 
  previous version was built using **OEToolkits 2016.Feb**.

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

* The tautomers functionality has gone through major improvements, 
  and the **Tautomer** application options have been redesigned to take advantage 
  of these improvements.

* Keto-enol tautomerization has been added to improve the canonical grouping of 
  unique molecules by their representative tautomers.

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

The following issues has been fixed in **Tautomers**:

* The handling of keto-enol tautomerization by default has been
  improved. The improvement extends to include imine-enamine
  tautomerization and related analogs. The keto and imine forms are
  favored except in the case of 1,3 diketones, where the internal
  hydrogen bond can be formed.

* The process for generating reasonable tautomers for many simple and complex 
  pyridone analogs, pyrrole analogs, and pyridine analogs have been improved.

* An issue that caused double bonds and hydrogens to move too far
  through a series of sp3 centers has been fixed.

* The default behavior of peptide tautomers and peptide stereochemistry
  have been improved.

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

* **pKaTyper**'s output now includes neutral species.



QUACPAC 2.0.1
================================================================================

*May 2019*

* This version of **QUACPAC** has been built using **OEToolkits 2019.Apr**. The previous
  version was built using **OEToolkits 2018.Oct**.

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

* New flag ``-wart`` added to **pKaTyper** to enable adding wart numbers with ``_``
  to each state.

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

* Failed molecules from a **Tautomers** run with ``.sdf.gz`` or ``.oeb.gz`` input
  are now written properly in a correspondiong ``.sdf.gz`` or ``.oeb.gz`` file.

* **Tautomers** output now correctly adds ``wart`` to the molecule names, only when
  there are more than one tautomer.

* Time required to generate an ``.sdf`` output from **pKaTyper** is now comparable
  to generating other formats of output.


QUACPAC 2.0.2
================================================================================

*Nov 2019*

* This version of **QUACPAC** has been built using **OEToolkits 2019.Oct**. The previous
  version was built using **OEToolkits 2019.Apr**.

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

* **FixpKa** now takes a ``-prefix``  parameter.

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

* Progress output for **Tautomers** and **pKaTyper** has been cleaned up.

* **pKaTyper** now outputs the input molecule as is if it fails to enumerate charges,
  instead of producing a fatal error.

* The ``-out`` parameter in **FixpKa** is now optional.

* **FixpKa** now sends warning information to a log file.



.. _quacpac_appendix:

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


*molcharge* Appendix: Complete list of *-method* options
==============================================================================

While there are many allowed options for the *-method* parameter in `molcharge`,
only **am1bccsym**, **mmff** (Default), **amberff99sb**, and  **gasteiger** are
recommended (indicated in italics). The full list is given below\:

   **am1** applies the AM1 semiempirical method to derive the atomic charges for
   the molecule. A full geometry optimization is carried out. A 3D geometry for
   the input molecule is required.

   **am1spt** applies the AM1 semiempirical method to derive the atomic charges for
   the molecule. Only a single-point calculation is carried out, so it is much
   faster but also very sensitive to the input geometry (bad charges from a bad
   geometry). A 3D geometry for the input molecule is required.

   **am1bcc** is a synonym for **am1bccnosym** (described below).

   .. note::
      Note that this differs from the "standard" *AM1BCC* charging scheme as published,
      where symmetrization is done (same as **am1bccsym**).

   **am1bccnosym** applies AM1BCC charges, but *without* averaging bond-topologically
   symmetric charges. The partial semiempirical AM1 geometry optimization is done.
   It requires a 3D geometry associated with an input structure. Non-symmetric
   charges can lead to problems with geometry optimizations and with
   multi-conformer molecules.

   **am1bccsym** (*recommended*) applies AM1BCC charges as published, including partial semiempirical
   AM1 geometry optimization and averaging bond-topologically symmetric charges.
   It requires a 3D geometry associated with an input structure. These are good-
   quality charges for intermolecular interactions involving organic molecules.

   **am1bccspt** is a synonym for **am1bccnosymspt** (described below).

   **am1bccnosymspt** applies AM1BCC charges as published, but *without* averaging bond-topologically
   symmetric charges. Only a single-point AM1 calculation is carried out, so it
   is much faster but also very sensitive to the input geometry (bad charges from
   a bad geometry). A 3D geometry for the input molecule is required.

   **am1bccsymspt** applies AM1BCC charges as published, averaging bond-topologically
   symmetric charges. Only a single-point AM1 calculation is carried out, so it
   is much faster but also very sensitive to the input geometry (bad charges from
   a bad geometry). A 3D geometry for the input molecule is required.

   **amberff99sb** (*recommended*) applies to proteins the RESP charge set used for Amber forcefields
   ff94, ff96, ff98, ff99, ff99sb, and ff99sbc0 (the same charge set is used in
   all these cases). This method only works for standard amino acids. These are
   very good-quality charges for intermolecular interactions involving proteins.

   **am1bccelf10** charging is designed to average the AM1BCC charges from 10 conformers chosen
   from the 2% of the conformer population having the Electrostatically Least-interacting Functional (ELF)
   groups. 10 conformers from 2% means there must be at least 500 conformers to start with; ligands which
   have fewer rotatable bonds may not have this many. In such cases, this method is designed to take all
   the conformers in the 2% ELF population.

   **amberff94**, **amberff99**, and **amberff99bsc0** are synonyms for **amberff99sb**
   The Amber forcefields use the same RESP charge set all cases

   **gasteiger** (*recommended*) applies Gasteiger charges (a charge-equilibration method).

   .. note::
      This method *should not be used for intermolecular interactions.*
      This method was intended for comparing relative reactivity of related
      organic chemical functional groups within different molecular contexts.
      It will work with only a 2D geometry. 

   **mmff** (*recommended*) applies MMFF94 charges. It only requires a 2D geometry. This method ia
   the best choice for use with the MMFF forcefield and these charges are of
   passable quality for intermolecular interactions. This is the default method.

   **initial** sets the charges to the MMFF94 initial fractional charges used
   for charged functional groups, smearing unit charges in the partial charge
   field onto resonance shared atoms.

   **formal** copies the formal charge field of atoms into the partial charge field.

   **none** sets the partial charges to zero.

.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _quacpac_citation:

************
Citation
************

.. note:: To cite QUACPAC please use the following:

    QUACPAC |quacpac_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



.. ROCS documentation master file
.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



#################################
ROCS |rocs_version|
#################################

.. toctree::
   :maxdepth: 2

   introduction
   rocs/rocs
   vrocs/vrocs
   utilities
   tutorials/rocs_tutorials
   theory/shape_theory
   releasenotes/index
   pub
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt





.. _rocs_introduction:

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


************
Introduction
************

==============
Overview
==============

**ROCS** :sup:`®` is a ligand-based virtual screening tool for aligning and scoring a database of molecules to a query or template molecule. The alignments can be used for a variety of purposes. The scores are used to rank molecules based on the probability that they share relevant (biological) properties with the query molecule.

**ROCS** aligns molecules based on shape similarity and their distributions of color or chemical features.
The minimal inputs into **ROCS** are a query molecule in a single 3D conformation and a search database of molecules in multiple 3D conformations. The minimal output is a file of the best alignment and scores for each of the database molecules to the query.

==============
Applications
==============

The **ROCS** distribution comprises 2 applications:

	:ref:`ROCS <chapter_rocs>`

	* Aligns and scores molecules in a database file to a query molecule.

	:ref:`vROCS <chapter_vrocs>`

	* A GUI application for **ROCS**.
	* Interactive generation, editing, and validation of queries for **ROCS**.

==================
Utility Programs
==================

The following utility programs are also included in this distribution:

	* :ref:`chapter_makerocsdb`: Generates a database in an optimized format for
	  searching with **ROCS** from a database of molecules in 3D conformations from OMEGA.

	* :ref:`chapter_chunker`: Divides an input database into a specified number
	  of pieces (chunks) of similar size. Used to generate sub-databases suitable for
	  running large calculations in a ``divide and conquer`` fashion.

	* :ref:`chapter_checkcff`: Applies color features to input molecules that are set
	  based on the input color force field file (CFF). Used to visually check that the
	  CFF is functioning correctly.

	* :ref:`chapter_hlmerge`: Merges multiple output files from **ROCS** into single
	  file. (Re-)ranks **ROCS** hits based on a specified score. Used to combine results
	  from ``divide and conquer`` calculations on sub-databases made using chunker.

	* :ref:`chapter_rocsreport`: Creates a multi-page PDF report document with the hit
	  molecule file generated by ROCS.



.. _chapter_rocs:

*********************************
ROCS
*********************************

.. toctree::
   :maxdepth: 2

   rocs_overview
   rocs_inputs
   rocs_example
   rocs_report_file
   rocs_help
   rocs_req_params
   rocs_opt_params



.. _rocs_overview:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: rocs 

======================
Overview
======================

The application of chemical similarity analysis in drug design is a
commonly used and useful technique. Numerous topological (2D) and
superposition (3D) methods exist for the measurement of chemical
similarity. Methods that work in three dimensions have traditionally
been much slower than 2D methods. This is due in large part to the
fact that 3D methods must have some notion of the energetically
accessible conformational ensembles available to a molecule, while 2D
methods only work with a single structure. 3D methods, however, have
the advantage of being able to find chemically less intuitive
structures that have approximately the same shape and chemical
properties. **ROCS** is designed
to perform large scale 3D database searches by using a superposition
method that finds the similar but non-intuitive compounds that are so
valuable in the drug discovery process.

**ROCS** is a shape-based superposition method. Molecules are aligned by a
solid-body optimization process that maximizes the overlap volume
between them (See :ref:`Shape based alignment method in ROCS<overlay_fig>`).
Volume overlap in this context is not the hard-sphere
overlap volume, but rather a Gaussian-based overlap parameterized to
reproduce hard-sphere volumes
(see :ref:`Shape Characteristics and the use of Gaussians<gaussians_and_shape>`).
ROCS uses only the heavy atoms of a
ligand, hydrogens are ignored. Since shape and volume in this context
are so closely related, a volume overlap maximization procedure is an
excellent method for gaining insights into similar shapes. Although
**ROCS** is primarily a shape-based method, user specified definitions of
chemistry can be included into the superposition and similarity
analysis process which facilitates the identification of those
compounds which are similar both in shape and chemistry.

.. _overlay_fig:

.. figure:: /_images/overlay_theory.png
   :height: 451
   :width: 722
   :align: center
   :alt: Shape based alignment method in ROCS
   
   **Shape based alignment method in ROCS**

Molecular superposition has had limited impact in 3D database
searching because of the slow speed (1-2 molecules/second) of
previously reported superposition methods. **ROCS** can routinely perform
global shape and color alignments at the rate of 600-800 conformers per
second. Medium-sized database searching (10's of millions of
conformers) becomes tractable but slow at this rate of
superposition. Distributed computing makes the entire process much
more facile for screening larger numbers of compounds and
conformers. **ROCS** can automatically split up similarity searches over
entire networks of computers in an efficient and manner
taking full advantage of parallel virtual machines. The coupling of
shape and chemistry screening with a distributed architecture makes
**ROCS** an incredibly powerful tool for searching large 3D
databases.



.. _rocs_inputs:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: rocs

==========================
Input Files
==========================

.. _databasefile:

The Database File
-----------------

The most common use of **ROCS** is overlaying a large collection of
molecules onto a query (reference) molecule. For the purposes of this
document, we'll call this large file the dbase (fit) file. The most common
format for the dbase file is a multi-conformer OEBinary file created
by OpenEye's OMEGA program, however, this file can be one of several
3D formats. These formats include SDF, MOL2 and PDB. ROCS
determines the input file format from the file extension, :file:`.sdf`
or :file:`.mol` for SDF, :file:`.mol2` for MOL2,
:file:`.pdb` or :file:`.ent` for PDB. Gzip compressed files of these same
formats are allowed as well. **ROCS** will interpret :file:`infile.sdf.gz`
as a gzip'ed SDF file.

.. note::

   Note that even though all these formats are supported, using SDF or
   MOL2 can result in a loss of speed due to the huge I/O penalty of
   these formats.

ROCS has no provision for conversion of 1D/2D molecules to 3D. The
input file must already be 3D. More importantly, ROCS will interpret
conformers in the input file as part of a single multi-conformer
molecule as long as they:

* Are contiguous in the input file.
* Have the same numbers of atoms and bonds in the same order
* Have identical atom and bond properties with their order
  correspondent in the subsequent connection table
* Have the same atom and bond stereochemistry

While this may appear to be a restrictive list, many programs write
multi-conformer molecules into SDF or MOL2 files such that the above rules
will be satisfied. If the conformers are named differently, (*i.e.* they
have a conformer number appended to the base name like acetsali_1,
acetsali_2), **ROCS** will still consider them part of a single multi-conformer
molecule if the criteria above are met. For file formats that are not
inherently multi-conformer, this behavior can be turned off with the
:option:`-scdbase` command-line switch. With the :option:`-scdbase` switch on, **ROCS**
will *not* attempt to combine multiple conformers into a single
multi-conformer molecule.

A new molecule file format, specifically for ROCS on large
clusters is the :file:`.rocsdb` format. See the :ref:`chapter_makerocsdb`
section for when to use this file and how to create it.

One other file type is allowed as the dbase file. A file name ending
in :file:`.list` or :file:`.lst` is assumed to be a list of actual
molecule files, one per line. **ROCS** will then open each in turn and
treat the entire collection as a single dbase file. Note that the
conformer detection/concatenation code above will not span the gaps
between these separate files.

Here is an example list file:

::

  part1.oeb.gz
  part2.oeb.gz
  part3.oeb.gz
  hits.mol2

.. _queryfile:

The Query File
--------------

The second required input for a **ROCS** run is a file containing one or
more molecules to be used as the query. **ROCS** will loop over molecules
read in from the dbase file and attempt to overlay each of them against the
query. In order to be consistent with other OpenEye software, this
query molecule can also be referred to as the *reference molecule*.

Normally, **ROCS** treats each molecule in the query file as a single conformer
molecule. For each molecule in the query file, **ROCS** will run a complete
loop over the dbase molecules and write out a hits structure file and
a report file, depending on the values of other command line switches
described below.

Alternatively, **ROCS** can read queries as multi-conformer molecules by
adding the :option:`-mcquery` command line switch. In this mode, **ROCS**
uses the same rules as described in the :ref:`databasefile` section
to determine if two consecutive molecules are actually conformers of
the same molecule. For each multi-conformer molecule in the query
file, **ROCS** will loop over the dbase molecules' conformers comparing
them to all query conformers. By default, **ROCS** will only return the
single best overlay of this NxM set of comparisons. More than one can
be returned by using the :option:`-maxconfs` command line switch.

Shape Queries
-------------

Version 3.0 of **ROCS** introduced a new type of query called a shape query.
It is a format that encompasses multiple elements of shape, including
molecules, color features and grids.  It can be generated
from :ref:`vROCS<chapter_vrocs>` and saved in a shape query file
with the extension ``.sq``.

Grid Queries
------------

ROCS can also use a grid instead of a molecule as a query
(\ [Virtanen-2010]_\). These grids must be in GRASP, OpenEye, OpenEye ASCII Grid
(.agd), CCP4, or XPLOR grid format and can be created with the OpenEye
Grid toolkit or with a graphical application like
GRASP. Certain **ROCS** features are not available when using a grid
query. For example, the color force field features are not available
with a grid query.



.. _rocs_example:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: rocs 

======================
Example Commands
======================

The example commands in this section can be run with files found under
the appropriate version directory in :file:`examples/rocs` under the top level 
installation directory.

ROCS always requires at the very least a file containing the query
molecule(s) and a file containing the database molecule(s). The query
file follows the :option:`-query` command line flag and database
file follows the :option:`-dbase` flag.  When **ROCS** is given no
other arguments besides a query file and a database file, it will
attempt to read the first query molecule, fit all database molecules
to the query molecule, and write out the top 500 structures that have
a Tanimoto Combo score above a given cutoff (default cutoff = -1.0).
It is important to note that a matching structure, or *hi*, is the
best fitting conformer of a database molecule. Only the best fitting
conformer of any molecule will be written out. Even if multiple
conformers of a molecule pass the cutoff, only the conformer which
fits the best will be written out by default.

**ROCS** writes a structure file and a report file for each query
molecule. The :option:`-prefix` command line switch is used to name
these files. The default prefix is **rocs**. The output structure file
is by default :file:`sdf` so that Shape Tanimoto and other
calculated values can be included as tagged data, but the format can
be changed by using the :option:`-oformat` flag or by giving a
specific filename using :option:`-hitsfile`.

Note that as of **ROCS** 2.4, the defaults include using a color force
field (ImplicitMillsDean), optimization against chemistry
(-optchem true) and ranking the hitlist via TanimotoCombo
(-rankby TanimotoCombo).

.. code-block:: bash

   prompt> rocs -dbase database.oeb.gz -query 4cox.sdf 

will cause structures in the file :file:`database.oeb.gz` that match
query molecule in :file:`4cox.sdf` to be written to a file called
:file:`rocs_hits_1.sdf`.  A tab-delimited report file containing the
scores will be written to :file:`rocs_1.rpt`. If
:file:`rocs_hits_1.sdf` is viewed in **VIDA**, hits can be visually
compared with the query and the numerical scores will appear in the
spreadsheet.  Molecules in the hits file and the report file will be
ranked by their TanimotoCombo score.

To prevent continually over-writing output files, the
:option:`-prefix` flag allows you to give unique names to the
files.

.. code-block:: bash

   prompt> rocs -dbase database.oeb.gz -query 4cox.sdf -prefix FOO

will write the hit structures into a file named
:file:`FOO_hits_1.sdf` and the overlay values will be in a file
called :file:`FOO_1.rpt`. As you follow the rest of the examples in
this section, you may wish to use different prefixes each time so that
you can compare how the output files differ.

The :option:`-cutoff` flag is used to control which database molecules are
considered hits.  By default this is set at -1.0. The following demonstrates
changing the cutoff from the default value

.. code-block:: bash

   prompt> rocs -dbase database.oeb.gz -query 4cox.sdf -cutoff 1.0

The difficulty in choosing a cutoff value is that the number of hits
at a given value is not usually known *a priori*, so setting too
high of a cutoff could result in no hits. The :option:`-besthits` and
:option:`-maxhits` flags can be used in conjunction with specifying a
cutoff value to coax **ROCS** into giving output of a manageable
size. Quick searches can be done to assess an appropriate cutoff values
for a particular query molecule. The following demonstrates a search
that will give a quick answer:

.. code-block:: bash

   prompt> rocs -dbase database.oeb.gz -query 4cox.sdf -cutoff 1.0 -maxhits 20

After 20 hits are found above a combo score of 1.0 in
:file:`database.oeb.gz` for the query molecule(s) in
:file:`4cox.sdf` the search terminates and the results are
written.  This option prevents the entire database file from being
searched if a sufficient number of hits are found before the end of
the database file.  Finding the best N hits above a threshold tends to
be a more common exercise.  If the top N hits of a database up to a
maximum of 100 and above a value of 1.0 are desired, the following
search can be done:

.. code-block:: bash

   prompt> rocs -dbase database.oeb.gz -query 4cox.sdf -cutoff 1.0 -besthits 100

If you just want the best N hits regardless of the cutoff,
then using the default cutoff of -1.0 along with :option:`-besthits`
generates the N best:

.. code-block:: bash

   prompt> rocs -dbase database.oeb.gz -query 4cox.sdf -besthits 100

If a report file alone is desired, the output of matching structures can be
suppressed with the :option:`-nostructs` option. For example:

.. code-block:: bash
 
   prompt> rocs -dbase database.oeb.gz -query 4cox.sdf -cutoff 1.0 -nostructs

will only generate a report file for matching structures but the matches will
not be written to a structure file.

By default, **ROCS** uses an inertial frame alignment to generate 4
separate starting positions, optimizes all 4 overlays and selects the
best match of the 4. By default, this inertial frame alignment aligns
the centers-of-mass of the two structures being aligned. If either
molecule is substantially smaller than the other, this may not be the
best starting position, so the choice to use random starting positions
is offered. The command:

.. code-block:: bash

   prompt> rocs -dbase database.oeb.gz -query 4cox.sdf -randomstarts 20

will use 20 random starting positions and keep the best score. Runtime is
proportional to the number of starting positions, so using a large
number for randomstarts can significantly slow down a ROCS job.

ROCS also calculates the Tversky coefficient based either on the
fit (database) molecule (FitTversky) or on the reference (query) molecule
(RefTversky). These scores will appear in the report file and in SD
tags if the structure are written to an SD or OEB file. ROCS can use these
other scores as the ranking score for the hitlist by using the
:option:`-rankby` switch.

To search a database and find the best 300 hits, scored by the
FitTverskyCombo coefficient weighted to each database molecule:

.. code-block:: bash

   prompt> rocs -dbase database.oeb.gz -query 4cox.sdf -rankby FitTverskyCombo -besthits 300

A chemical force field is used by default (ImplicitMillsDean) but a
different one can be specified. Please refer to the chemical force
field (CFF) section for a description of how to define a chemical
force field. To simply calculate the CFF score after finding the best
alignment based on shape use the :option:`-chemff` option. For example:

.. code-block:: bash

   prompt> rocs -dbase database.oeb.gz -query 4cox.sdf -chemff ExplicitMillsDean

To turn off all color and run ROCS as shape overlap only, you can
use the :option:`-shapeonly` flag:

.. code-block:: bash

   prompt> rocs -dbase database.oeb.gz -query 4cox.sdf -shapeonly



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _rocs_reportfile:

.. program:: rocs 

==============
Report File
==============

The **ROCS** report file format appears as a tab-delimited file with the
following fields. Since the names of the query and the hits are of
indeterminate length, fixed size fields for these names could result
in loss of information. Unfortunately this gives a file that is hard
to read in a terminal session, but it can easily be read into a
spreadsheet program or into the spreadsheet in **VIDA**. 

Name
   This is the name of the database molecule. If the database contains
   multi-conformer molecules, the specific conformer index is appended
   to the molecule name with an underscore if :option:`-conflabel`
   is used.

ShapeQuery 
   This is the name of the query molecule. If the query is a
   multi-conformer molecule, then the specific conformer index is
   appended to the molecule name with an underscore.

Rank 
   The numerical ranking in the hitlist, based on the chosen score
   to sort by. Can be altered by using :option:`-rankby` command line
   switches. If the :option:`-stats` command line switch is used with
   **best** or **all**, data is written into the report file in the order
   that the search is performed.  If no hitlist was used in the
   calculation, this field will be 0 (zero).

TanimotoCombo 
   To provide a score that includes both shape fit and color, the
   Shape Tanimoto is added to the Color Tanimoto, resulting in the
   TanimotoCombo score. This has a value between 0 and 2 and is the
   score used for ranking the hitlist when the :option:`-rankby`
   `TanimotoCombo` command line switch is used.

ShapeTanimoto 
   This column gives the Shape Tanimoto, a value between 0
   and 1 as calculated by the Tanimoto equation (see the :ref:`rocs_theory` section).

ColorTanimoto 
   This column gives the Color Tanimoto, a value between 0
   and 1 as calculated by the Tanimoto equation (see the :ref:`rocs_theory` section).

FitTverskyCombo
   To provide a Tversky score that includes both shape and color, the
   FitTversky is added to the FitColorTversky, resulting in the
   FitTverskyCombo score. This has a nominal value between 0 and 2,
   although do due the field nature of shape matching, the value can
   be higher than 2.

FitTversky 
   Shape Tversky is calculated using the Tversky equation
   (see the :ref:`rocs_theory` section)
   with the fit (database) molecule as the main self-overlap
   with beta = 0.95. This was previously called Tversky(d).

FitColorTversky 
   Color Tversky is calculated using the Tversky equation
   (see the :ref:`rocs_theory` section)
   with the database molecule as the main self-overlap
   with beta = 0.95. 

RefTverskyCombo 
   To provide a Tversky score that includes both
   shape and color, the RefTversky is added to the RefColorTversky,
   resulting in the RefTverskyCombo score. This has a nominal value
   between 0 and 2, although do due the field nature of shape matching,
   the value can be higher than 2.

RefTversky
   Shape Tversky is calculated using Tversky equation
   with the reference (query) molecule as the main
   self-overlap term with alpha = 0.95. This was previously called Tversky(q).

RefColorTversky 
   Color Tversky is calculated using the Tversky equation
   with the reference (query) molecule as the main
   self-overlap term with alpha = 0.95.

ColorScore 
   This column provides the actual color score. Since differing color
   force field files can use different strengths for the color forces
   and since each molecule may have a different number of color atoms,
   there is no upper bound on this score. By default, the color score
   is calculated by looping over all the color atoms in the query
   molecule and summing the single best color interaction with the hit
   molecule. This leads to scores that mirror the one-to-one
   correspondence of features sometimes seen in pharmacophore matching
   programs.

SubTan 
   One additional score can be calculated by giving the
   :option:`-subtan` commandline argument. Since there is an
   additional time cost for this calculation, it is not included by
   default. Subtan is defined by taking the positions of the query and
   dbase molecule at the final overlay and removing all dbase atoms
   greater than 1.5 Angstroms from any query atom. Then a shape
   Tanimoto calculation is performed using these 2 structures and this
   Tanimoto coefficient is recorded as SubTan. Note that this has the
   effect of raising scores for small queries against much larger
   dbase molecules. In some respects, this is similar to Tversky for a
   sub-shape match, but does result in different rankings than
   Tversky. It is recommended that for searches involving a small
   query against a dbase of large molecules that both Tversky and
   SubTan be considered.

Overlap 
   This is the absolute value of volume overlap between the query and
   the dbase molecule. The value is in arbitrary units, and is most
   useful when using a grid as query.

DBConformerIndex 
   By default, the actual conformer index of each hit is
   appended to the molecule title. If the :option:`-conflabel` ``sdtag`` or
   :option:`-conflabel` ``both`` is specified, the conformer index will
   appear in this column.



.. _rocs_help:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: rocs 

======================
Command Line Help 
======================

A description of the command line interface can be obtained by executing ROCS
with the `--help` option.

.. code-block:: bash
   
   prompt> rocs --help

will generate the following output:

::

  Help functions:
    rocs --help simple      : Get a list of simple parameters
    rocs --help all         : Get a complete list of parameters
    rocs --help <parameter> : Get detailed help on a parameter
    rocs --help html        : Create an html help file for this program




.. _rocs_req_params:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: rocs 

======================
Required Parameters
======================

.. option:: -query <filename>

   File containing molecules or a single grid to use a shape query. 

   For molecule queries, available formats (and file extensions) include:

   ============ ===========================
   File type    Extension                  
   ============ ===========================
   OEBinary     .oeb .oeb.gz               
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz  
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz             
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz  
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz             
   ============ ===========================

   For grid queries, available formats (and file extensions) include:

   ============== ===========================
   Grid File type Extension                  
   ============== ===========================
   OpenEye        .grd                       
   -------------- ---------------------------
   Grasp          .phi                       
   -------------- ---------------------------
   CCP4           .map .ccp4                 
   -------------- ---------------------------
   XPLOR          .xplor .xplmap             
   -------------- ---------------------------
   ASCII Grid     .agd                       
   ============== ===========================

   For shape queries, only available format and file extension is:

   ================ ===========================
   Shape Query type Extension                  
   ================ ===========================
   OpenEye          .sq                        
   ================ ===========================

   [Aliases=**-ref**,**-q**]

   
.. option:: -dbase <filename>

   File containing one or more 3D molecules to overlay against query
   from above.  This flag supports all the same molecule file formats
   (**not** grids or shape queries) as :option:`-query` plus the ROCS DB format
   :file:`.rocsdb` and the list file (:file:`.lst` or :file:`.list`) as
   described in the :ref:`databasefile` section.
   [Aliases=**-fit**,**-db**]




.. _rocs_opt_params:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: rocs 

=======================
Optional Parameters
=======================

Execute Options
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -param

   The argument for this flag is the name of a
   file containing control parameters.  The control parameter file acts
   to either replace or augment the command line interface.  All
   parameters necessary for program execution may be provided in the
   control parameter file, although any command given explicitly on the
   command line will supersede options found in the parameter file.
   The application generates a new parameter file containing the full set of
   execution parameters upon every execution.  The name of the
   parameter file is created by combining the prefix
   base name with the *'.param'* extension.

.. option:: -mpi_np <n>

   Specifies the number of processors ``n`` when the application is run in MPI mode.

.. option:: -mpi_hostfile <filename>

   Specifies the name of the file containing processors configuration. For every host
   this file should contain a line ``host_name slots=n`` where ``n`` is the number of
   processors on the host.



Input Options
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -mcquery
 
   Combine contiguous conformers in :option:`-query` file into a
   multi-conformer query molecule, following the same rules for
   combining sequential conformers in the :option:`-dbase` file. By
   default, this is false and each connection table in the
   :option:`-query` file is treated as a separate query. Labelling 
   the conformer by adding a wart to the name 
   can be set using the :option:`-qconflabel` parameter.

   [Default=false]

.. option:: -scdbase

   Don't combine contiguous conformers in :option:`-dbase` file into
   a multi-conformer molecule. 

   .. note::

      For :file:`.oeb` files that store a
      multi-conformer molecule directly, this switch has no effect. 

   [Default=false]

General Output Options
^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -prefix <name>

   Prefix used to name output files. Using :samp:`-prefix FOO` will
   create a hits structure file named like :file:`FOO_hits_1.sdf` and
   a report file, :file:`FOO_1.rpt`, where :samp:`_1` will be
   replaced by a sequential number corresponding to the index of the
   query in the :option:`-query` file. Additionally, a parameter file
   containing all options for the current run will be written to
   :file:`FOO.parm`. This parameter file can be used with the
   :option:`-param` switch. 

   [Default=rocs]

.. option:: -outputdir <dirname>

   Output directory for output files. The directory specified by this parameter
   must exist otherwise it will be ignored.

.. option:: -besthits <N>

   Search entire dbase file and keep a hitlist, sorted
   by score given by :option:`-rankby` switch. Size of hitlist is determined by
   integer value N. Note that all members of the hitlist must pass the
   :option:`-cutoff`, if given, so the final size can be smaller than the N
   requested. This switch is ignored if :option:`-maxhits` is given. Note, that if
   this is set to zero (0) and :option:`-maxhits` is also zero (0), then no 
   hitlist will be maintained and all results will be streamed directly to 
   the respective output files.  

   [Default=500]

.. option:: -cutoff <F>

   Cutoff (F) to determine whether a specific
   overlay should be considered good enough for hitlist inclusion. This
   is a floating point value and the actual parameter used for the
   scoring is as defined by the :option:`-rankby` switch. 

   [Default=-1.0]

.. option:: -rankby <score>

   Score to use for ranking the hitlist. Legal values include: 

   * TanimotoCombo
   * ShapeTanimoto (tanimoto)
   * ColorTanimoto
   * RefTverskyCombo
   * RefTversky (tverskyq)
   * RefColorTversky        
   * FitTverskyCombo
   * FitTversky (tverskyd)
   * FitColorTversky
   * Overlap (overlap)

   [Default=TanimotoCombo]

.. option:: -maxconfs <N>

   Maximum number of overlays returned for each
   comparison of a dbase molecule with a query molecule. This defaults to 1.
   As an example, if the query has ``n`` conformers and a given dbase
   molecule has ``m`` conformers, then a total of ``nxm`` overlays
   will be performed. By default, the single best one (1) will be returned 
   (if it passes any :option:`-cutoff` given).  Choosing an alternate value for
   :option:`-maxconfs` will cause up to the top ``N`` of these overlays to be 
   returned and merged into the hitlist. In the hitlist, these conformers will
   not be associated with each other. Throughout a run, some can drop off the
   hitlist while others remain. 

   [Default=1]

.. option:: -maxhits <N>

   Maximum number of hits to return. This option causes ROCS to finish
   as soon as N molecules are in the hitlist. Useful for a quick check
   of a query to see what hits it is finding; this option overrides
   any value for :option:`-besthits`. 

   [Default=0]

Hits Output Options
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -conflabel

   Controls where the conformer index from a database molecule gets labeled on output molecules.  
   The allowed values are none, title, sdtag, and both.

   [Default=title]

.. option:: -qconflabel

   Controls whether the conformer index from a query molecule gets labeled on output molecules.  
   The allowed values are none and title.

   [Default=title]

.. option:: -outputquery

   Put the query structures at the top of the 
   output structure file. This is very useful for keeping the query structure
   in the same file as the hits, so that for instance, you only need to load
   one file into VIDA to browse the results. For a grid query, a copy of the 
   grid will be written to PREFIX\_ref.grd, where PREFIX is defined by the
   :option:`-prefix` commandline option.
   
   [Default=true]

.. option:: -nostructs

   Don't write a structure file. There are times when all you really
   want are the numerical results from ROCS. If you don't want or need
   an output structure file, you can prevent its creation with this
   switch.

   [Default=false]

.. option:: -hitsfile <filename>

   Instead of writing to :file:`PREFIX_hits_n.sdf` (for example) where
   PREFIX is provided by the :option:`-prefix` commandline flag, write all hit
   structures to the file provided with this flag. Can be a filename
   or full/relative path.  Also, if the name provided is actually a
   molecule file format extension (i.e. .sdf, .mol2.gz, .oeb, etc.),
   ROCS will write to :file:`stdout` using the format derived from the file
   extension. For example if the following is used:

   .. code-block:: bash

      -hitsfile .sdf

   then ROCS will write all the hits out to :file:`stdout` in SDF format.
  
   Note that this option will only work for a single query. If more
   than one query is provided along with the :option:`-hitsfile` option, ROCS will 
   issue an error and stop.

.. option:: -oformat <extension>

   Format for the output structure file(s). This option gives a file
   extension to be used for all output structure files.  The format
   for the file is determined from the extension. Valid values include
   all the molecule file formats listed in the table above for
   :option:`-query` files.

   [Default=oeb.gz]

.. option:: -sdTags

   This parameter controls whether to attach score information to output molecules as SD data. 

Report Output Options 
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -reportfile <filename>

   Instead of writing to :file:`PREFIX_n.rpt` where PREFIX is provided
   by the :option:`-prefix` commandline flag, write all report
   information (stats) to the file provided with this flag. Can be
   filename or full/relative path. Note that if more than one query
   molecule is provided, this flag will not work unless the
   :option:`-report` flag is also set to :samp:`one` to put all report
   info into one report file.

.. option:: -report

   Controls report file generation. The default, :samp:`each`, writes a
   separate report file for each query in the :option:`-query` file. If
   :samp:`one` is chosen, stats for multiple queries in the same
   :option:`-query` file will be placed in a single report file. This is
   useful for computing a NxN comparison of a file as both the dbase
   and query. Finally, to prevent ROCS from writing report files, use
   :samp:`none`. 

   [Default=each]

.. option:: -stats

   Determines which stats get placed into report files.  Values
   include :samp:`hits` (the default), :samp:`best` and :samp:`all`.
   The default is to include just the stats for the compounds in the
   hitlist. If :samp:`best` is chosen, the report file will include
   stats for the best overlay(s) for every dbase molecule. The number
   of best overlay score is determined by the value of
   :option:`-maxconfs`.  Finally, if :samp:`all` is given, stats for
   every single overlay will be placed in the report file. Be
   careful. For a multi-conformer query against a large dbase file,
   :samp:`all` can generate a HUGE amount of data.

   [Default=hits]

Status Output Options 
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -statusfile <filename>

   Instead of writing to :file:`PREFIX_n.status` where PREFIX is provided
   by the :option:`-prefix` commandline flag, write all status
   information to the file provided with this flag. Can be
   filename or full/relative path. Note that if more than one query
   molecule is provided, the status written to this file is only for the
   most recently processed query.

.. option:: -status

   Controls status file generation. The default, :samp:`each`, writes a
   separate status file for each query in the :option:`-query` file. If
   :samp:`one` is chosen, the status for multiple queries in the same
   :option:`-query` file will be placed in a single status file.
   Note that if more than one query
   molecule is provided, the status written to this file is only for the
   most recently processed query.
   Finally, to prevent ROCS from writing status files, use
   :samp:`none`. 

   [Default=each]

Log Output Options
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -logfile <filename>

   Filename for log file. Overrides log filename created from :option:`-prefix`.

.. option:: -progress <method>

   Method for showing job progress on the command line. Choices include:

   * percent - show a percent complete progress bar (DEFAULT)
   * log     - echo the log message for each molecule
   * logoutput - write each log line to screen
   * dots    - show dots
   * none    - print nothing to console 

.. option:: -verbose

   Add extra verbosity to log file.

Shape Options
^^^^^^^^^^^^^^^^^^^^^^
   [Aliases=**-v**]

.. option:: -tanimoto_cutoff <F>

   Flag that can be used to limit output hits to only those with some
   minimum shape score. This can be used regardless of which score is
   chosen (:option:`-rankby`) for ranking the hitlist. For example, using:

   .. code-block:: bash
  
      -rankby TanimotoCombo -cutoff 1.1 -tanimoto_cutoff 0.6

   any molecule with Shape Tanimoto <= 0.6 will not be
   retained. Additionally, the constraint on TanimotoCombo to be at
   least 1.1 implies that Color Tanimoto must also be > 0.5 so that
   the sum can be greater than 1.1.

   [Default=0.0]

.. option:: -randomstarts <N>
   
   Specifies number (N) of random starting positions to try instead of
   inertial frame overlay as described in the theory section. Since
   inertial frame alignment involves 4 (or 8 in the case of highly
   symmetric molecules) starting positions, setting
   :option:`-randomstarts` to a value much larger will result in much
   slower run times.

.. option:: -subtan

   Also calculate sub-Tanimoto score. See the :ref:`rocs_reportfile` section 
   for a complete description of how sub-Tanimoto is calculated.

.. option:: -subrocs

   Specifies starting the search at all heavy atoms of the larger molecule 
   as well as the default inertial starts.  The larger molecule is chosen
   by comparing the self shape-overlap terms of the query and database molecule.
   The :option:`-subrocs` option is especially useful when the query and database
   molecules have a large difference in size.

.. option:: -shapeonly

   A color force field is used by default and
   optimization against shape and color is the default overlap method. It is
   incompatible with a shape file. As an easy way to run ROCS with just shape
   overlap, this flag is the equivalent of setting:

   ::
   
      -chemff none
      -optchem false
      -rankby tanimoto

.. option:: -scoreonly

   Perform scoring calculation only on input molecules. Sets the following flags:

   :: 

      -opt false
      -optchem false
      -besthits 0
      -maxhits 0
      -scdbase  

.. option:: -opt

   Turn optimizer on if true, off if false. Not normally used
   by itself, but with other flags via the :option:`-scoreonly` flag. 
   
   [Default=true]

Color Options
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -chemff <cffname>

   Color-force-field name. Either the name of one of the built-in
   color force fields (ImplicitMillsDean or ExplicitMillsDean) or the
   name of a user-defined color force field file. The format of this
   file is given in the :ref:`colorforcefield` section.
  
   [Default=ImplicitMillsDean]

.. option:: -optchem

   Use color force field forces and gradients as part of 
   overlay optimization. Ignored when :option:`-opt` is ``false``.

   [Default=true]

.. option:: -coloronly

   Enables overlay optimization against only the color components, i.e., color
   atoms for a molecule or color gaussians for a shape query, of the query. This
   provides a color equivalent option of the corresponding ``-shapeonly``
   option.

   [Default=false]



.. _chapter_vrocs:

*********************************
vROCS
*********************************

.. toctree::
   :maxdepth: 2

   vrocs_overview
   vrocs_setup_run
   vrocs_res_viz
   vrocs_stats
   vrocs_saving
   vrocs_query_source
   vrocs_edit_query
   vrocs_menus



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _vROCS_usage:

.. program:: vROCS 

=============
Overview
=============

**vROCS** provides a single user interface from which the user can build/edit 
**ROCS** queries, set up **ROCS** runs and analyze/visualize the results.  It also 
includes rigorous statistics tools for validating a query, facilitating the 
comparison of different queries and selection of the most appropriate query for the project.

There are four primary workflows (tasks) in **vROCS** available from an 
initial :ref:`Welcome page<task_select_fig>` with a button for accessing each task.  
Each workflow provides the tools required to guide the user through the task.  
These workflows are:

1. Perform a simple **ROCS** run
2. Create a query with a wizard
3. Create or edit a query manually
4. Perform a **ROCS** validation

.. _task_select_fig:

.. figure:: /_images/task_select.png
   :scale: 100
   :align: center
   :alt: vROCS Welcome page
   
   **vROCS Welcome page**


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _run_setup:

.. program:: vROCS

=============================================
Setup a simple run and a validation run
=============================================
**vROCS** guides the user through all the steps of setting up and performing a
**ROCS** run and visualizing and analyzing the results.  There are two main run
types for which a user would wish to employ **ROCS**.

1. Simple run
2. Validation run

From the Welcome page click on the button to ``Perform a simple
ROCS run`` or ``Perform a ROCS validation`` to bring up the :ref:`Run
set-up dialog<run_setup>`.

.. list-table::
  :widths: 50 50
  :header-rows: 0

  * - .. image:: ../images/vrocs/run_setup_1.png
    - .. image:: ../images/vrocs/run_setup_2.png
  * - **Simple run setup**
    - **Validation run setup**

|
|
|

:Run Name: Editable name that will be used for the **ROCS** run and displaying the
           results in **vROCS**.
:Color F.F: A dropdown menu that allows selection of the current
            :ref:`color force field<colorforcefield>`.
            Options are:

            - Implicit Mills Dean (default unless changed in User Preferences),
            - Explicit Mills Dean

            If a custom color force field was selected using ``ROCS > Preferences``
            then this will also be available here.  The current force field cannot
            be changed for a specific active query.  Changing the current force
            field in the dropdown will filter the active query list to show only
            queries which use that color force field.  Opening a saved query file
            (\*.sq, \*.sq.gz) will use the color force field previously associated
            with that file and the active force field in the Color F.F. dropdown
            will change to reflect this.
:Query: List of queries that can be selected for the **ROCS** run.  Click on
        ``Open queries...`` or the folder icon to browse to saved **ROCS**
        query files (molecules/grids/queries).  Click on the black down arrow
        icon to select from a list of recently used queries.  The source file
        path is shown below the opened query name.  Queries built in the **vROCS**
        query editor are automatically added to this list for the current **vROCS**
        session.  The query highlighted in blue is the selected (active) query.
        The query name can be edited (pencil) or the query can be deleted from
        the list (red X).  Corresponds to the ``-query`` command line flag.
:Database: The source of ligands which ROCS is to align to the query file during a
           simple ROCS run.  Click on ``Open database...`` or the folder icon to browse
           to database files.  Click on the black down arrow icon to select from
           a list of recently used databases.  Corresponds to the ``-dbase`` command
           line flag.
:Actives: The source of 'active' ligands which **ROCS** is to align to the query file
          during a **ROCS** validation run.  Click on ``Open database...`` or the folder
          icon to browse to database files.  Click on the black down arrow icon
          to select from a list of recently used databases.
:Decoys: The source of 'decoy' ligands which **ROCS** is to align to the query file
         during a **ROCS** validation run.  Click on ``Open database...`` or the folder
         icon to browse to database files.  Click on the black down arrow icon
         to select from a list of recently used databases. The number of decoy ligands
         cannot exceed 100,000.
:Home: Return to the Welcome screen or the **vROCS** query editor.
:Next: Proceed to the Run set-up details Inputs tab.  This button only becomes
       active once the query and database (or actives and decoys) files are selected.
:Run: Run ROCS using the selected run name, query and database (or actives
      and decoys) and default parameters.  Only becomes active once query and
      database (or actives and decoys) are selected.

The input for **ROCS** is a shape-based query with optional color atoms and one (or more)
databases of molecules to search.  The query shape is most frequently derived from a
ligand of interest although other sources are possible, such as a variety of grids
built in AFITT, Spicoli, OEDocking, OEChem and third party tools
(see :ref:`ROCS Shape Query Sources<shape_query_sources>`).  **vROCS** allows the user to
load a pre-saved query for **ROCS**, having 3D coordinates, or to build or modify one *in
situ*.  The list of available queries for a specific run is filtered based upon the
type of color force field shown in the Color F.F. drop down.  The database(s) are
required to be prepared externally with 3D coordinates generated and conformers
enumerated, usually by OMEGA. (See :ref:`Simple run setup and Validation run setup<run_setup>`)

Simple Run
----------

A simple run aligns a database of pre-computed molecular conformers
against a query.  For each molecule in the database it overlays every conformer based
on molecular shape with the option to employ color force fields.  For a full description
of the shape and Gaussian theory employed by **ROCS**, see :ref:`Shape Theory<rocs_theory>`.
The conformers are scored based upon the Gaussian overlap to the query and the best
scoring conformer is reported.  The most common scores are ShapeTanimoto (shape alone),
or TanimotoCombo (shape + color) which is the default for **ROCS** and **vROCS**.
The molecules in the
database are finally ranked by the scores for their best aligned conformers.  This
type of simple **ROCS** run is commonly used when lead-hopping i.e. looking for structurally
dissimilar molecules which have a higher probability of biological activity at the same
target as the query while also overcoming issues such as ADME/Tox or patent coverage.
Numerous literature examples of this application exist and some representative examples
are given here.

.. note::

  See :ref:`List of selected ROCS publications<rocs_pubs>` for a list of selected **ROCS** publications.
  Lead-hopping examples include:

  * :ref:`A Shape-Based 3-D Scaffold Hopping Method and its Application to a Bacterial Protein-Protein Interaction<paper2>`
  * :ref:`Scaffold hopping, synthesis and structure-activity relationships of 5,6-diaryl-pyrazine-2-amide derivatives: A novel series of CB1 receptor antagonists<paper8>`
  * :ref:`Novel Approach for Chemotype Hopping Based on Annotated Databases of Chemically Feasible Fragments and a Prospective Case Study: New Melanin Concentrating Hormone Antagonists<paper18>`

Validation Run
--------------

Before running a simple **ROCS** run on a large database, e.g. a corporate
database of thousands or potentially millions of compounds (and even more conformers!),
one should have confidence that the query is indeed able to distinguish true actives
from inactives.  For this purpose the validation **ROCS** run is employed.  The major
difference when setting up a validation run is that the validation run searches two
sets of compounds, whereas the simple run searches only a single database.  These
two datasets are:

1. A set of molecules known to possess the desired biological activity.  These are the actives.
2. A set of molecules known (or presumed) not to possess the desired biological activity.
   These are the decoys.  The decoys can be a random set of molecules from a database or
   could be property matched (e.g. DUD [Huang-2006]_\ ) for a more stringent validation.

The method of alignment of compounds is the same for both run types (simple and validation).
In the case of the validation run the desired result is that molecules from the set of
actives are generally scored more highly than the set of decoys i.e. they have a greater
shape similarity.  Measurement of the degree of selectivity between these two datasets
provides the user with confidence that the query is, indeed, selective and suitable for
use in a simple **ROCS** run on a larger dataset.

A good validation experiment is vital to the success of future research.  It needs to be
carefully planned and set up e.g. selection of active and decoy datasets as well as query
design (see :ref:`Editing ROCS Queries in vROCS<editting_queryies>`).  For example, is a modification to a
query really beneficial to the selectivity of that query?  The rigorous use of validated
statistical methods and parameters to analyze and, more importantly, compare runs is
essential and frequently overlooked.  For that reason statistical analysis tools are
included in **vROCS** when visualizing the results of a **ROCS** validation run.  These are
described below in :ref:`Statistics Metrics<statistical_metrics>`.

The run set-up options pages (See :ref:`Simple run options and Validation run options<run_setup_options>`) in
**vROCS**  are pre-populated with the default **ROCS** options e.g. how compounds are
initially oriented and aligned and how  alignments are scored and ranked.  These
default values are calculated to give a good starting point in the majority
of examples.  However, these are also some of the most common options that
a **ROCS** user might want to modify.  For example,
changing the start type from inertial to random can be particularly useful for a
grid-based query (as opposed to a shape-based query) because it is more difficult
to identify and set the 4 true inertial points for a grid.  The disadvantage of
using random starts and setting this number to be high is that it will significantly
increase the run time.  Deselecting the 3D view option will speed up runs,
particularly on computers with limited compute resources.  By default an Open GL 3D
alignment for each compound is shown as the run progresses and, since this can
be somewhat CPU intensive, switching the display off can be beneficial.

.. _run_setup_options:

.. list-table::
  :widths: 75 50
  :header-rows: 0

  * - .. image:: ../images/vrocs/run_setup_opts_1.png
    - .. image:: ../images/vrocs/run_setup_opts_2.png
  * - **Simple run options**
    - **Validation run options**

|
|
|

:Working Directory: Directory in which the files for the **ROCS** run are to be saved.
                    Default location is the **vROCS** installation directory, if it is user
                    writable, otherwise, a temporary directory is used.  Click on
                    the folder icon to browse and select alternative directories.
                    Corresponds to the ``-outputdir`` command line flag.
:Best Hits: Number of top ranking hits to be saved after searching the entire
            database.  Use the arrows to increase/decrease or type the desired
            number in the field.  Corresponds to the ``-besthits`` command line
            flag.  Only available for simple **ROCS** run.
:Prefix: Naming prefix for the current **ROCS** run.  All the output **ROCS** files
         will contain this name.  If no name is specified the default is
         "rocs".  Corresponds to the ``-prefix`` command line flag.
         The output files using the prefix are: Parameter file (prefix.parm), Log file (prefix.log), Report file (prefix_1.rpt), Status file (prefix_1.status), Structure file (prefix_hits_1.oeb.gz)
:Rank by: Dropdown allows selection of one of the many score types available in vROCS.
          The results will be ranked by the selected score for selection of Best
          N hits (above).  Default is TanimotoCombo.  Corresponds to the
          ``-rankby`` command line flag.  Available scores are:
          TanimotoCombo, ShapeTanimoto, ColorTanimoto, 
          Combo Reference Tversky, Shape Reference Tversky, Color Reference Tversky,
          Combo Fit Tversky, Shape Fit Tversky, Color Fit Tversky, Overlap
:Score Cutoff: Check the check box to exclude any hit with a score less than the
               specified value from the hitlist.  The score used is the one
               specified by the Rank by field.  Change the cutoff value by using
               the arrows to increase/decrease or type the desired number in the
               field.  The allowed score range varies according to the score selected
               in the Rank by field. Corresponds to the ``-cutoff`` command line
               flag.  Only available for simple **ROCS** run.
:Tanimoto Cutoff: Check the check box to exclude any hit with a ShapeTanimoto score
                  less than the specified value from the hitlist.  Change the
                  cutoff value by using the arrows to increase/decrease or type
                  the desired number in the field.  The allowed score range is 0-1
                  (min-max). Corresponds to the ``-tanimoto_cutoff`` command line
                  flag.  Only available for simple **ROCS** run.
:Shape Only: Check the check box to perform a shape only overlay, turning off
             the color force field.  Corresponds to the ``-shape_only``
             command line flag.
:Score Only: Check the check box to score the incoming poses against the query
             in their current 3D coordinate frame, turning off alignment and
             hitlist.  This is useful for scoring a pre-aligned dataset.
             Corresponds to the ``-score_only`` command line flag.  Only available
             for simple **ROCS** run.
:Start Type: Use the radio buttons to specify how **ROCS** places the initial
             alignment.  Inertial is the default option and uses 4 initial starts.
             Random specifies using random starts for the
             initial overlay and corresponds to the ``-randomstarts`` command
             line flag.  Specify the number of random starting
             configurations by using the arrows to increase/decrease
             or type the desired number in the field.
:Color Optimize: Check the check box to use the color force field in the
                 optimization of the alignments.  Default is checked on.
                 Corresponds to the ``-optchem`` command line flag.
:Full Optimization: Check the check box to perform full best overlay optimization.
                    Default is checked on.  If off (false) then score only.
                    Corresponds to the ``-opt`` command line flag.
:3D View: Check the check box to select whether a 3D view of the query and
          database molecules aligning is displayed as the run progresses.
          Default is on.
          If checked off a text-based progress screen is displayed.  This will
          increase ROCS' run speed on low powered computers.

The final page of set-up is the Run Summary on the :ref:`Run Rocs<run_summary_fig>` page.
The summary gives a quick rundown of the query file and database used, as well
as the **ROCS** version.  It also contains a collapsible panel to display the full
set of command line options that will be fed to **ROCS** and will be saved as the
ROCS parameter file (.parm).  This can be useful when setting up and validating
runs in **vROCS** that will later be run on the command line across a remote cluster.
The **Additional Options** prompt allows entry of a command not listed in the
command line such as a new parameter not yet available in the released
version of **ROCS**.

.. _run_summary_fig:

.. list-table::
  :widths: 50 50
  :header-rows: 0

  * - .. image:: ../images/vrocs/run_summary_1.png
               :align: center
    - .. image:: ../images/vrocs/run_summary_2.png
  * - **Simple run summary**
    - **Validation run summary**

:Query:          Query file as specified on the Inputs tab
:Database:       Database file as specified on the Inputs tab in a simple run
:Actives:        Actives database file as specified on the Inputs tab in a validation run
:Decoys:         Decoys database file as specified on the Inputs tab in a validation run
:Output:         Working directory where all files will be written.
:Prefix:         Naming prefix for the output files that will be written to the
                 Working Directory, as specified in the Options tab.  This is
                 defined by the Prefix field on the Options tab.
:Command Line...:  Click to display/hide the full command line that will be sent to
                 the ROCS executable.  This can be copied to export and use in
                 command line ROCS installations.  A field is available for typing
                 additional ROCS parameters that will be included in the command
                 line not exposed via the vROCS interface.  Note that the
                 command line may use temporary files in some instances.



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _vrocs_res_viz:

.. program:: vROCS 

===================================
Results visualization and analysis
===================================

The **vROCS** interface provides multiple tools for results visualization and analysis.  
The :ref:`3D visualization window<results_viz>` shows the query where the molecule 
structure is displayed as green sticks with associated shape and color atoms.  All 
three portions (molecule, shape and color) can be made visible or hidden using 
controls in the window.  The aligned 
hit molecules are shown as sticks colored by atom type.  Buttons at the bottom of the 
3D window allow the shape grid, shape atoms, color atoms and color atom labels to be 
toggled on or off.  The color of the shape contour can be changed and the contour 
level displayed for the shape grid can also be modified using a slider.  This is 
particularly useful when adding color atoms to a grid-based query, for example.

.. _results_viz:

.. figure:: /_images/results_vis.png
   :scale: 100
   :align: center
   :alt: 3D visualization window
   
   **3D visualization window**

.. list-table::
  :widths: 15 50
  :header-rows: 1
  
  * - Icon
    - Description
  * - .. image:: ../images/vrocs/table4/icon_fit_scene.png
    - Fit scene to screen
  * - .. image:: ../images/vrocs/table4/icon_fit_query.png
    - Fit query to screen
  * - .. image:: ../images/vrocs/table4/icon_screenshot.png
    - Take screenshot of 3D Window (excludes the gray query information panel)
  * - .. image:: ../images/vrocs/table4/icon_3d_parameters.png
    - Show/hide the :ref:`3D parameters control window<three_d_parameters_fig>`
  * - .. image:: ../images/vrocs/table4/icon_edit_query.png
    - Edit query: Open the Edit Query panel and add the query editing icons 
      (See :ref:`Editing ROCS Queries in vROCS<edit_query_fig>`).  This icon 
      is replaced by a Done Editing icon while in editing mode.
  * - .. image:: ../images/vrocs/table4/icon_contour_color.png
    - Change color of the contour
  * - .. image:: ../images/vrocs/table4/icon_contour_toggle.png
    - Toggle display of the shape contour on/off
  * - .. image:: ../images/vrocs/table4/icon_shape_toggle.png
    - Toggle display of shape atoms on/off
  * - .. image:: ../images/vrocs/table4/icon_color_toggle.png
    - Toggle display of color atoms on/off
  * - .. image:: ../images/vrocs/table4/icon_label_toggle.png
    - Toggle display of color atom labels on/off
  * - .. image:: ../images/vrocs/table4/icon_contour_slider.png
    - Slider to adjust display level of the shape contour from 0-3 (default 1).  
      This only changes the contour display and not the query itself

The :ref:`3D parameters control window<three_d_parameters_fig>` provides user control for graphics 
rendering of the image in the 3D window.  

The font size for text labels in the 3D display can be altered, as can
the stereo visualization type and settings.  Not all stereo settings are
available on all machines and therefore some stereo options may be grayed out.
See :ref:`the 3D parameters table<three_d_parameters_table>` below for details.

.. _three_d_parameters_fig:

.. figure:: /_images/three_d_parameters.png
   :scale: 75
   :align: center
   :alt: 3D Parameters control window
   
   **3D Parameters control window**

.. _three_d_parameters_table:

:Text Scale:
 	  Slider to adjust the size of the font for the color atom labels.
:Stereo Off:
      Disable stereo graphics.
:Splitscreen:
      Display the image in the 3D window in splitscreen stereo mode for 
      unassisted 3D viewing.
:Stencil:
      Display the image in the 3D window in a format suitable for viewing 
      with a Zalman Trimon LCD 3D monitor (or similar hardware).
:Hardware:
      Enabled only on machines which are capable of performing 3D hardware 
      stereo-in-a-window.  Hardware stereo requires a graphics card that supports 
      "stereo in a window" display as well as the appropriate stereo glasses.
:Angle:
      Slider to adjust the angle between the images for splitscreen, 
      stencil or hardware stereo modes.
:Separation:
      Slider to adjust the separation between the images for splitscreen, 
      stencil or hardware stereo modes.

A :ref:`results spreadsheet<result_spread_fig>` below the main 3D window lists results for 
each molecule (with best-fitting conformer number) and its associated scores.  
The data is displayed for the run associated with the highlighted Run Name tab. 
Individual or multiple molecules can be observed overlaid with the query in the 
3D window.  Only the top 20 scoring molecules are displayed in the spreadsheet, 
based on the ``Rank by`` score selected in the Run Set-up Options tab.  The spreadsheet
can be resorted by clicking on other column headers, and the top (or bottom) results for
that column will be displayed.  Note: this can be a DIFFERENT set of 20 molecules than were 
displayed originally.  To see ALL 
results users are encouraged to use the spreadsheet tools in **VIDA**.  
This can be done by right-clicking on the Run Name tab in the results panel and following 
the option to "Open 'Run Name' in **VIDA**".  

.. _result_spread_fig:

.. figure:: /_images/results_spreadsheet.png
   :scale: 100
   :align: center
   :alt: Results Spreadsheet
   
   **Results Spreadsheet**

.. list-table::
  :widths: 15 50
  :header-rows: 1
  
  * - Icon
    - Description
  * - .. image:: ../images/vrocs/table6/icon_display_hide_results.png
    - Display/hide the results panel.
  * - .. image:: ../images/vrocs/table6/icon_show_rocs_output.png
    - Show the ROCS output.  This is the information that 
      would be displayed in the terminal window during a command line ROCS run.
  * - .. image:: ../images/vrocs/table6/icon_show_spreadsheet.png
    - Show the results spreadsheet.
  * - .. image:: ../images/vrocs/table6/icon_show_statistics.png
    - Show the statistics panel.  Only available for ROCS validation run.
  * - .. image:: ../images/vrocs/table6/icon_visible.png
    - Make this compound visible in the 3D window and keep it 
      visible while scrolling through other results.
  * - .. image:: ../images/vrocs/table6/icon_delete.png
    - Delete the results for the highlighted Run Name tab

The spreadsheet columns include the name of the database 
compound, the name of the query, 14 different scores (see :ref:`section Report File<rocs_reportfile>`
for full definitions) and a rank column (based on the score type chosen when setting up the run).  
The available scores are:

1. TanimotoCombo
2. ShapeTanimoto
3. ColorTanimoto
4. Ref Tversky
5. RefColorTversky
6. RefTverskyCombo
7. FitTversky
8. FitColorTversky
9. FitTverskyCombo
10. ColorScore - score type from older **ROCS** versions not available as a Rank by... choice but can be used to sort the spreadsheet.
11. SubTan - score type from older **ROCS** versions not available as a Rank by... choice but can be used to sort the spreadsheet.
12. Overlap

The spreadsheet for a validation run has an additional three columns:

13. Active - indicates whether the compound was in the set of actives (1) or decoys (0)
14. Rocs_db_index - identifies the placement of each compound in the database 
    ROCS formed by combining the active and decoy sets prior to search.  
    This is required in case a compound in the actives and decoys happens 
    to have the same name.
15. Lingos similarity - the 2D fingerprint similarity to the query, if the query is a molecule
  
The spreadsheet can be sorted by any field.  If an alternative score is chosen for 
sorting then the best 20 molecules by that score will be displayed.  This may be 
a different set of molecules from the original 20 displayed because **vROCS** 
sorts and retrieves data from the saved structure hitlist and report files.  
Additionally, the spreadsheet includes controls to show/hide or mark each molecule.  
This allows the user to compare overlays between compounds and against the query 
in the 3D visualization window as well as control the data that is saved out.

The most common scores used are ShapeTanimoto (shape only) or the default score, 
TanimotoCombo (shape + color).  Tanimoto scores should be used when the query 
and database molecules are a similar size.  Tversky scores include a weighting 
factor to deal with size differences and are therefore useful when the query is 
small and the database molecules are large, or *vice versa*.  The RefTversky score 
is weighted for a small query e.g. to find all instances of a known active 
scaffold fragment in a database.  The FitTversky score has the opposite weighting.

Additionally the validation runs have a :ref:`statistics panel<statitistics_fig>` available.
It provides several statistical metrics for analysis of the quality of the results.  
The metrics reported in **vROCS** consist of the following and are described below:

1. ROC (receiver operating characteristic) curve together with its AUC (area under the curve) 95% confidence limits
2. Score histogram to examine the distribution of scores obtained for the active and decoy datasets
3. Early enrichment at 0.5%, 1% and 2% of decoys retrieved 95% confidence limits
4. When comparing multiple runs p-values are calculated for each enrichment level & AUC

These metrics and the rationale behind their inclusion are fully described in the section 
:ref:`Statistics Metrics<statistical_metrics>`.

.. _statitistics_fig:

.. figure:: /_images/statistics_panel.png
   :scale: 75
   :align: center
   :alt: Statistics Panel
   
   **Statistics Panel**

|
|

.. _statistics_table:

:Compare to:  Add the results from another run to the statistics 
              spreadsheet and calculate the p-values between the two 
              runs.  The additional run will also be plotted in the ROC 
              curve and score histogram.  The dropdown lists None, Lingos 
              and all other validation runs available from that vROCS 
              session.  Lingos is the 2D similarity and is always 
              available as a comparison choice with molecular queries.
              Default is None.
:Save:        Chose score, plot or spreadsheet data to save as ``.csv`` 
              format for the active run.  If another run(s) is selected 
              in the ``Compare to`` field that data will also be saved.
              Select Plot data to save an image file of the ROC plot or score
              histogram.
:Chart:       Select from a dropdown whether to display the ROC curve 
              or the score histogram
:Metric:      Select one of the scores (metrics) to be used for the ROC 
              plot or score histogram.  These correspond to the score 
              columns in the results spreadsheet

The statistics panel includes a spreadsheet listing the values for 
the statistics metrics, together with score histograms and an ROC 
plot from which is calculated the AUC
(See section :ref:`Statistics metrics<statistical_metrics>`.  
The ROC plot graphs actives *vs* decoys and a higher AUC represents 
greater selectivity in favor of the actives.  The ROC curve can 
be plotted for any of the 14 scores available (See :ref:`ROC plot<roc_fig>`).  
Note that changes to the score used for the ROC plot will probably 
cause changes to the AUC and enrichment values.  

.. _roc_fig:

.. figure:: /_images/roc_plot.png
   :scale: 75
   :align: center
   :alt: ROC plot
   
   **ROC Curve**

Instead of the ROC plot a score histogram can be plotted.  The score 
histogram compares the distribution of scores for the actives and the 
decoys (See :ref:`Score Histogram<score_histogram_fig>`).  The better the 
AUC (closer to 1.0), the greater the separation will be, in general, between the 
two histograms, with the actives scoring higher and 
further to the right than the decoys.

.. _score_histogram_fig:

.. figure:: /_images/score_histogram.png
   :scale: 75
   :align: center
   :alt: Score Histogram
   
   **Score Histogram**

To better visualize the plots the plot area can be resized by dragging 
the divider between the plot and spreadsheet.  The statistics panel 
can also be resized by moving the divider between the panel and the 3D window.

Multiple runs can be compared in the spreadsheet. 
The statistics panel enables the comparison of multiple validation runs 
using the ``Compare to`` dropdown and the data and plots can be exported to 
a CSV (``.csv``) file for import into other applications or statistics packages.  
The statistics for multiple runs will be 
displayed side by side in a spreadsheet and these runs will be plotted 
together on the ROC plot and score histogram for a direct comparison.  
This could help to answer the following questions:

* Is one query more selective than another on the same database?  
* Is the query selectivity the same for multiple training databases? 
  Was a representative validation database selected?  

When comparing two runs it is useful to gauge whether one is giving 
statistically better results than another.  For this reason p-values 
are displayed in the comparison (see :ref:`Statistics for comparison of ROCS runs<statistics_panel_2_fig>`). 
A low p-value suggests that the base run is statistically better 
than the run selected in the ``Compare to`` dropdown.  For a description of p-values see 
section :ref:`Statistics Metrics<statistical_metrics>`. If comparing particularly
large data sets it is wise to pay attention the memory foot print -- save and
close any unneeded runs.

.. _statistics_panel_2_fig:

.. figure:: /_images/statistics_panel_2.png
   :scale: 75
   :align: center
   :alt: Statistics for comparison of ROCS runs
   
   **Statistics for comparison of ROCS runs**

While it is more open to individual interpretation, inspection of the overlays 
in the 3D window should not be overlooked as a valuable tool for results 
interpretation.  Can additional knowledge of the receptor be applied that 
validates the ROCS alignments?


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _statistical_metrics:

.. program:: vROCS 

====================
Statistics metrics
====================

To facilitate accurate understanding, interpretation and comparison of virtual 
screening results from multiple (independent) experiments when publishing or 
presenting research it is important to use consistent and industry standard metrics.  
To date no official industry standard has been set.  However, steps 
and recommendations were made in this direction at the "Evaluation of Computational Methods"
symposium at the 234th American Chemical Society in August 2007 and the follow-up Journal 
of Computer Aided Molecular Design issue 22 in March 2008.  Measures that have become 
standard in other fields tend to possess the following short list of characteristics:

1.  Independence to extensive variables
2.  Robustness
3.  Straightforward assessment of error bounds
4.  No free parameters
5.  Easily understood and interpretable

The widespread and habitual use of good reporting practice is something that 
OpenEye is keen to encourage and therefore **vROCS** implements statistics metrics 
discussed in these recommendations ([Jain-2008]_, [Nicholls-2008]_).

The metrics reported in **vROCS** consist of the following and are described below:

1.  ROC (receiver operating characteristic) curve together with its AUC (area under the curve) 95% confidence limits
2.  Early enrichment at 0.5%, 1% and 2% of decoys retrieved 95% confidence limits
3.  When comparing multiple runs p-values are calculated for each enrichment level

ROC Curve
---------

A ROC curve (\ [Hanley-1982]_\ ) in **vROCS** plots the percentage (or fraction) of actives found on
the Y-axis versus the percentage of decoys on the X-axis as the scores decrease.  The top scoring
compounds are plotted closest to the origin.  It gives an indication of how the 
actives and inactives are ranked as a result of the ROCS run.  An ideal ROC 
plot for a perfectly selective query would show all of the actives being identified first 
because they score most highly.  The plot would shoot up the Y axis at X=0.  Then the 
lower scoring decoys would be plotted and the curve would follow the X axis at Y=100 %.  
:ref:`ROC Plot 2<roc_plot_2_fig>` illustrates an ROC plot for an almost perfectly selective query where 
most of the actives rank more highly than most of the decoy molecules.

.. _roc_plot_2_fig:

.. figure:: /_images/roc_plot_2.png
   :width: 75%
   :align: center
   :alt: ROC Curve 2
   
   **ROC Plot 2**
   
   An almost perfectly selective ROC curve with AUC = 0.979 where most 
   of the actives rank more highly than most of the decoy molecules.
   The dashed diagonal line represents random.

AUC
---

The AUC (area under the curve of an ROC plot) is simply the probability that a 
randomly chosen active has a higher score than a randomly chosen inactive.   
A useless query, one with no better chance of identifying an active from an 
inactive, would give an AUC of exactly 0.5, as shown by the dotted line in 
:ref:`ROC Plot 2<roc_plot_2_fig>`.  A perfect query is one which ranks all the actives above all 
the inactives.  In this case the AUC would be 1.0.  In most cases the observed 
AUC will be somewhere between these two extremes, and for a highly selective 
query it will often be in the 0.8-1.0 range.  Sometimes an AUC of < 0.5 is observed. 
This occurs when the query is scoring the decoys more highly that the actives 
i.e. it is selective for the inactives.

.. note::

  AUC has, for a long time, been a standard metric for other fields.  The main 
  complaint against the AUC is that is does not directly answer the questions 
  some want posed, i.e. the performance of a method in the top few percent. 
  It is a global measure and therefore it reflects the performance throughout a 
  ranked list.  Thus, the notion of "early enrichment" may not be well 
  characterized by just AUC, particularly when virtual screening methods yield 
  AUC values short of the 0.8-1.0 range.  For this reason we include early 
  enrichment values in the **ROCS** output for a validation run.
  Early enrichment, while certainly more reflective of the common usage of 
  virtual screening methods, is a property of the experiment conducted, not 
  the methods being studied in that experiment and thus should be used with 
  care.

AUC is quoted in **vROCS** as a mean value 95% confidence limits.  Bootstrapping 
the data produces a set of samples from which the mean and confidence levels are 
obtained.

Enrichment
----------

Consider the example in :ref:`Early Enrichment Comparison<enrichment_roc_fig>` 
below taken from the Nicholls paper (\ [Nicholls-2008]_\ )
which illustrates how AUC provides no information on early enrichment.  
Both the Early (pink) and Late (blue) curves have an AUC of exactly 0.5.  
Clearly both examples are equally likely to score an active higher than 
an inactive (or *vice versa*) overall.  However, the solid (pink) plot also 
shows that some fraction of the actives is scoring significantly higher 
than the inactives, while another fraction of the actives scores worse.  
In a virtual screen it is desirable not to screen the entire database but 
to select only the top scoring fraction of the compounds.  Only the average 
behavior across the whole database, not the early enrichment of actives
in the solid pink plot, is reflected in the AUC.  Thus, it is beneficial 
to report early enrichment in addition to AUC.

.. _enrichment_roc_fig:

.. figure:: /_images/enrichment_roc.png
   :width: 75%
   :align: center
   :alt: Early Enrichment Comparison
   
   **Early Enrichment Comparison**

Use of early enrichment values overcomes this deficit in AUC.  **vROCS** 
reports enrichment percentages at the following values: 0.5%, 1% and 2%.  
The formulation of enrichment that is used in vROCS reports the ratio of 
true positive rates (the Y axis in an ROC plot) to the false positive rates 
of 0.5%, 1% and 2% (found on the X axis in an ROC plot).  Thus "enrichment at 1%" 
is the fraction of actives seen along with the top 1% of known decoys 
(multiplied by 100).  This removes the dependence on the ratio of actives 
and inactives and directly quantifies early enrichment.  It also makes 
standard statistical analysis of error bars much simpler.

Enrichment values are quoted as a mean value 95% confidence limits.  
Bootstrapping the data produces a set of samples from which the mean 
and confidence levels are obtained.  Repeating a run within a 
single **ROCS** session will always result in identical enrichments.  
However, enrichments may vary slightly between **ROCS** sessions because 
a new random number is supplied to the bootstrapping algorithm 
for each **ROCS** session.

p-Value
-------

In statistical hypothesis testing, the p-value is the probability of 
obtaining a result at least as extreme as the one that was actually 
observed, assuming that the null hypothesis is true.  The fact that 
p-values are based on this assumption is crucial to their correct 
interpretation (\ [Wikipedia-pValue]_\ , [Dallal-2001]_\ ).

In the **vROCS** analysis there are two runs being compared, a Base run (A)
and a 'Compare to' run (B).  These two runs use two different queries
or methods (e.g. color force fields) to search the same active and decoy 
databases.  We have a statistic, AUC (or % enrichment), one for each 
distribution (A & B).  We would like to know whether AUC-A is statistically 
better than AUC-B otherwise we cannot say anything about the comparison 
of the methods.  AUC-A and AUC-B alone are not enough to generate 
anything of statistical significance.  To circumvent this we use a 
bootstrapping method which randomly selects a statistical sampling of 
the input molecules to repeatedly generate many AUCs.  

Traditionally, the null hypothesis is that while the perceived results 
may be different (e.g. between AUC or % enrichment), the underlying 
processes are indistinguishable.  However, since null-hypothesis testing 
predicts the likelihood of obtaining a given result if the null hypothesis 
is true, use of this null hypothesis wouldn't give any indication of whether 
method A or method B is better.  To avoid this confusion OpenEye has used a 
modified null hypothesis.  The null hypothesis, as implemented in
vROCS, is that making a change to the query/method results in a 
better result (AUC or % enrichment) for run B than run A.  Therefore
we utilize a one-sided statistical test, not the usual two-sided test, 
based on the prior assumption that method B is superior to method A.
The p-value is the probability that AUC-B > AUC-A and that this difference 
is due to differences between the methods/queries and not due to 
random chance alone.

If the null hypothesis holds true then we observe that AUC-B > AUC-A 
and the p-value tends towards 1.0.  If the null hypothesis is incorrect 
then the p value tends towards 0.0 and the query/method used in run A 
(Base run) is statistically better than that used in run B (the 'Compare to' run).  
If the results for the two runs are indistinguishable and the result could be 
due to random chance then the p-value = 0.5.

The :ref:`plot below<pvalue_fig>` illustrates these three p-value extremes.  
Each curve in the plot represents an example of comparing two ROCS runs.  
For each run bootstrapping produced a statistical sampling of the data 
from which the mean and 95% confidence limit values were calculated 
for AUC and % enrichments.  The distribution of differences in AUC 
(or % enrichment) between the bootstrapped samples for the two runs 
can also be calculated and is plotted below.  

.. _pvalue_fig:

.. figure:: /_images/pvalues.png
   :width: 75%
   :align: center
   :alt: Plot to illustrate calculation of p-values
   
   **Plot to illustrate calculation of p-values**
   

In the case of p-value = 0.5 half of the distribution is positive and 
half of the distribution is negative.  The p-value is calculated from 
the integral of the area under the curve from 0 to infinity (the part 
of the curve that falls within the shaded area).  In the case of 
p-value = 1.0 the difference between run B and run A is always 
positive and the entire curve is above 0 on the X-axis.  The entire 
curve falls within the shaded area and so the integral is 1.0.  In the case 
where the p-value = 0.0 the difference between run B and run A is always 
negative.  None of the curve falls within the shaded area 
and so the integral is 0.0

When considering the results from two **ROCS** runs the p-values should 
be interpreted as follows.  If the p-value tends towards 0.0 then the 
results for the Base run are better than the 'Compare to...' run (run A > run B). 
If the p-value = 0.5 then the results for the two runs are statistically 
indistinguishable.  If the p-value tends towards 1.0 then the Base run is 
not better than the 'Compare to...' run or, in other words, the 'Compare to...' 
run is giving results better than the Base run (run B > run A).

Consider the example below for three different trypsin queries run 
against the same active and decoy databases.  From the 
:ref:`ROC plot for the three trypsin queries<roc_plot_3_fig>`,
we observe that run Trypsin1 has an AUC intermediate between those of Trypsin2 and Trypsin3.  

.. _roc_plot_3_fig:

.. figure:: /_images/roc_plot_3.png
   :width: 75%
   :align: center
   :alt: ROC plot for three trypsin queries 
   
   **ROC plot for three trypsin queries**
   
Looking at :ref:`Table 1<trypsin_table_1_fig>`, where Trypsin1 is the Base run (run A) and is compared to 
Trypsin2 and Trypsin3 (run B), we see that there is a p-value of 0.979 for Trypsin2.  
The Trypsin2 AUC of 0.940 mean value with 95% confidence limits of 0.888 and 0.979 
is has very little overlap with Trypsin1 at 0.868 with 95% confidence limits of 
0.805 and 0.915.  The p-value = 0.979 suggests that Trypsin2 is producing superior 
results and these are due to differences between the queries, not to chance alone.  
The null hypothesis (run B > run A) holds true in this case.  Note that in 
:ref:`Table 2<trypsin_table_2_fig>`, where Trypsin2 is now the Base run, the p-value is reversed.  
In this case p-value = 0.021 suggests that Trypsin1 is producing inferior 
results and these are due to differences between the queries, not to chance 
alone.  The null hypothesis (that the 'Compare to' run produces superior 
results to the Base run) can be rejected.  Similarly, when comparing Trypsin3 
to Trypsin1 in :ref:`Table 3<trypsin_table_3_fig>`, the p-value of 0.006 suggests that Trypsin3 is 
producing inferior results and these are due to differences between the
queries, not to chance alone.  This is supported by our observations in 
the ROC plot (see :ref:`ROC plot for three trypsin queries<roc_plot_3_fig>`) 
where Trypsin3 clearly has the lowest AUC.

.. _trypsin_table_1_fig:

.. figure:: /_images/trypsin_table_1.png
   :width: 90%
   :align: center
   :alt: Trypsin1 (Base) compared to Trypsin2 and Trypsin3
   
   **Table 1: Trypsin1 (Base) compared to Trypsin2 and Trypsin3**

.. _trypsin_table_2_fig:

.. figure:: /_images/trypsin_table_2.png
   :width: 90%
   :align: center
   :alt: Trypsin2 (Base) compared to Trypsin1 and Trypsin3
   
   **Table 2: Trypsin2 (Base) compared to Trypsin1 and Trypsin3**
   
.. _trypsin_table_3_fig:

.. figure:: /_images/trypsin_table_3.png
   :width: 90%
   :align: center
   :alt: Trypsin3 (Base) compared to Trypsin 1 and Trypsin 2
   
   **Table 3: Trypsin3 (Base) compared to Trypsin1 and Trypsin2**

Now consider the p-values for the 0.5%, 1% and 2% enrichments.  Trypsin1 
and Trypsin3 have similar enrichment levels.  For example, at 0.5% enrichment 
Trypsin1 is 35.987 with 95% confidence levels of 11.321 and 62.857 while 
Trypsin3 is 28.625 with 95% confidence levels of 9.524 and 51.724.  Each 
has an average enrichment that is well within the 95% confidence limits 
of the other.  This is supported by p-values tending towards 0.5 i.e. 
0.340 when comparing Trypsin3 to Trypsin1 
(in :ref:`Table 1<trypsin_table_1_fig>`) 
and 0.660 when comparing Trypsin1 to Trypsin3 
(in :ref:`Table 2<trypsin_table_3_fig>`) 
(the inverse around 0.5).
From this we can conclude that the query Trypsin1 gives a slightly 
better 0.5% enrichment than does Trypsin3 (p-value 0.660, from
:ref:`Table 1<trypsin_table_1_fig>`)
but that the differences may not be entirely statistically significant.

In the case of Trypsin2 the enrichments at all levels are much higher 
than Trypsin1 or Trypsin3 (e.g. 126.127 with 95% confidence limits of 
96.000 and 152.381 for the 0.5% enrichment) with 95% confidence limits 
that do not overlap at all with those for Trypsin1 or Trypsin3.  
This results in p-values of 1.000 when either Trypsin1 or Typsin3 
is the Base run (Tables 1 or 3) (i.e. Trypsin2 is the superior 
query and the null hypothesis holds true) or 0.000 when Trypsin2 is 
the Base run (in Table 2) (i.e. Trypsin1 and Trypsin3 are clearly inferior to 
Trypsin2 and the null hypothesis is rejected).  These conclusions are also 
clearly visible in the :ref:`ROC plot<roc_plot_3_fig>`.

Repeating a run within a single ROCS session will always result in 
identical p-values for enrichments.  However, since enrichments may 
vary slightly between ROCS sessions, when a new random number is supplied 
to the bootstrapping algorithm, there may be small differences in p-value for 
the same combination of runs if repeated in different ROCS sessions.  

A typical cutoff for statistical significance of p-values is applied at the 
5% (or 0.05) level.  Thus, a p-value of 0.05 corresponds to a 5% chance of obtaining a 
result that extreme, given that the null hypothesis holds.  A p-value of less than 0.05
(or greater than 0.95) would give good confidence that the selectivity you
observe in your ROC plot is derived 
exclusively from differences between the two queries or methods and not a result of 
chance alone.


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _vrocs_saving:

.. program:: vROCS 

=================
Saving ROCS data
=================

The **vROCS** interface provides multiple tools for saving data.  Data that can be saved includes:

1. The query file
2. The entire set of results obtained from a simple or validation **ROCS** run
3. Data and statistics from a validation run in ``.csv`` delimited file format
4. Screenshots of the 3D window illustrating the query and/or aligned hit molecules
5. Screenshots of the ROC or Score Histogram plots

**Query file:**  A query that is built or modified in **vROCS** can be saved for future use.  
The default file type for saving a query is a **ROCS** Saved Query file with extension ``.sq`` or 
``.sq.gz``.  This file type is not compatible with older versions of **ROCS**.
Additionally, it contains information about the color force field used 
and therefore cannot be used with an alternative color force field.

There are multiple ways to save a query file from the vROCS interface.  

* Firstly, using the File menu click on ``File`` > ``Save Query...`` or use the ``Ctrl+S``
  shortcut keys.  This is a 'Save As...' action and will always prompt for a filename 
  and a directory in which to save it.  This action is performed on the query 
  currently selected in the Query list of the Run Set-up Inputs dialog.
* There is also a right-click option.  When viewing the results panel 
  right-clicking on the run name tab opens a :ref:`right-click menu<save_popup_fig>`
  in which the second option is Save Query from 'Run Name'.  This is a 
  'Save As...' action and operates specifically on the query associated with that run.  
  Therefore, it allows the user to save an older version of a query that 
  may have been subsequently modified by going back to activate the Results tab for the earlier run.

.. _save_popup_fig:

.. figure:: /_images/save_popup.png
   :height: 678
   :width: 1126
   :align: center
   :alt: Right-click menu on results spreadsheet Run Name tab
   
   **Right-click menu on results spreadsheet Run Name tab**

============================== ==========================================================
Option                         Description
============================== ==========================================================
Save results from 'Run name'   Save the results for the active results set in a 3D 
                               structure and data file.  The default file type is OE 
                               Binary (\*.oeb, \*.oeb.gz).
Save query from 'Run name'     Save the query for the active results set in a 3D 
                               shape query file (\*.sq, \*.sq.gz).  The file contains 
                               information about both shape and color, as well as the 
                               color force field used to apply the color atoms.  
                               This is a Save As... action and will always prompt for 
                               a filename.
Rename 'Run name'              Rename the Results Name tab
Open 'Run name' in VIDA        Exports the structures and data for the active Run Name 
                               tab into VIDA.  If VIDA is not already open a new 
                               session is opened.  If VIDA is already in use the dataset 
                               is appended to the list of molecules already in the 
                               VIDA List Window.  All the data is available to view 
                               in the VIDA spreadsheet.
============================== ==========================================================

**Results:**  From the results spreadsheet for either the simple or validation run the 
user can right-click on the run name tab to open a :ref:`right-click menu<save_popup_fig>`
in which the first option is Save Results from 'Run Name'.  This is a Save As... 
action and operates specifically on the data for the run associated with that 
spreadsheet.  Having multiple spreadsheets available allows the user to save 
results from either the current run or an older run by selecting the appropriate 
run name tab.  All the data points for the run are saved, not just the top 20 
results visible in the spreadsheet.  The sort order from the spreadsheet is 
not retained.  The compounds in the saved file are sorted by the Rank By 
score selected during runs set-up.  The results are saved in a variety of 
possible molecule file types suitable for opening in the **VIDA** spreadsheet 
or other third party applications.  The default is the OpenEye OE Binary 
file type with ``.oeb`` or ``.oeb.gz`` file extension.  Since only the top 20 results 
are visible in the **vROCS** spreadsheet users are encouraged to save the results 
and use the **VIDA** spreadsheet, not the **vROCS** interface as the primary tool for 
analyzing results.

**Statistics data:**  From the statistics panel in a validation run three 
different types of data - score data, plot data and spreadsheet - can be 
exported and saved in a comma delimited format (``.csv``), suitable for loading 
in text-based applications and other statistics packages.  
These options are selected from the ``Choose stats to save...`` drop down menu in the 
:ref:`statistics panel<stats_panel_menu_fig>`.

.. _stats_panel_menu_fig:

.. figure:: /_images/stats_panel_menu.png
   :scale: 75
   :align: center
   :alt: Choose stats to save drop-down in the statistics panel
   
   **Choose stats to save drop-down in the statistics panel**

|
|

======================== ====================================================
Option                   Description
======================== ====================================================
Score Data               Save a file containing the raw scores for the top 
                         scoring aligned conformer of each compound searched 
                         using each of the scoring functions of a validation 
                         run displayed.  Data for **all** database compounds 
                         are exported.
Plot Data                Export the data points from either the ROC Curve 
                         or the Score Histogram.  These are (x,y) datapoints 
                         from the curve or histogram created in **vROCS**, not 
                         raw data.  Note that this export is context 
                         sensitive upon the plot that is currently 
                         displayed (i.e. when the ROC curve is displayed the 
                         plot data output will have (x,y) values to recreate 
                         the ROC curve and when the Score Histogram is 
                         displayed the data output will have (x,y) data 
                         for both actives and decoys to recreate a
                         histogram).
Spreadsheet              Save the data displayed in the **vROCS** statistics 
                         panel spreadsheet (AUC and enrichment values with 
                         error bars).  If a second run has been selected 
                         to compare against the currently active run then 
                         data for both runs and the associated p-values are 
                         exported in a single file.       
======================== ====================================================

**ROC plot/Score Histogram:**  Exporting the data to recreate the 
ROC plot (or Score Histogram) to a ``.csv`` delimited file (described above) 
provides the opportunity to rebuild the plots in a third party graphing application 
and combine plots from different **ROCS** sessions.  
However, this can prove somewhat cumbersome and it is frequently 
useful to take a 
screenshot of the current plot (either of a single run or a comparison of multiple runs) 
for inclusion in a report, presentation or publication.  To do this,
right click on the plot and choose "Save Image...".

.. _save_plot_fig:

.. figure:: /_images/save_plot.png
   :scale: 75
   :align: center
   :alt: Save an image file of the ROC plot or score histogram
   
   **Save an image file of the ROC plot or score histogram**
   
**3D window screenshot:**  A screenshot can be useful for insertion into 
presentations and publications.  A :ref:`camera<screenshot_full_fig>` icon at the top of the 3D
window allows for taking a single click screenshot
of the view in the 3D window.  It is a WYSIWYG 
(what you see is what you get) screenshot of the 3D window with the 
exception that the surrounding buttons are not included.  
See the :ref:`figure<screenshot_full_fig>` below.

.. _screenshot_full_fig:

.. figure:: /_images/screenshot_full.png
   :scale: 100
   :align: center
   :alt: 3D Window screenshot option
   
   **3D Window screenshot option**
   

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _shape_query_sources:

.. program:: vROCS 

=========================
ROCS shape query sources 
=========================

**ROCS** is most commonly used to compare alignments of molecular shapes.  However, 
a range of other shapes, e.g. molecular grids, form equally valid and
useful alignment target queries, with the following provisos.

Grids are built without color atoms.  The absence of color atoms in a query 
usually causes **ROCS** performance to be lower.  For ligand shape queries 
adding color atoms has been shown to enhance **ROCS** performance with twice 
as much signal over random when color atoms are used, compared to shape 
alone.   Without color the **ROCS** TanimotoCombo scores will also 
generally be lower (TanimotoCombo 0-1 instead of 0-2).  Therefore, one should 
either add color atoms manually to a grid-based query 
(see section :ref:`Editing ROCS queries in vROCS<editting_queryies>`) or compare 
with the ShapeTanimoto score obtained from a ligand-shape query.  

.. note::

  Using DUD 1.0 with **ROCS** shape only the average AUC across the 38 cases is approximately 
  0.6. With shape + color the average AUC is around 0.73.  Therefore, the delta over 
  random for shape is 0.1 and for shape + color is 0.23.  Hence, by this rather odd 
  way of looking at it there is twice as much signal. 
  - *P. Hawkins, OpenEye*

It is possible to add color points to grid shapes using the editing tools 
available in **vROCS**, described in the tutorial 
:ref:`Building and editing a query manually<tutorial2>` and this can usefully guide 
the alignments.  However, ligand shape with color generally provides superior 
results to using a grid-based query.  Grids can be useful in cases where no 
suitable ligand query exists.

There are several potential sources of grids:

* AFITT can produce a grid of electron density from crystallographic data.  
  It is also possible to back-compute a grid of density for a crystallographic or 
  docked ligand.  This allows heavier atoms to contribute more to the grid than 
  light ones, whereas shape grids are uniform.
* Spicoli will make grids from surfaces.
* **OEDocking** also produces a shape grid.
* Using the OEGrid toolkit you can read in any grid format and, 
  using an ASCII interchange format, write it to an OE format 
  that could be used by **vROCS**.  This capability allows access to 
  grids produced by third party applications.  For example, DOCK (\ [DOCK]_\ ) uses 
  scoring grids, GRID (\ [GRID]_\ ) makes grids and so on.  All of these could be 
  used to makes queries for **vROCS**, but their application and usefulness
  has not been thoroughly validated.

Recent research has been carried out at OpenEye to validate some tools currently 
under development (\ [Nicholls-2010]_\ ).  These produce shapes 
that describe a protein binding pocket (using the same technology as Spicoli) 
for use as **ROCS** queries.  Initial results 
show that shapes from sources other than pure ligands can be successfully used 
as useful **ROCS** queries and that adding color atoms is often useful to increase 
selectivity (and is never detrimental, to date), just as for ligand-based 
shape and color queries.


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _editting_queryies:

.. program:: vROCS 

=====================================
Editing ROCS queries in vROCS
=====================================

In earlier versions of **ROCS** it was difficult to edit a query using the various 
command line utilities.  The input to **ROCS** was generally required to be either a 
whole molecule query or a grid or shape query, although it was possible to load 
one or more molecules into a 3D builder and then modify or merge them into a 
super molecule.   Having the **vROCS** graphical editor for **ROCS** provides the ability 
to move from a simple molecule with automatic color atom assignment or a grid 
(with no color atoms at all) to a position where the user can decide how the 
query is built.  The **vROCS** graphical editor will facilitate this process by:

1. Reducing the time required.
2. Reducing the risk of errors.
3. Increasing the flexibility of the editing process by allowing a
   greater range of editing tasks to be accomplished.

This will have a knock-on effect that more complex and/or selective queries 
can be employed in **ROCS** and, in some cases, it is possible that higher quality 
results could be obtained.  Additionally, it will facilitate the use of queries 
that are not directly molecule shape-based e.g. multiple fragments or grid-based queries.  

There is a danger associated with the ability to edit the query and that is 
over-editing i.e. editing a query until it does not work.  For this reason 
the validation run and its associated statistical analysis tools 
were included in **vROCS** (see section :ref:`Statistics metrics<statistical_metrics>`).  
By providing the 
validation the user has the tools necessary to decide whether a complex new 
query is really better than simply using e.g. the x-ray ligand.  This caveat 
should constantly be uppermost in the user's mind.  

There are two methods for editing queries in **vROCS**.  An automated wizard 
guides the user through one of a few predesigned paths for building a new query.  
Manual query building and editing is also available. 
Both functions are available from the Welcome interface.

Query Building Wizard
---------------------
The :ref:`query building wizard<wizard_fig>` is designed to walk the user through building a query 
through one of the paths below:

1.  SMILES
2.  Ligand Model Builder

These are typically paths for which manual query building is less straightforward.

.. _wizard_fig:

.. figure:: /_images/wizard.png
   :scale: 75
   :align: center
   :alt: Query building wizard interface 
   
   **Query building wizard interface**

There are two ways to access the Wizard.  Either select the Create a Query 
With a Wizard button on the **vROCS** Welcome page or select File > New Query... from 
the menu at any time during a session.

SMILES
^^^^^^
The SMILES option produces up to 5 queries from an input SMILES string, 
calculating a reasonable 3D structure and conformations.  

In the Create Query tab of the Query Wizard select the radio button 
SMILES and then click Next (as seen :ref:`above<wizard_fig>`).

The Select SMILES tab becomes active. This gives the option to type in a 
SMILES string or molecule name (systematic IUPAC or molecule name, i.e. aspirin).  
The molecule structure will be incrementally displayed as the SMILES
string is entered.

.. _enter_smiles_fig:

.. figure:: /_images/enter_smiles.png
   :scale: 75
   :align: center
   :alt: Select SMILES page
   
   **Select SMILES page**

Clicking on the green "+" icon in the SMILES entry field pops up a :ref:`Sketcher<picto_fig>` 
in which the molecule can be sketched or the SMILES string or molecule name can be entered in the 
input field.  When sketching is complete, clicking OK will close the Sketcher and update the 
structure displayed in the Select SMILES tab.

.. _picto_fig:

.. figure:: /_images/picto.png
   :scale: 75
   :align: center
   :alt: Picto sketcher
   
   **Picto sketcher**

Alternatively, a file of one or more molecules can be loaded and a SMILES 
string is displayed for each molecule in the file.  Scrolling through the 
list of molecules will change the structure displayed.  The highlighted 
structure in the list is the one that will be selected for the next step.

Because the query will be run through **OMEGA** to generate conformers, and **OMEGA**
requires stereochemistry to be defined, chiral molecules with undefined stereo 
centers will require an additional step to specify the proper configuration
at each stereo center.  Atoms and bonds with undefined stereochemistry will
appear highlighted in red (see :ref:`figure below<undef_stereo_fig>`).  
Clicking on the highlighted atoms will cycle through the possible 
configurations. 

.. _undef_stereo_fig:

.. figure:: /_images/undefined_stereo_1.png
   :scale: 75
   :align: center
   :alt: Molecule with Undefined Stereochemistry
   
   **Molecule with Undefined Stereochemistry**

.. _def_stereo_fig:

.. figure:: /_images/undefined_stereo_2.png
   :scale: 75
   :align: center
   :alt: Molecule with Stereochemistry Defined
   
   **Molecule with Stereochemistry Defined**

Clicking Next activates the :ref:`Pick Queries page<choose_queries_fig>`.  For the 
previously highlighted structure five (5) **OMEGA** lowest energy conformers 
are generated and listed.  Conformer 1 is the lowest energy conformer.  
Scrolling through the list of conformer names using the up/down arrow keys 
or clicking on a specific conformer displays that structure in the 3D 
window above where it can be rotated or zoomed using the mouse.  
Multiple conformers can be chosen for import as **ROCS** queries into 
the main **vROCS** interface.  The desired conformers are marked with 
a red check mark by double-clicking on their entries in the list. 

.. _choose_queries_fig:

.. figure:: /_images/choose_queries.png
   :scale: 75
   :align: center
   :alt: Pick queries page
   
   **Pick queries page**

Click Finish to close the Wizard and import the selected conformers into 
**vROCS**.  They will be listed in the Query list for simple or validation runs 
and the lowest energy conformer will be displayed in the 3D window.

Ligand Model Builder
^^^^^^^^^^^^^^^^^^^^

If there are several known active ligands for a given project it can be desirable 
in **ROCS** to use a hypothesis query which is an alignment of more than one of the 
active ligands.  This avoids losing potentially important information from one 
ligand that may not be present in others.  The ligand model builder takes a set 
of pre-aligned ligands in the same Cartesian coordinate frame and carries out a 
rigid alignment in the same frame of reference.  It produces hypothesis models 
for 1,2...n molecules (where n is selected by the user as the maximum number of 
molecules per model).  The top scoring model(s), based on TanimotoCombo score, 
are returned.  These are the model(s) that best represent the set of ligands as a 
whole.  Since this is a rigid alignment no **OMEGA** conformers are generated and it 
is therefore important to use a 'reasonable' structure for each compound that 
represents a putative binding mode e.g. a set of docked ligands or a set of 
x-ray crystal structures.

Consider the following example.  A set of 19 trypsin protein crystal structures 
are sequence aligned and the ligands extracted to give a set of 19 Cartesian aligned ligands.  
The user is interested in building 2 models, each containing up to 3 molecules.  
The ligand model builder builds hypothesis alignment models containing 1, 2 and 3 
of these 19 ligands.  It scores all the models against the set of 19 compounds and 
returns the top scoring 2 models.  These may contain 1, 2 or 3 of the ligands and a 
3-ligand model does not necessarily contain any of the ligands used in a 1- or 2-ligand model.

From the :ref:`Create Query dialog<wizard_fig>` of the Wizard select the radio-button option for 
Ligand Model Builder and click Next.  This will activate the 
:ref:`Load Aligned Ligands page<load_aligned_fig>`.

.. _load_aligned_fig:

.. figure:: /_images/load_aligned.png
   :scale: 75
   :align: center
   :alt: Load Aligned Ligands page
   
   **Load Aligned Ligands page**

The user is required to browse and select a file containing the aligned ligands 
(single conformer only).  The input file type can be any format with 3D coordinates but 
must contain molecules.  Other potential ROCS inputs (e.g. shape grids) cannot 
be supported in this workflow.  Both 3D and 2D preview windows allow scrolling 
through the individual members of the file.  The 3D window is interactive for 
zooming or rotating with the mouse.  Click the Next button to proceed to the 
Adjust Parameters page.

All the required parameters are set by default so it is optional to make any 
additions or changes to fields in the :ref:`Adjust Parameters page<adjust_parameters_fig>`.  

.. _adjust_parameters_fig:

.. figure:: /_images/adjust_parameters.png
   :scale: 75
   :align: center
   :alt: Adjust Parameters page
   
   **Adjust Parameters page**

|
|

========================= ============================================================
Option                    Description
========================= ============================================================
Max. molecules per model  Models containing 1,2,...n molecules will be considered 
                          for an input value of n.
Models to keep            The number of best models to output, based on TanimotoCombo 
                          score.
Output title prefix       Optional naming prefix for the output models.
Merge color atoms         Optional merging of close color atoms of the same type in 
                          multi-molecule models.
========================= ============================================================

The following options are available:
  
**Max. molecules per model**: This is the value n described above.  For n=4 models containing 
1, 2, 3 & 4 molecules will be considered.  The input value for n cannot exceed the 
number of ligands in the input file.  As n is increased the number of models considered 
will increase at a rate of the sum of the binomial coefficients.  
It is the sum of the binomial coefficient elements of the nth row of Pascal's
triangle from 1 to n.  (https://en.wikipedia.org/wiki/Pascal%27s_triangle.)

      :math:`k = \sum_{i=1}^n\frac{h!}{(h-n)!n!}`
      
      k = total number of models considered; 
      
      h = no. of molecules in the pool; 
      
      n = max. molecules per model

Consider the trypsin example above where k=19.  The binomial coefficients (for 1 to 19) are: 

      :math:`19+171+969+3,876+11,628+27,132+50,388+75,582+92,378+`
        :math:`92,378+75,582+50,388+27,132+11,628+3,876+969+171+19+1`

If only models containing 1 molecule are considered then 19 models will need to be evaluated.  
If models containing up to 3 molecules are considered then 1159 models will be built and 
evaluated:

      :math:`19+171+969=1159`

This represents 19 one-molecule models, 171 two-molecule models and 969 three-molecule models.  
However, if models containing all 19 molecules were to be considered then:

      :math:`k = 2^{19} -1=524,287`
      
      k = total number of models considered

Thus, 524,287 models would be built and evaluated.  Clearly this can become a cpu intensive
and time consuming process so it is recommended to keep n low (<5) when the pool of 
molecules is large.  This also avoids building overly complex models.

**Models to keep**: This is the number of top ranking models to output.  By default this 
is set to 1 and therefore a single model will be produced.  The output model is 
the one with the highest mean TanimotoCombo score across all the ligands.  
If this input value is set higher then more 
models will be output for visual evaluation and use as possible hypotheses.  
Increasing the number of models to keep has no effect on the run time; the 
same number of models are created and evaluated.  It only changes the number 
of models retained in the output set.

**Output title prefix**:  This optional field names the models produced.  
For a prefix 'model' the resulting models will be named 'model 1', 'model 2', 
etc.  If no prefix is provided then the model name will be formulated by the 
names of the ligands which comprise the model.  For example, '1GJ6_1QBO' is a 
model made from two ligands named '1GJ6' and '1QBO' in the input file.

**Merge color atoms**:  This is an optional field.  If two color atoms are overlaid 
then they will automatically be merged.  However, color atoms are often close but 
not perfectly overlaid, for example, the two donor atoms highlighted 
:ref:`below<merge_color_fig>`.  
Checking the Merge color atoms box will attempt to produce a single color atom which 
describes both.  This simplifies the resulting model.  Color atoms can also be manually 
deleted or merged later, if desired, as described in :ref:`Manual query building<manual_building>`.

.. _merge_color_fig:

.. figure:: /_images/merge_color.png
   :scale: 75
   :align: center
   :alt: A two-ligand model produced by the model query builder
   
   **A two-ligand model produced by the model query builder**

When the desired parameters are set in the Adjust Parameters dialog click Next to 
begin the calculation.  A progress tab will provide information on the progress 
of the model building.  Models are built using the color force field currently 
selected in the user preferences (``Edit > Preferences > vROCS``, 
see :ref:`vROCS Preferences<vrocs_prefs>`).  

When the calculation and evaluation is complete the models best fitting the 
parameters, based upon TanimotoCombo score, will be displayed in the :ref:`Pick 
Queries tab<merge_color_fig>`.  A 3D preview window shows the model which can be rotated and 
zoomed.  The model currently on display is highlighted in the list below the 3D display.  
The list gives each model's name and a description made up of the names of 
the ligand(s) taken from the input ligand pool to build the model.  

Clicking the Back button from the Pick Queries tab and changing any of the 
parameters will prompt with a warning that the previous results will be lost.
To avoid losing potential queries it is advisable to first import any models of interest to the 
main **vROCS** interface before re-running the Wizard.

To import one or more models as queries to the main **vROCS** interface click 
to add a check mark in the column next to the model description.  At least 
one check mark is required to activate the Finish button.  The checked models 
will be imported into the Query list for a simple or validation **ROCS** run and 
each can be highlighted and viewed in the 3D window.

Queries built using the Ligand Model Builder can include many color features, 
some derived from each of the ligands used to build the query.  This will have 
a couple of ramifications.

* **ROCS** search speeds are typically slower with more color atoms
* Unmatched color atoms give rise to scoring penalties and so scores using
  color might be lower than one might expect (e.g. TanimotoCombo score <1)
  compared to using a single ligand as a query.  However, AUC and enrichment 
  values will not be affected.

For these reasons it can frequently be useful to further edit the queries 
produced by the Ligand Model Builder and simplify them by removing some of 
the color features.  Example candidates might be those that were not quite 
close enough to be merged by the Merge color atoms algorithm. 

Manual Query Building
---------------------

.. _manual_building:

Manual query editing and building operations can be carried out on a new 
query (e.g. an imported ligand), a saved query file or the output from 
the Ligand Model Builder.  To carry out the editing operations **vROCS** is 
required to be in the Edit Query mode.  

**Edit Query Mode:**  The Edit Query mode can be accessed in one of the 
following ways.  Either click on the ``Create or Edit a Query Manually`` 
button in the Welcome screen or, at any time during an **vROCS** session, 
click on the ``Edit Query`` icon at the top of the 3D window.  While in the 
editing mode the ``Edit Query`` button will be replaced by the ``Done Editing`` 
button and an :ref:`editing toolbar<edit_query_fig>` will 
appear at the left of the 3D Window to select atoms, add color atoms, 
delete atoms or color atoms and merge color atoms.  

.. _edit_query_fig:

.. figure:: /_images/edit_query.png
   :scale: 75
   :align: center
   :alt: Editing a query
   
   **Editing a query**

|
|

=============================================================== ===========================================================================
Icon                                                            Description
=============================================================== ===========================================================================
.. image:: rocs/images/vrocs/table4/icon_edit_query.png           Edit Query icon.  Displayed in the :ref:`3D Visualization Window<results_viz>`.
                                                                Open the Edit Query panel and add the query editing icons.  This icon 
                                                                is replaced by a Done Editing icon while in editing mode.
.. image:: rocs/images/vrocs/table13/icon_done_editing.png        Done Editing icon.  This returns the user to the 3D
                                                                visualization window and hides the editing icons once
                                                                query editing is complete.  This icon is only visible in
                                                                editing mode.
.. image:: rocs/images/vrocs/table13/icon_select.png              Selection mode.  Click on a shape or color atom to select it.
                                                                Selected atoms will be highlighted in orange.  CTRL click
                                                                to select multiple shape atoms or color atoms.  Only all
                                                                color atoms or all shape atoms can be selected using CTRL
                                                                click.  Right-click and drag a box to select a portion
                                                                of the query including both shape and color atoms.
.. image:: rocs/images/vrocs/table13/icon_add_color_atom.png      Add Color Atom mode.  Click and select the desired color atom
                                                                type from the pop-out menu.
                                                                Choices for built-in color force fields are: 1) Acceptor (A), 2) 
                                                                Anion (An), 3) Cation (C), 4) Donor (D), 5) Hydrophobe (H) and 
                                                                6) Rings (R).  
                                                                The letter on the icon indicates the currently active atom type.  For
                                                                other force field types, the list will be populated accordingly.
.. image:: rocs/images/vrocs/table13/icon_eraser.png              Delete Atoms mode.  Click on shape or color atoms to delete
                                                                them from the query.  Right-click and drag a box to delete all shape 
                                                                and color atoms currently visible within the box.
.. image:: rocs/images/vrocs/table13/icon_delete.png              Delete Selected Atoms action.  Delete all currently selected atoms
                                                                and/or color atoms.  If there are no selected atoms, this button is disabled.
.. image:: rocs/images/vrocs/table13/icon_merge_color_atoms.png   Merge Color Atoms action.  Merge multiple molecular fragments into a
                                                                single query and merges color atoms of the same type 
                                                                to a single average representation.  If color atoms are selected, those will
                                                                be merged.  If no color atoms are selected, all color atoms of the same
                                                                type within 0.75 Angstroms of each other will be merged.
=============================================================== ===========================================================================

An :ref:`Edit Query panel<edit_panel_fig>` will display on the left hand side of the screen. 
This panel contains two areas.  At the bottom is a Shape Inventory area.  This lists 
all the open shape files that could be used in the query.  These can be opened ligand 
or grid files, hits from an earlier **ROCS** run or other active queries.  Items can be 
displayed in the 3D window by clicking their name.  Molecules will be displayed as 
atom-colored sticks.  At this stage they have no associated **ROCS** shape or color 
elements.  Multiple items can be displayed together for comparison by clicking on
the green visibility icon to the right of the item name on or off.   Hovering over 
an item's name will display a 2D depiction of the structure, if it is a molecule file. 

.. _edit_panel_fig:

.. figure:: /_images/edit_panel.png
   :scale: 50
   :align: center
   :alt: Edit Query panel
   
   **Edit Query panel**

At the top of the Edit Query panel is the Current Query area where components 
(e.g. atom components, color components, shape components) of the current working 
query are listed and can be selected or deselected.  A selected item has a red 
check mark next to its name and will be used in the current query.  Queries 
derived from molecules are displayed in the 3D Window as green colored sticks with atom-type 
colored heteroatoms.  Color atoms are shown as colored spheres with labels.  
Grid shapes are shown as a gray, transparent surface 
(see :ref:`Editing a query<edit_query_fig>`).  

Any item can be moved from the Shape Inventory to the Current Query by dragging 
it from the bottom panel to the top panel or by right-clicking its name and 
selecting Add to Query.  The other right-click options available in the Shape 
Inventory are to Delete the current item from the list or to Rename the item.  
A query can be made up of multiple query elements.  To remove any element from 
the working query click on the red check mark to undisplay it or right-click 
on its name and select the option to Disable in Query.  Other right-click 
options for the Current Query elements are Delete and Rename.

At any point the current working query can be saved by clicking on the 
``Accept`` button below the Shape Inventory or by ``File > Save Query...`` These are 
both save as... actions and will always prompt for a filename and directory 
for the file to be saved.  Note that the color force field parameters used 
to apply color atoms to a query are saved with the query and cannot be 
changed on re-opening a saved query.  The color force field is set in the 
``Edit > Preferences`` dialog (see :ref:`vROCS Preferences<vrocs_prefs>`) and can only be changed before any 
molecules or shapes are loaded into vROCS.  When editing is complete either 
click on the ``Done Editing`` icon at the top of the 3D Window or the ``Use in 
ROCS`` button below the Shape Inventory.  Both will return to the display from 
which the editing mode was accessed (e.g. Welcome screen or Run set-up dialog).

The manual query editing tasks available via the vROCS interface are:

1. Merge two or more molecules/grids. 
2. Delete color atom(s).
3. Delete shape atom(s).
4. Add color atom(s) from one or more selected atom(s).
5. Alter shape atom or color atom weighting.
6. Merge color atom(s).
7. Load grid.
8. Add color atom(s) to grids.

Each is described in more detail below.

**Merge two or more molecules/grids:**  A query can be made up of molecules 
and/or grids from multiple sources/files.  For example, two molecular 
fragments that describe ligand-protein interactions at different 
positions in the binding pocket, as shown below.

.. _two_fragments_fig:

.. figure:: /_images/two_fragments.png
   :scale: 75
   :align: center
   :alt: Query built from two fragments
   
   **Query built from two fragments**

Open the files into the Shape Inventory using ``File > Open`` in the Edit Query 
mode and then drag them to the Current Query area of the Edit Query Panel.  
Each of these molecules/grids will be added to the current working query. 
They should have a similar 3D coordinate frame so all portions of the query 
can be viewed in the 3D window at the same time.  Saving the current query 
will save all constituent parts of the query together unless the red check 
mark indicating ``Use in Current Query`` is checked off.  The combined query 
can be further edited using the options below.

**Delete color atom(s):**  A ligand-based query automatically has color atoms 
assigned by **vROCS**.  They are assigned using the currently selected color 
force field, as applied in the checkcff (command line) utility.  The default 
color force field for **vROCS** is ImplicitMillsDean (see section :ref:`Color Force 
Field<colorforcefield>`) but this can be changed using the ``Edit > Preferences`` 
dialog (see :ref:`vROCS Preferences<vrocs_prefs>` for more details).
Color atoms can also be manually placed on atoms or grids.  It can be desirable 
to delete a color atom.  For example, a hydroxyl oxygen atom would be assigned 
as both an H-bond donor and an H-bond acceptor by **vROCS** as highlighted
in :ref:`Deleting a color atom<delete_color_atom_fig>`.  However, 
knowledge of your active compounds and/or receptor cavity may lead you to 
believe that an acceptor is required at that position.  The donor color atom 
can be deleted.

.. _delete_color_atom_fig:

.. figure:: /_images/delete_color_atom.png
   :scale: 100
   :align: center
   :alt: Deleting a color atom
   
   **Deleting a color atom**

Click on the eraser icon highlighted in 
:ref:`Deleting a color atom<delete_color_atom_fig>`, above, to activate 
the ``Delete Atoms`` mode.  A gray background to the button shows it 
has been selected.  A single left click on the color atom (or atoms) 
that you wish to delete will remove that feature from the query.  
In the case of the combined donor/acceptor example clicking on the 
blue quadrants of the color atom will remove the donor feature and 
clicking on the red quadrants will remove the acceptor.  
Multiple color atoms can be deleted using sequential clicks.

At any point the ``Edit > Undo`` menu item can be used to replace a 
color atom (or shape atom) that is accidentally deleted.  Since 
the Delete Atoms mode operates on both color and shape atoms 
it is often useful to hide (undisplay) the shape atoms and 
surface contour using the buttons at the bottom of the Edit Query 3D window.

To delete multiple adjacent color atoms right click and drag to 
draw a rectangular box around the features to be deleted with the 
Delete Atoms button highlighted.  In this case it is desirable to 
display only the color atoms (hide the shape atoms and contour).  
This prevents other parts of the query from being deleted.  The delete 
function only operates on the part of the query that is visible. 

An alternative method is to click on the lightning bolt icon to activate the
``Selection`` mode and select the color atom(s) to be deleted.  
The grid contour may have to be hidden before the color atom(s) can be selected.  
With the ``Selection`` mode active (icon highlighted gray) select 
the color atom by clicking on it.  Once selected the color atom is highlighted in 
orange.  To select multiple color atoms CTRL-click on each or right-click and 
draw a box around the group.  Either click on the ``Delete Selected Atoms`` button 
(red 'X') or right-click on the highlighted color atom and select the ``Delete`` option.
Using the ``Selection`` mode is useful when multiple color atoms are to be deleted.

**Delete shape atom(s):**  It can be useful to delete part of the 
query molecule (shape atoms) if, for example, you are starting 
from a large query molecule but are carrying out vHTS to identify 
small ligands that are a good shape fit to only part of that query.  
Alternatively, some parts of the known active molecule may be 
important for binding and another portion requires less 
stringent alignment so a query built only from those fragments 
would be useful.

Click on the ``Delete Atoms`` (eraser) button to make it the active mode.  A gray 
background to the button shows it has been selected.  A single left 
click on the shape atom (or atoms) that you wish to delete will remove 
that feature from the query.  Multiple shape atoms can be deleted using
sequential clicks.  The portion of the shape contour associated with the 
deleted shape atom(s) will also be deleted.  To delete multiple adjacent 
shape atoms right click and drag to draw a rectangular box around the 
features to be deleted with the Delete Atoms mode button highlighted.  

The ``Delete Atoms`` mode operates on both color and shape atoms and 
will delete a color atom preferentially over a shape atom.  The 
delete function only operates on the part of the query that is visible.  
Therefore it is possible to delete shape atoms but leave behind color 
atoms with no associated shape in the query (as seen :ref:`below<color_remains_fig>`)
if the color atoms are hidden during the delete operation.  The utility of queries 
of this nature has not been evaluated at OpenEye.  It is possible that 
if a conformer is able to align with the color atom outside the shape 
during a **ROCS** alignment it may score higher than another conformer 
with an equally good alignment to the shape part of the query.  In that case the conformer 
would receive a higher ColorTanimoto score although the ShapeTanimoto 
would be unchanged.  However, this is probably only the case for color atoms 
close to the shape and these color atoms will not help to drive the 
optimization of the shape-based alignment.  Therefore, for most queries
the user should manually delete the color atoms as well as the shape atoms.

.. _color_remains_fig:

.. figure:: /_images/color_remains.png
   :scale: 75
   :align: center
   :alt: Color atoms remain after the shape atoms (and contour) have been deleted
   
   **Color atoms remain after the shape atoms (and contour) have been deleted**

An alternative is to select the shape atom to be deleted using the ``Selection`` 
tool (lightning bolt icon).  The grid contour and color atoms may have to be hidden before the 
shape atom can be selected.  Once selected, the shape atom is highlighted in 
orange.  Either click on the ``Delete Selected Atoms`` button
(red 'X') or right-click on the highlighted 
color atom and select the ``Delete`` option.

**Add color atom(s) to atoms:**  Color atoms can be added to shape atoms
in a query molecule using the :ref:`Add Color Atoms tool<add_color_fig>`.
This button contains a pop-out menu for selection of any color atom 
type for the current color force field.  In the two built-in color force fields,
these are acceptor (A), anion (An), cation (C), donor (D), hydrophobe (H) or 
rings (R).  Click on any color atom type to create atoms for that color 
type.  The button change will change the letter on the icon, as indicated in 
the list above, to indicate the active color atom type.  In the Edit Query 
mode position the color atom by clicking on any atom of the ligand.  Since 
color atoms can also be added to grids and surfaces the surface contour
should be hidden before adding the color atoms.  This is achieved
using the Toggle Surface Contour button at the bottom of the 3D window.

If a color atom is added in error then the ``File > Undo`` option will
remove it again.  Alternatively, follow the instructions to Delete
Color Atoms above.

An example of a situation where this might be useful is if the query 
ligand is a basic amine but you believe the N-atom is protonated at 
physiological pH to better interact with the protein.  Deleting the 
Donor color atom from the N followed by adding a Cation color atom 
would effect this change.  The overall shape of the query would be 
unchanged.

.. _add_color_fig:

.. figure:: /_images/add_color.png
   :scale: 100
   :align: center
   :alt: The Add Color Atoms button and sub-menu
   
   **The Add Color Atoms button and sub-menu**

An alternative method is to select the shape atom where the color 
atom is to be added using the Selection mode.  The grid contour 
may have to be hidden before the shape atom can be selected.  Once 
selected the shape atom is highlighted in orange.  Right-click on 
the highlighted atom.  A pop-up menu provides the option to 
``Create color atom...`` with a drop-down for selection of color atom type.

**Move a color atom:** Immediately after adding a color atom, ``shift + click`` in
a new location to move the added color atom to the geometric center of its initial
position and the new location. This allows a color atom to be positioned within a ring.

**Alter shape atom or color atom weighting:**  Some molecular features 
or color interactions between a ligand and a protein are more important 
than others.  This knowledge can be incorporated into the query to help 
drive the alignment and rank the hits.  One way to weight only the 
important interactions is to delete those considered less important.  
However, this can cause loss of valuable information from the query. 
More preferred would be to increase the weighting of the important 
shape or color atoms while retaining the other features in the query.  

Color atom weighting is achieved in a similar fashion to adding color 
atoms, described above.  In the :ref:`image below<weight_color_atom_fig>`, 
the highlighted acceptor has been given a double weighting (acceptor x2) by 
adding a second acceptor feature to the hydroxyl.  Select the 
Add Acceptor tool and click on the atom/color atom to be weighted.  
Similarly, use the Delete tool (eraser icon) to remove additional weighting from 
color atoms, exactly as previously described for deleting color 
atoms.  The added color atoms will be listed as 
'Shape from "User Added Features"' in the Current Query panel 
and can therefore also be deleted, hidden or selected for use in
the current query (red check mark) in that panel.  There is no 
limit to the increase in weighting that can be employed.  

.. _weight_color_atom_fig:

.. figure:: /_images/weight_color_atom.png
   :scale: 100
   :align: center
   :alt: Weighting a color atom
   
   **Weighting a color atom**

Shape atoms can be weighted by selecting the desired shape atom with the Selection 
tool so that it is highlighted in orange.  Right-click on the highlighted atom and 
from the pop-up menu select the option to ``Set shape atom strength...``  The strength can 
be weighted from 1 (normal) to 5.  This has the effect of placing up to 5 of those 
atoms at that position in space.  The atom will be displayed larger to indicate 
its weighting and the shape contour will also be expanded, as seen for the carbonyl oxygen 
:ref:`below<weight_shape_atom_fig>`.

.. _weight_shape_atom_fig:

.. list-table::
  :widths: 50 50
  :header-rows: 0
  
  * - .. image:: ../images/vrocs/weight_shape_atom_1.png
         :align: center
    - .. image:: ../images/vrocs/weight_shape_atom_2.png
  * - **Methotrexate query with all shape atom weightings set to 1 (default)**
    - **Methotrexate query with the carbonyl shape atom weighting set to 5**

**Merge color atoms:**  There are two cases where it may be useful to merge
multiple color atoms together into a single color atom.  The first occurs
when a query is composed from multiple aligned molecules, resulting in
color atoms of the same type lying very close to one another in space.
The second case occurs when a molecule gives rise to multiple color atoms
where a single color atom might better represent what the user would like
to match.  For example, a carboxylate group will by default be represented by
two acceptor color atoms, but in some cases a single acceptor color atom,
located midway between the two oxygen atoms, might be preferable.  Likewise,
a bicyclic ring system could be represented by a single ring color atom
instead of the default two.  Color atoms of the same type may be merged into
a single color atom, located at the geometric centroid of the original color
atoms, using the Merge Color Atoms tool.

.. _merge_color_atoms_fig:

.. figure:: /_images/merge_color_atoms.png
   :scale: 100
   :align: center
   :alt: Merging color atoms
   
   **Merging color atoms**

   Aligned ligands from 1C2D.pdb and 1G3D.pdb in a single query.  The highlighted area 
   illustrates where color atom merging is useful.  The arrow indicates the 
   ``Merge Color Atoms`` button

In the :ref:`Merging color atoms<merge_color_atoms_fig>` figure, the ligands 
from 1C2D.pdb and 1G3D.pdb :ref:`above<merge_color_atoms_fig>` both possess a 
terminal benzamidine group, located at nearly identical positions.

Selecting the Merge Color Atoms tool when no color atoms are selected, will
merge similar color atoms within 0.75 Angstroms of each other.  (See the
figure :ref:`Merged ligands and color atoms<merge_color_atoms_after_fig>`.)
To merge specific color atoms together, simply select two or more color atoms of the
same type, and then use the Merge Color Atoms tool.

Note that if the current query is composed from multiple molecules, it will be
collapsed into a single super molecule when color atoms are merged.  This means
that each individual ligand can no longer be separately selected, hidden, or
deleted from the current query.
   
.. _merge_color_atoms_after_fig:

.. figure:: /_images/merge_color_atoms_after.png
   :scale: 100
   :align: center
   :alt: Merged ligands and color atoms
   
   **Merged ligands and color atoms**

   Aligned ligands from 1C2D.pdb and 1G3D.pdb in a single query ("super molecule").  The highlighted area 
   illustrates where color atom merging simplified the query.

**Load grid:**  The majority of **ROCS** queries tend to be ligand-based.  
However, queries from other sources can also be useful, particularly if 
no active ligand is known.  This is discussed in :ref:`ROCS Shape 
Query Sources<shape_query_sources>`.  Grids are loaded into the **vROCS**
interface in the same  way as ligands, the major difference being 
that no color features are automatically added to a grid.  In the 
Edit Query mode ``Use File > Open`` and browse to the desired grid 
file.  The grid will be loaded into the Shape Inventory area of 
the Build Query panel from where it can be dragged up to the 
Current Query.

**Add color atom(s) to grids:**  When a grid is first loaded into **vROCS** it 
has no associated color atoms because the color atoms can only
be automatically assigned to a ligand.  
However, adding color atoms to grid-based queries can enhance 
**ROCS** search selectivity, just as for ligand-based queries.

Color atoms can be added to grid shapes in the same manner as adding 
color atoms to ligands.  Select the desired Add Color Atom tool 
(acceptor, donor, etc.) and click on the grid contour surface to 
place a color atom at that position on the contour surface.  
Clicking subsequent times on the color atom will increase 
the weighting for that color atom.  Color atoms that one
might expect to place on/near a grid surface are those that 
would make strong protein-ligand interactions, e.g. H-bonding.

.. _grid_color_fig:

.. figure:: /_images/grid_color_1.png
   :scale: 75
   :align: center
   :alt: Merged ligands and color atoms

   **Grid surface color features**

Hydrophobic and ring color atom types would normally be buried 
within the shape contour.  These can be placed by initially clicking 
on the grid surface (see :ref:`Grid surface color features<grid_color_fig>` above) 
and then CTRL-click elsewhere on
the surface to move the color feature to the mid-point between the two 
surface points (see :ref:`below<grid_color_2_fig>`).  Additional surface points can be used 
to position the color atom at the desired position.

.. _grid_color_2_fig:

.. list-table::
  :widths: 50 50
  :header-rows: 0
  
  * - .. image:: ../images/vrocs/grid_color_2a.png
         :align: center
    - .. image:: ../images/vrocs/grid_color_2b.png
  * - **Click on the grid surface to place an initial hydrophobe feature, indicated by the yellow sphere**
    - **CTRL-click (red arrow) to bury the feature mid-way between the two surface points (indicated by orange dots)**

An alternative method of placing color atoms within the grid is to use the 
Contour level slider.  The default contour level is set at 1.  Increasing 
the contour level (up to a maximum of 3) has the effect of displaying a 
smaller surface shape.  Place the color feature on the new contour surface 
(:ref:`Hydrophobe feature placed on contour surface...<grid_color_3_fig>`) 
using the Add color atoms tool described above and then use
the slider to change contour level back up to 1.0 
(:ref:`Contour level returned to 1.0...<grid_color_3_fig>`).

.. _grid_color_3_fig:

.. list-table::
  :widths: 50 50
  :header-rows: 0
  
  * - .. image:: ../images/vrocs/grid_color_3a.png
            :align: center
    - .. image:: ../images/vrocs/grid_color_3b.png
  * - **Hydrophobe feature placed on contour surface at contour level 3.0**
    - **Contour level returned to 1.0 results in a partially buried color atom**


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _vrocs_menus:

.. program:: vROCS 

==============
vROCS menus
==============

File
----

========================= ===================================================================
Menu Item                                 Description
========================= ===================================================================
New Query...                Starts the Query Building Wizard.  The resulting query 
                            (or queries) will be listed in the query input for a simple 
                            or validation run and displayed in the 3D window.  They are also 
                            placed in the Shape Inventory list.  This option is only 
                            available in view mode.
Open Query...               Opens a file browser for opening a saved **ROCS** query file.  
                            Acceptable saved query sources are molecules of a variety of 3D 
                            molecule types, grids or shape queries (\*.sq).  The opened file 
                            is listed as a potential query for simple or validation ROCS runs 
                            and displayed in the 3D window.  It is also placed in the Shape 
                            Inventory list.  This option is only available in view mode.
Add to Shape Inventory...   Starts the Query Building Wizard.  The resulting query (or 
                            queries) will be placed in the Shape Inventory list.  
                            This option is only available in edit mode
Open...                     Opens a file browser for opening a shape query source.  
                            Acceptable shape sources are molecules of a variety of 3D file 
                            types, grids or shape queries (\*.sq).  The opened file will 
                            be placed in the Shape Inventory list.  This option is only 
                            available in edit mode
Save Query...               Save the current query in **ROCS** query format (\*.sq).  
                            This is a save as... operation.  The user will be prompted to 
                            enter a filename and directory location for saving the new 
                            \*.sq file.  The current file will never be overwritten.  
                            Keyboard shortcut is CTRL+S.
Save Color Force Field...   Save as... operation to save a copy of the current color force 
                            field file and prompts for a filename and directory.  
                            This can be useful as a starting point to edit a new custom 
                            color force field file.
Clear...                    Clears all objects from the current **vROCS** session.  
                            Keyboard shortcut is CTRL+N.
Recent Queries...           Select from a list of recently opened queries - molecules, 
                            grids and shape queries.  The selected query will be added 
                            to the list of queries available for simple or validation ROCS 
                            runs and will be displayed in the 3D window.  The list persists 
                            across vROCS sessions.  This option is only available in view 
                            mode.
Recent Databases...         Select from a list of recently opened databases.  
                            The selected database will be used to populate the database 
                            field for simple **ROCS** runs.  The list persists across **vROCS** 
                            sessions.  This option is only available in view mode for 
                            the simple run set-up and sometimes from the Welcome page.
Recent Actives...           Select from a list of recently opened databases.  
                            The selected database will be used to populate the actives
                            field for validation **ROCS** runs.  The list persists across 
                            vROCS sessions.  This option is only available in view 
                            mode for the validation run set-up and sometimes from 
                            the Welcome page.
Recent Decoys...            Select from a list of recently opened databases.  
                            The selected database will be used to populate the decoys 
                            field for validation **ROCS** runs.  The list persists across 
                            **vROCS** sessions.  This option is only available in view mode 
                            for the validation run set-up and sometimes from the 
                            Welcome page.
Recents...                  Select from a list of recently opened shape sources - molecules,
                            grids and shape queries.  The list persists across **vROCS** 
                            sessions.  This option is only available in edit mode.
Exit...                     Close the **vROCS** session.  Displayed in the Application menu on 
                            Mac as ``Quit...``
========================= ===================================================================

Edit
----
========================= =================================================================
Menu Item                 Description
========================= =================================================================
Undo...                     Undo the last action.  This can be done repeatedly or see Undo 
                            History...  Keyboard shortcut is CTRL+Z
Undo History...             Shows the last 10 operations that can be selected to undo. 
                            The Undo history list can be much greater than 10 items so 
                            revisit this list to see additional items.
Redo...                     Redo the last action that was just undone.  This can be done 
                            repeatedly or see Redo History...  Keyboard shortcut is CTRL+Y
Redo History...             Shows the last 10 operations that have been undone and can be 
                            selected to redo.  The Redo history list can be much longer 
                            than 10 items so revisit this list to see additional items.
Preferences...              Opens the Preferences dialog to set user preferences that will 
                            persist across **vROCS** sessions.  There are two pages: vROCS and 
                            Display.  See below for full details.  Displayed in the
                            Application menu on Mac.
========================= =================================================================

Preferences
^^^^^^^^^^^^

Every user has his or her own individual preferences with regards 
to how molecules, grids, and surfaces should look and how applications 
should behave.  For this reason, a Preferences dialog is available 
which allows customization of the application to the user's preference.  
The first time **vROCS** is launched the Preferences will open automatically, 
to enable the user to set his or her own options.   A snapshot of the 
Preferences dialog can be seen :ref:`below<prefs_vrocs_fig>`.  On the left-hand side 
of the dialog is column containing preference categories.  These categories 
include: **vROCS** and Display.  Clicking on any of these categories will update 
the right-hand side of the dialog to display the options corresponding to 
the selected category.  The vROCS category includes preferences for **ROCS** 
and the color force fields.  The Display category contains preferences 
for the Open GL display of molecules and shapes.

vROCS Preferences
^^^^^^^^^^^^^^^^^

.. _vrocs_prefs:

.. _prefs_vrocs_fig:

.. figure:: /_images/prefs_vrocs.png
   :scale: 75
   :align: center
   :alt: Preferences: vROCS
   
   **Preferences: vROCS**

.. _prefs_opengl_fig:

========================== =================================================================
Menu Item                  Description
========================== =================================================================
Default color force field  Click the radio buttons to select the default color force field 
                           which will be used to apply color atoms to molecules that are 
                           loaded into **vROCS** or to define the nature and interaction of 
                           color atoms that are added during manual query editing.  
                           This color force field information will be saved in any saved 
                           query file.  Options are: 
                           
                           Implicit Mills-Dean
                           
                           Explicit Mills-Dean
                           
                           Custom
                           
                           To use a custom color force field define the path to the color 
                           force field (\*.cff) file that contains definitions of the color 
                           atoms.  Multiple custom color force fields can be loaded into 
                           **vROCS** and are listed in the box.  The selected (active) custom 
                           color force field will be highlighted in blue.  Custom color 
                           force fields can be deleted from the list by clicking on the 
                           red X beside their name in the list.
                           
                           Changing the default color force field during an **vROCS** session 
                           will not result in changing the force field for any currently 
                           opened molecules or queries.  Changes will take place only if 
                           no molecules or queries are opened or on closing and reopening 
                           **vROCS**.
Display ROCS run in 3D     Check on to display a 3D Open GL rendering of the query and 
                           database molecules aligning as the run progresses together with 
                           2D structures for the current 5 best hits.  Click off to display 
                           a text-based run progress summary, saving compute resources on 
                           lower performance computers.  This is equivalent to checking 
                           on/off the 3D View option in the simple or validation Run 
                           Set-Up Options dialog but persists across all runs and sessions, 
                           not a single run.
Color Atom Styles          Change the color and style for the different color atom types.  
                           Select the force field from the drop-down menu.  For each color 
                           atom type select a color from the drop-down color list and a 
                           style (solid or mesh) for the color atom display.  Restore 
                           default color atom colors and styles by clicking the Restore 
                           button below.
Restore                    Click to restore the current preferences to the default ones.
Save                       Save the current preferences for this session and for future 
                           sessions of **vROCS**.
Cancel                     Click to close this dialog without applying any of the changed 
                           preferences.
========================== =================================================================

OpenGL Preferences
^^^^^^^^^^^^^^^^^^

.. figure:: /_images/prefs_opengl.png
   :scale: 75
   :align: center
   :alt: Preferences: Display
   
   **Preferences: Display**
   
=============================== =================================================================
Menu Item                       Description
=============================== =================================================================
Background Color                Change the background color by selecting from a drop-down color 
                                list.
Lighting Position               Sets the position of the lighting used in the 3D view.
Material Shininess              Sets the shininess of solid-rendered objects in the 3D view.
Disable OpenGL Shaders          Turns off hardware shading functions.  May be useful if the
                                3D scenes are not rendering properly.
Disable Hardware Acceleration   Turns off all hardware rendering.  May be useful if scenes
                                are not rendering properly due to video driver problems.
Screenshot Shares Context       May be useful if screenshots are not being saved properly
                                on some systems.
Restore                         Click to restore the current preferences to the default ones.
Save                            Save the current preferences for this session and for 
                                future sessions of **vROCS**.
Cancel                          Click to close this dialog without applying any of the 
                                changed preferences.
=============================== =================================================================

|

There are three buttons at the bottom of the dialog.  Clicking on the Restore 
button will restore the current preferences to the default ones.  Clicking 
on the Save button will save the current preferences for this run and for 
future runs of **vROCS**.  Clicking on the Cancel button will close this dialog 
and will not apply any of the changed preferences.

Preferences are stored in a binary file (preferences.oeb) in a user-specific 
local directory on the computer currently running the application.  
The preferences file can be found in:

* ``C:\Documents_and_Settings\USERNAME\AppData\Local\OpenEye\vROCS\<version>``
  on Microsoft Windows Vista.
* ``C:\Users\USERNAME\AppData\Local\OpenEye\vROCS\<version>`` on Microsoft Windows 7.
* ``~USERNAME/.OpenEye/vROCS/<version>`` on all other platforms.  

While the preference file shares the same file extension as the 
OpenEye's binary database file, it cannot be read into **vROCS** using the 
``File > Open`` menu item.  The preferences file is loaded automatically 
when the application starts and is saved back to disk when the application 
exits.  Deleting this file is equivalent to clicking on the Restore 
button in the dialog box.

There is also a file in this same directory which called vROCS.ini 
which contains machine specific settings like the list of recent files, 
preferred layouts, and hardware stereo options.  Deleting this file 
will restore these settings to the defaults as well.

This directory can be opened from within vROCS by selecting the 
``Open User Directory`` menu item in the Help menu.

Help
----

========================== =======================================================
Menu Item                  Description
========================== =======================================================
About...                     Provides version and release information.  This should 
                             be provided when requesting technical support.  
                             Displayed in the Application menu on Mac
Documentation...             Access this user documentation manual in either PDF or 
                             HTML format.
License...                   Open and display the current license file or access a 
                             browser to set the license file.
Open Data Directory...       Opens a file browser in a platform-specific location
                             for access to the tutorial datasets.
Open User Directory...       Open a file browser in the user directory containing
                             the preferences.oeb and vROCS.ini files described 
                             above.
File Bug Report...           Opens a new email prefilled with "support@eyesopen.com"
                             in the To: field.  Write an informative title and add
                             details of the bug you wish to report.  Don't forget to
                             include details of your platform and OS.
========================== =======================================================


*********************************
Utilities
*********************************

.. toctree::
   :maxdepth: 2

   checkcff
   chunker
   hlmerge
   makerocsdb
   rocsreport



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_checkcff:

************
CheckCff
************

.. program:: checkcff

========
Overview
========

This is a simple utility that will simply apply a color force field to
one or more input molecules and output a report of color atoms added,
the TYPE of the added atom and the corresponding input molecule atoms
that matched the SMARTS defining that TYPE. Additionally,
:command:`checkcff` will output an OEB file containing molecules with
the color atoms added. This file can be loaded into VIDA and the atoms
labeled with *Name* to visually inspect which color atoms are
being added.

======================
Example Commands
======================

By default, :command:`checkcff` will use the ImplicitMillsDean color force
field. This can be over-ridden by using the :option:`-chemff` option and
providing either a name of one of the built-in color force fields
(ImplicitMillsDean, ExplicitMillsDean, ImplicitMillsDeanNoRings, ExplicitMillsDeanNoRings) or the name of a user-defined
color force field file.

So to see which atoms are considered color atoms using the ImplicitMillsDean
force field:

.. code-block:: bash

  prompt> checkcff -in mymolecules.sdf

To use the ExplicitMillsDean force field to see which atoms are considered 
to be color atoms:

.. code-block:: bash

  prompt> checkcff -in molecules.sdf -chemff ExplicitMillsDean

The run always generates a report CSV file and an OEB file that can be viewed in VIDA:

.. code-block:: bash

  prompt> checkcff -in 4cox-neutral.sdf

And the view in **VIDA** might look a bit like:

.. figure:: /_images/checkcff.png
   :scale: 75
   :align: center
   :alt: VIDA view of molecule with color atoms.

   **VIDA** view of 4COX with color atoms attached and labeled.

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing **CheckCff**
with the `--help` option.

.. code-block:: console
   
   > checkcff --help

will generate the following output:

::

   Help functions:
     checkcff --help simple      : Get a list of simple parameters
     checkcff --help all         : Get a complete list of parameters
     checkcff --help defaults    : List the defaults for all parameters
     checkcff --help <parameter> : Get detailed help on a parameter
     checkcff --help html        : Create an html help file for this program
     checkcff --help versions    : List the toolkits and versions used in the application

======================
Required Parameters 
======================

:command:`checkcff` only has 1 required commandline parameter.

.. option:: -in <filename>

  Input molecule file to be colored. Can be any one of the molecule
  file formats described in Section :ref:`queryfile`.

======================
Optional Parameters 
======================
  [Aliases=**-i**]

.. option:: -out <oebfile>

  Output OEB file name for 3D structures with color atoms named
  by the TYPE from the color force field. 

  [Default=checkcff.oeb]
  [Aliases=**-o**]

.. option:: -report <csvfile>

  Override prefix used to name report file. 

  [Default=checkcff_rpt.csv]

File Options
==================

.. option:: -log

   The argument for this flag specifies the name of
   the log file.  The level of detail for logfile information can be
   altered using the :option:`-verbose` flag.  Generation of an
   output log may be disabled by providing ``nul`` as a argument in Windows and ``/dev/null`` as an
   argument on Linux and macOS.  
   [default = ``prefix`` _log.txt]

.. option:: -prefix

   The argument for this flag defines the prefix to be used
   for various information and data files generated.  Most
   important among these is the '*prefix_parm.txt*' file which includes a
   copy of all the parameters used in the run.  The prefix is
   also used to generate a default log file name if not explicitly
   specified with the *-log* flag. 
   [default = <app_name>].

.. option:: -verbose

   This is a boolean flag that controls the level of
   detail written to the log file.  By default only
   minimal information is written to the log file. 
   Verbose logging will cause more information to be written to the log
   file in order to follow behavior during program execution.  
   [default = false]

.. option:: -molNames

   This parameter takes a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set then only molecules in the
   input file(s) (see parameter :option:`-in`) with names that match those
   in the text files will be read in.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecule(s) that are contained in a large file, without
   having to extract those molecules by hand from the input molecules file.
   [default = NONE].

.. option:: -progress

   Show progress on screen.  Options are 'none', 'dots', 'log' and 'percent'.
   The 'dots' options will displays dots on screen to show molecules
   completed.  The 'log' option will duplicate the log file on screen.
   The 'percent' option will track progress through the input file.  
   [default = none]


Overlap Prep Option Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are 6 overlap prep option parameters.

.. option:: -chemff <cff_file>

  Color-force-field name. Either the name of one of the built-in color
  force fields (ImplicitMillsDean or ExplicitMillsDean or ImplicitMillsDeanNoRings or ExplicitMillsDeanNoRings) 
  or the name of a user-defined color force field file. The format of this file is
  given in section :ref:`colorforcefield`.  

  [Default=ImplicitMillsDean]

.. option:: -assignColor

  Determines the state of the assign color flag. If true, color atoms would be 
  assigned during the :ref:`Prep<OEShape_OEOverlapPrep_Prep>`.

  [Default=true]

.. option:: -useHydrogens 

  Determines the state of the use hydrogens flag. If true, explicit hydrogens atoms would be 
  created during the :ref:`Prep<OEShape_OEOverlapPrep_Prep>`. If false, all hydrogen
  atoms would be removed.

  [Default=false]

.. option:: -assignBondiRadii

  Determines the state of the assign Bondi radii flag. If true, Bondi radii 
  would be assigned to all the atom during the :ref:`Prep<OEShape_OEOverlapPrep_Prep>`.

  [Default=false]

.. option:: -removeDups

  Determines if close color atoms with the distance less than `-minDistance`
  should be removed. 

  [Default=false]

.. option:: -minDistance

  Threshold for duplicate removal. A value in the interval (0,1) that determines the minimum
  allowed distance between two color atoms.

  [Default=0.001]


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_chunker:

***********
Chunker
***********

====================
Overview
====================

This is a simple commandline utility to take an input database file and divide it into similar-sized smaller pieces. Then
each piece can be used as a dbase file in a separate **ROCS** run. This divide-and-conquer approach is an alternative way
to run a single dbase over multiple CPUs but without the use of MPI.

======================
Example Commands 
======================

To break ``input.oeb.gz`` into 5 chunks, each with the same number of molecules.

.. code-block:: bash

    prompt> chunker -in input.oeb.gz -base bar -nchunks 5

would create

.. code-block:: bash

    bar0000001.oeb.gz
    bar0000002.oeb.gz
    bar0000003.oeb.gz
    bar0000004.oeb.gz
    bar0000005.oeb.gz

To break input.oeb.gz into chunks, each with 1000 multi-conformer molecules:

.. code-block:: bash

    prompt> chunker -in input.oeb.gz -base foo -chunksize 1000

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing **Chunker**
with the `--help` option.

.. code-block:: console
   
   > chunker --help

will generate the following output:

::

   Help functions:
     chunker --help simple      : Get a list of simple parameters
     chunker --help all         : Get a complete list of parameters
     chunker --help defaults    : List the defaults for all parameters
     chunker --help <parameter> : Get detailed help on a parameter
     chunker --help html        : Create an html help file for this program
     chunker --help versions    : List the toolkits and versions used in the application

======================
Required Parameters 
======================

.. option::  -in <filename>

    Name of input file to chunk.
    
.. option::  -base <NAME>

    Base name of output files. Output files will be sequentially numbered.

And one of the following two options must be used:

.. option::  -nchunks N

    Create N new files of equal number of conformers or molecules. Chunker will read through the entire file 
    once to count the number of conformers/molecules, then will create the new files.  The switch is the 
    ``-countConfs`` flag. N must be a positive integer.

.. option::  -chunksize M

    Create new files, each containing M molecules. M must be a positive integer.

.. note::

   Only one of ``-nchunks`` or ``-chunksize`` can be used.
   
======================
Optional Parameters
======================

.. option::  -countConfs

    If the flag ``-countConfs`` is set to
    true then the file will be switched to give approximately equal numbers of conformers in each chunk.
    The split always occurs at the end of each molecule so all the conformers for each molecule are kept
    together.  If the flag ``-countConfs`` is set to
    false then the file will be switched to give equal numbers of molecules in each chunk.
    
    [Default=true]

.. option::  -pad_zeros

   This option will pad the front of the output filenames with zeroes, which helps keep files in order 
   when doing a sort of filenames.

   [Default=true]



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_hlmerge:

***********
HLMerge
***********

=========
Overview
=========

This utility takes as input a single molecule file (SD or OEB) or list file containing one or more molecules files. It
will re-rank these input files by a user-defined SD tag. The most common use is to create a single hitlist after running
**ROCS** on the separate files created by chunker.

======================
Example Commands 
======================

Assuming a set of ROCS results for the previous chunker example are in a file called ``bar.list``:

.. code-block:: bash

    bar0000001_hits_01.sdf
    bar0000002_hits_01.sdf
    bar0000003_hits_01.sdf
    bar0000004_hits_01.sdf
    bar0000005_hits_01.sdf

To merge these, rank by Tanimoto Combo and then keep the top 200.

.. code-block:: bash
    
    prompt> hlmerge -in bar.list -out bar_hits.sdf -rankby ROCS_TanimotoCombo -besthits 200

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing **HLMerge**
with the `--help` option.

.. code-block:: console
   
   > hlmerge --help

will generate the following output:

::

   Help functions:
     hlmerge --help simple      : Get a list of simple parameters
     hlmerge --help all         : Get a complete list of parameters
     hlmerge --help defaults    : List the defaults for all parameters
     hlmerge --help <parameter> : Get detailed help on a parameter
     hlmerge --help html        : Create an html help file for this program
     hlmerge --help versions    : List the toolkits and versions used in the application

======================
Required Parameters 
======================

.. option::  -in <filename>

   Name of input file to rank, or the name of a list file
   (:file:`.lst` or :file:`.list`) containing a collection of files to rank.
   [Aliases=**-i**]

   
..  option::  -out <filename>

    Output structure file for sorted hits. Formats other than SDF or OEB will lose the SD tag data.
    [Aliases=**-o**]

    
..  option::  -rankby <SD tag>

    SD tag containing a score (that can be converted to a floating point value) to use as the score to rank with.
	
======================
Optional Parameters 
======================

.. option:: -besthits N

    Number of hits to keep.
    [Default=500]

.. option:: -biggerisbetter

    By default, hits are ranked with higher scores meaning better results. To rank by a score 
    where the smaller value is better, use -biggerisbetter false.
    [Default=true]



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_makerocsdb:

**************
MakeRocsDB
**************

=========
Overview
=========

.. program:: makerocsdb

.. note:: The format for ``.rocsdb`` is specific for **ROCS**.
  The format may change in the future, following more work in 
  optimizing for large clusters. Or the format may ultimately be
  retired if no longer needed.

In order to provide maximum throughput for scalability, this version
of ROCS comes with a utility to convert existing **OMEGA** dbase files into
a ``.rocsdb`` file. This is **not** required for normal **ROCS**
usage, only for scaling to 64 CPUs and beyond under MPI. 

======================
Example Commands
======================

So to convert an OMEGA database file, ``omega_confs.oeb.gz`` into **ROCS** DB
format:

.. code-block:: bash
  
  prompt> makerocsdb -in omega_confs.oeb.gz -out rocsinput

will create a new file, ``rocsinput.rocsdb``

By default, :command:`makerocsdb` will apply the same contiguous conformer
test that **ROCS** does and will attempt to merge contiguous conformers into
a single multi-conformer molecule on output. If this behavior is not desired, 
then the ``-scdbase`` flag can be set to true and each input molecule
will be written into the rocsdb file as a separate molecule.

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing **MakeRocsDB**
with the `--help` option.

.. code-block:: console
   
   > makerocsdb --help

will generate the following output:

::

   Help functions:
     makerocsdb --help simple      : Get a list of simple parameters
     makerocsdb --help all         : Get a complete list of parameters
     makerocsdb --help defaults    : List the defaults for all parameters
     makerocsdb --help <parameter> : Get detailed help on a parameter
     makerocsdb --help html        : Create an html help file for this program
     makerocsdb --help versions    : List the toolkits and versions used in the application

======================
Required Parameters 
======================

:command:`makerocsdb` has only 2 required command-line parameters:

.. option:: -in <filename>

  Input dbase file to be converted. Can be any one of the molecule
  file formats described in Section :ref:`databasefile`.
  [Aliases=**-i**]

.. option:: -out <prefix>

  Prefix for output ``.rocsdb`` file.
  [Aliases=**-o**]

.. option:: -scdbase

  Read input as single conformer.  Do not combine contiguous conformers.
  [Default=false]

.. option:: -chemff <cff_file>

  Chemical force field file to use.
  [Default=ImplicitMillsDean]



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_rocsreport:

************
ROCSReport
************

.. program:: rocs_report

========
Overview
========

**RocsReport** is a utility program that takes the hit molecule file generated by ROCS
and creates a multi-page PDF document that visualizes the hit structures along with their 
score information.
The layout of the generated report is depicted in
:ref:`Table: Example of a multi-page document generated by the rocs_report program<table_rocs_report_overlay>`

.. _table_rocs_report_overlay:

.. list-table:: **Example of a multi-page document generated by rocs_report program** (The pages are reduced here for visualization convenience)
   :widths: 150 150 150
   :header-rows: 1

   * - page 1 (front page)
     - page 2
     - page 3

   * - .. image:: images/rocs_report/rocsreport-page-1.png
     - .. image:: images/rocs_report/rocsreport-page-2.png
     - .. image:: images/rocs_report/rocsreport-page-3.png

=============
Report File
=============

Front Page
========================================================================================

The front page of document summarizes information about the ROCS search:

It shows the 2D representation of the query molecule.
(See :ref:`Figure: Query in 2D<figure_rocs_query_rocsreport>`).
The 2D coordinates of the query displayed in the report are driven by
3D coordinates read from the input file.
The atom colors of the 3D query are projected into the 2D
molecular graph and visualized by filled circles.
Each atom color type is associated with a color and the legend of the
color atoms is display along the 2D query structure.
The arcs around the query represents the 2D surface of the molecule.
The 3D representation of same query along with its color atoms is shown in
:ref:`Figure: Query in 3D<figure_rocs_query_VROCS>`.

.. _figure_rocs_query_rocsreport:

.. figure:: /_images/screenshot-query-rocsreport.png
    :figwidth:  1000 px
    :scale:  40 %
    :align:  center

    **Query in 2D**

    *Example of the 2D visualization of the query structure with color atoms on the front page of a ROCS report*

.. _figure_rocs_query_VROCS:

.. figure:: /_images/screenshot-query-VROCS.png
   :scale:  100
   :align:  center

   **Query in 3D**

   *Example of the 3D visualization of the query structure with color atoms in vROCS*

.. seealso::

   * :ref:`rocs_color_features_section` section

   * `OERenderShapeQuery <https://docs.eyesopen.com/toolkits/python/graphemetk/OEGraphemeFunctions/OERenderShapeQuery.html>`_ function in the **Grapheme TK** manual.

     
.. warning::

   :program:`rocs_report` currently cannot visualize ROCS outputs for multi-conformer queries.

The front page also displays the histogram of the score distribution of the input
hit molecules for the following scores:

* Tanimoto Combo score
* Shape Tanimoto score 
* Color Tanimoto score 
* 2D Similarity Tanimoto score

.. _figure_rocs_graphs_rocsreport:

.. figure:: /_images/screenshot-graphs-rocsreport.png
   :figwidth:  1000 px
   :scale:  40 %
   :align:  center

   **The histograms of the score distribution**

The first three scores are calculated by ROCS and read from the input file.
The 2D similarity scores are calculated on-the-fly by the :program:`rocs_report`
program using the tree fingerprints of the **OEGraphSim TK**  (\ [GraphSim]_\ ).

Visualizing Shape and Color Overlays
========================================================================================

Each row on the following pages represents information of an individual hit structure
read from the input file. See example in
:ref:`Figure: Example of the 2D visualization of a hit structure<figure_rocs_hit_rocsreport>`.
The 2D coordinates and layout of the hit molecule are calculated based on the
3D alignment of the hit and the query structures.
The corresponding 3D overlay between of the hit molecule and the query is show in
:ref:`Figure: Example of 3D overlay between the query and hit structure<figure_rocs_hit_VIDA>`.

.. _figure_rocs_hit_rocsreport:

.. figure:: /_images/screenshot-hit-03-rocsreport.png
   :figwidth:  1000 px
   :scale:  30 %
   :align:  center

   **Example of the 2D visualization of a hit structure**

.. _figure_rocs_hit_VIDA:

.. figure:: /_images/screenshot-hit-03.png
   :scale:  100
   :align:  center

   **Example of 3D overlay between the query (colored by green) and hit structure (colored by atomic number)**

In each row the query molecule among with distribution of the TanimotoCombo scores is depicted.
On the histogram, the position of the score of the given hit is marked with a dotted red line
(see :ref:`Figure: Example of the 2D visualization of a hit structure<figure_rocs_hit_rocsreport>`).

The hit structure is depicted three times visualizing the following information:

* **shape overlap** between the hit and the query 
* **color atom overlap** between the hit and the query 
* **2D graph similarity** between the hit and the query 

The **shape overlap** between the hit and the query is visualized by using a property map,
*i.e.* a 2D grid, laid underneath the molecule structure, where the cells of the grid that
are colored blue indicate good 3D shape overlap between the query and the hit structure.
Additionally, a clash between the hit structure and 2D molecule surface of the query
structure indicates shape mismatch in 3D.
(See :ref:`Figure: Example of visualization of shape overlay<figure_rocs_hit_rocsreport_shape>`).

.. _figure_rocs_hit_rocsreport_shape:

.. figure:: /_images/screenshot-hit-03-rocsreport-shape.png
   :figwidth:  1000 px
   :scale:  30 %
   :align:  center

   **Example of visualization of shape overlay**

.. seealso::

   * :ref:`molecular_shape_section` section

   * `OERenderShapeQuery <https://docs.eyesopen.com/toolkits/python/graphemetk/OEGraphemeFunctions/OERenderShapeQuery.html>`_ function in the **Grapheme TK** manual.

The **color atom overlap** between the hit and query are visualized with
circles. Each circle corresponds to a color atom in the query molecule. 
The color of the circle indicates the fitness of the color atom match in 3D. 
The lighter the color, the smaller the overlap between the query and hit color 
atoms in 3D. 
Unfilled circles represent unmatched query color atoms. If there is a good color 
atom match exist for a query color atom in 3D, then the circle representing 
the color atom is positioned to the matching fit color atom in 2D.

(See :ref:`Figure: Example of visualization of color atom match<figure_rocs_hit_rocsreport_color>`).

.. _figure_rocs_hit_rocsreport_color:

.. figure:: /_images/screenshot-hit-03-rocsreport-color.png
   :figwidth:  1000 px
   :scale:  30 %
   :align:  center

   **Example of visualization of color atom match**

.. seealso::

   * :ref:`rocs_color_features_section` section

   * `OERenderShapeOverlap <http://docs.eyesopen.com/toolkits/python/graphemetk/OEGraphemeFunctions/OERenderShapeOverlap.html>`_ function in the **Grapheme TK** manual.

Visualizing 2D Graph Similarity
========================================================================================

The **2D graph similarity** is visualized by using a linear color gradient
to highlight molecular similarity or dissimilarity between the hit and query
structures.
After calculating the 2D molecule similarity score, the bonds of the
hit molecule are colored based on how frequently they occur in
molecular fragments that can be also detected in the query structure.
The color pink is used to highlight parts of the hit molecule that are
2D dissimilar to the query structure. Where there is 2D similarity
detected between the hit and the query, the "yellow to dark green" color gradient is
used to highlight the bonds and the color gets greener and darker with increasing similarity.
(See :ref:`Figure: Example of visualization of 2D fingerprint similarity<figure_rocs_hit_rocsreport_2D_similarity>`).
The calculation of 2D similarity score and similarity visualization
use the tree fingerprint type implemented in the OEGraphSim toolkit.

.. _figure_rocs_hit_rocsreport_2D_similarity:

.. figure:: /_images/screenshot-hit-03-rocsreport-2D-similarity.png
   :figwidth:  1000 px
   :scale:  30 %
   :align:  center

   **Example of visualization of 2D fingerprint similarity**

The relevant score of the given hit structure is printed below the 2D
molecular structure while the histogram of the score distribution is displayed
above the 2D molecular structure.
(see :ref:`Figure: Example of the 2D visualization of a hit structure<figure_rocs_hit_rocsreport>`).

.. seealso::

   The Python script that visualizes molecule similarity based on fingerprints
   can be downloaded from the

   `OpenEye Python Cookbook <http://docs.eyesopen.com/toolkits/cookbook/python/depiction/simcalc.html>`_

=======================
Command Line Help
=======================

A description of the command line interface can be obtained by executing :program:`rocs_report`
with the `--help` option.

.. code-block:: bash

   prompt> rocs_report --help

will generate the following output:

::

  Help functions:
    rocs_report --help simple      : Get a list of simple parameters
    rocs_report --help all         : Get a complete list of parameters
    rocs_report --help <parameter> : Get detailed help on a parameter
    rocs_report --help html        : Create an html help file for this program

=======================
Required Parameters
=======================

.. option:: -in <filename>

-i  <filename>

   [keyless parameter 1]

   OEBinary input file (*.oeb* or *.oeb.gz*) or *.sdf* with results from ROCS.
   [Aliases=**-i**]

.. option:: -out <filename>

-o   <filename>

   [keyless parameter 2]

   Output .pdf file.

=======================
Optional Parameters
=======================

Input/Output Options
=====================
   [Aliases=**-o**]

.. option:: -refmol <filename>

   Reference i.e. query molecule. If omitted, the first molecule in "-in" is used
   as the reference.  This parameter is not usually required since the **ROCS** hitlist 
   includes the query molecule by default.

General Options
=================
   [Aliases=**-ref**]

.. option:: -maxpages

   Maximum number of results pages to output, including the title page.
   A value of 1 will only return the title page.
   Use 0 for no maximum.

   [Default=0]

.. option:: -verbose

   Triggers more messages

   [Default=true]

Molecule Display Options
=========================

.. option:: -aromstyle <style>
   -astl <style>

   Aromatic ring display style: *Kekule, Circle, Dash*.

   [Default=Kekule]

Report Options
================

.. option:: -pagesize <size>

-psize <size>

   Output file page size: ISO_A4, US_Letter, US_Legal.

   [Default=US_Letter]
   [Aliases=**-psize**]


ROCS Tutorials
==============

.. toctree::
   :maxdepth: 2

   rocs_tutorial_intro
   rocs_tutorial_1
   rocs_tutorial_2
   rocs_tutorial_3
   rocs_tutorial_4
   rocs_tutorial_5



﻿.. include:: ../substitutions
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _rocs_tutorial:

=================
Introduction
=================

Four tutorials are included which guide the user through examples of each 
of the main tasks available in **vROCS**.  A fifth tutorial illustrates setting 
up a simple run via the **ROCS** command line interface.  The aim of providing 
these tutorials is to familiarize the user with the steps required to complete 
each task and give an understanding of what the task involves.  More detailed 
background information on any of the options or dialogs is available in the 
Usage sections of this manual.  Each tutorial is designed to stand alone so 
the user can choose which bets fits his/her current research needs.  We 
encourage the user to run the tutorials initially and thereafter they 
can be used as a guide for your own experiments.

Data files for these tutorials are located in the directory ``OPENEYE_DIR/data/vrocs`` where ``OPENEYE_DIR`` refers to the top 
level OpenEye installation directory.  A versioned ROCS directory in ``C:\Program Files (x86)\`` is default on Windows.  The data
and documentation directories are easily accessible in OSX distributions as standalone folders in the package.    
This directory contains four sub-directories:

* The files for :ref:`Build/edit a query using the Wizard<tutorial1>` are in the sub-directory ``wizard``
* The files for :ref:`Build/edit a query manually<tutorial2>` are in the sub-directory ``edit``
* The files for :ref:`Perform a ROCS validation run<tutorial3>` are in the sub-directory ``validation``
* The files for :ref:`Perform a simple ROCS run<tutorial4>` and 
  :ref:`Perform a ROCS run from the command line<tutorial5>` are in the sub-directory ``simple``


﻿.. _tutorial1:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


========================================
Build/edit a query using the Wizard
========================================

Background information
^^^^^^^^^^^^^^^^^^^^^^
This tutorial teaches the user to create a new query to either save or to use
in ROCS.  The wizard creates a query through one of a few predesigned paths.  

You have recently been assigned to a trypsin inhibitor project.  You are 
interested in building a query from known ligands in their binding modes, 
suitable for use in **ROCS** for vHTS.  A set of 19 trypsin inhibitors are 
available as co-crystal structures from the PDB (see the IDs for trypsin inhibitors in the [PDB-IDs]_\  citation).
The dataset has been prepared by aligning the 19 protein crystal 
structures.  The ligands were 
then extracted to give a set of 19 ligands, aligned in 
the protein binding pocket frame of reference.  The query building wizard 
will be used to construct a **ROCS** query to employ only the ligands
that are most representative of the set as a whole.

The tutorial will require approximately 10 minutes to complete.

Build models using the wizard
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Open a new **ROCS** session.  At the Welcome screen select the option to 
``Create a query with a wizard``.  This will open up the ``Create a query`` dialog.

In the top tab, Create Query, select the radio button for Ligand Model Builder 
and then click Next.

In the Load Aligned Ligands tab click on the Filename area and browse to the 
file containing the 19 aligned trypsin ligands.  This file is located in the 
``OPENEYE_DIR/data/vrocs/wizard`` directory and is called 
``pdbmodel_ligands.oeb.gz``.  Click OK in the file browser to accept the 
choice of file.  The file will be loaded and the first ligand is displayed 
in the preview.  Examine the ligand by rotating (left mouse button) or 
zooming (mouse wheel) the structure image.  Scroll through the list 
of ligands using the green arrows.  When satisfied click Next to continue.

It is not required to change any of the options in the Adjust Parameters 
tab, as indicated by the green check mark next to the tab name.  However, for the 
purposes of this tutorial we will keep the 
Max Molecules Per Model as 3 (consider only models containing 1,2 or 3 molecules) 
but increase the Models to Keep to 3 (keep the best 3 models for further 
review).  Enter Trypsin in the ``Prefix`` field and check the box to ``Merge Color Atoms``.  

Click Next to begin building the models.  A progress dialog will provide information 
on the model building.  When all the 1159 models containing 1, 2 or 3 molecules 
from the dataset of 19 trypsin inhibitors have been built and compared the top 
3 models are listed in the Pick Queries dialog.

Visualize the results
^^^^^^^^^^^^^^^^^^^^^

The first model in the list, ‘Trypsin 1’, is displayed in the preview window and 
is made from three of the ligands: 1G3E.pdb, 1GHZ.pdb and 1QB6.pdb.  This is 
the model that is most representative of the dataset of 19 inhibitors as a whole.  

Note that the three ligands align at one end of the model whilst the other end is 
described by only the single, larger molecule.  Where the three ligands align 
closely the donor/cation/donor triad of color atoms have been merged to a single 
representation, instead of close color atoms from each ligand (e.g. three partially 
overlaid cation color atoms).  Retaining multiple instances of the color atoms 
would serve to stress the importance of these features in the model over the 
other features.

Click on the second model, 'Trypsin 2'.  Its name will be highlighted in blue 
and it will be displayed in the preview window.  This is the second most 
preferred model and is also made of three ligands: 1H4W.pdb, 1K1I.pdb and 1QB9.pdb.  
Note that this is a different set of three ligands than Trypsin 1 
(although it is possible for some ligands to be used in multiple high ranking models).  

The third model, 'Trypsin 3' is made of 1C5T.pdb, 1GJ6.pdb and 1QBO.pdb.  
All three models contain one of the larger, hinged ligands and at least 
one of the set of smaller ligands.

Save the results
^^^^^^^^^^^^^^^^

Place a check mark next to the name of each model to select it for export 
to the main vROCS interface.  In this tutorial we will export all three 
models and save them so they can be used in further validation experiments.
However, in your own work you may choose only some of the 
models for export.

Having checked all three models click ``Finish`` to close the ``Build a new query`` 
dialog.  Model 'Trypsin 1' will be displayed in the main vROCS 3D window 
and the Welcome panel is to the left of the screen.  In the Welcome panel 
click on ``Perform a simple ROCS run``.  The three models are listed as 
potential queries in the Inputs dialog, with 'Trypsin 1' as the active 
query.  To save 'Trypsin 1' as a ROCS saved query (\*.sq) file select 
``File > Save Query As…`` from the main File menu.  Navigate to your preferred 
working directory and enter ``Trypisn_1.sq`` as the file name.  Click ``OK`` to 
save the file.  In the query list select model 'Trypsin 2' and use 
``File > Save Query As…`` to save this query as ``Trypsin_2.sq``.  Repeat with
model 'Trypsin 3' to save a query with filename ``Trypsin_3.sq``.

Conclusions
^^^^^^^^^^^

This concludes the tutorial "Build/edit a query using the Query Wizard".  In this 
tutorial we used a set of 19 aligned known trypsin ligands and built three potential 
ROCS queries, using up to three of the ligands from the dataset.  These queries best 
describe the dataset as a whole, based on TanimotoCombo scores of all the potential 
models.  These models can be further validated before use, as described in 
the tutorial :ref:`Perform a **ROCS** validation run<tutorial3>`.

If you have time some suggestions for further study are: 

* Try changing some of the model building parameters.  (Note, it is recommended to keep the 
  maximum number of molecules in a model low (less than or equal to five), to avoid extended
  run times for model building and overly complex output models/ROCS queries.
* Modify the current force field in the Preferences dialog (Edit  > Preferences, vROCS tab) and see whether this changes the models
* Re-run the tutorial steps with your own set of aligned ligands 


﻿.. _tutorial2:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


========================================
Build/edit a query manually
========================================

Background information
^^^^^^^^^^^^^^^^^^^^^^

In this tutorial the user will learn to manually create a 
new query either for saving or for use in **ROCS**.  It also 
covers the steps required to edit or modify a saved query.

A grid shape query is available that describes a protein 
binding pocket.  To improve the quality of results obtained 
for alignment to the query you wish to add some color features 
that are known to be important for protein-ligand binding.  This
tutorial will guide the user through the basics of adding color 
atoms and saving the resulting **ROCS** query file.

The tutorial will require approximately 15 minutes 
of personal time to complete.

Build and edit a new query
^^^^^^^^^^^^^^^^^^^^^^^^^^

Open a new ROCS session.  At the Welcome screen select 
the option to ``Create or Edit a Query Manually``.  Click 
``File > Open`` and browse to the file 
``OPENEYE_DIR/data/vrocs/edit/erantag_shape.grd``.  
This is a grid-based shape file that represents the shape of 
the binding pocket for the estrogen antagonist receptor, 3ERT, 
that can be downloaded from the PDB (see ID for the estrogen antagonist receptor in the [PDB-IDs]_\  citation).  The file will be listed in the
Shape Inventory list as “unnamed”.  The grid shape will 
display in the 3D window as an opaque shape.  Click and 
drag the file up to the Current Query list.  It is 
renamed as “Shape from 'erantag'”. The representation 
in the 3D window becomes transparent.  

.. note::

  To use this query as-is in **vROCS** click the Use in **ROCS** button 
  to return to the Welcome screen.  The grid shape will be imported 
  into the query list as the active query for either a simple or validation ROCS run

Several active estrogen receptor antagonists have a similar 
color pattern, consisting of two phenol moieties, which can act 
as either donor or acceptor, and a cation on a flexible chain, 
as shown in :ref:`Annotated OEDepict TK depiction of generalized estrogen receptor active ligand<sketch_fig>`.  
These are the color atoms that will be added to the query.

.. _sketch_fig:

.. figure:: /_images/tutorial2_sketch.png
   :scale: 75
   :align: center
   :alt: Annotated OEDepict TK depiction of generalized estrogen receptor active ligand
   
   **Annotated OEDepict TK depiction of generalized estrogen receptor active ligand**
   

Rotate the shape in the 3D window until it resembles the orientation in 
:ref:`Profile orientation<shape_fig>`.

 
.. _shape_fig:

.. figure:: /_images/tutorial2_shape.png
   :scale: 75
   :align: center
   :alt: Profile orientation
   
   **Profile orientation**
   

Use the Contour slider at the bottom of the 3D window to 
raise the contour display threshold to 1.25.  Click on the 
``Add color atom`` button at the left of the 3D Window (See 
:ref:`Add acceptor atoms<add_acceptor_fig>`\ ) and 
select Acceptor from the dropdown.  Click on the contour surface 
to add two acceptor atoms, as shown in :ref:`Add acceptor atoms<add_acceptor_fig>`.

 
.. _add_acceptor_fig:

.. figure:: /_images/tutorial2_addacceptor.png
   :scale: 75
   :align: center
   :alt: Add acceptor atoms
   
   **Add acceptor atoms**
   
Click on the Add color atom tool at the left of the 3D Window 
and select Donor from the dropdown.  Click on each of the acceptor 
features to add two donor atoms at the same point, as shown in 
:ref:`Add donor atoms<add_donor_fig>`.

 
.. _add_donor_fig:

.. figure:: /_images/tutorial2_adddonor.png
   :scale: 75
   :align: center
   :alt: Add donor atoms
   
   **Add donor atoms**

Adjust the Contour slider back to a contour level of 1.0.  Click on the Add 
color atom button at the left of the 3D Window and select ``Cation`` from the 
dropdown.  Click on the contour surface to add a cation atom as shown in
:ref:`Initial cation placement<init_cation>`.  

.. _init_cation:

.. figure:: /_images/tutorial2_addcation.png
   :scale: 75
   :align: center
   :alt: Initial cation placement
   
   **Initial cation placement**

Then CTRL-click on the surface twice more, as indicated by the orange 
dots in :ref:`Final cation placement<final_cation>`, to move the cation color 
atom mid-way between the three surface points.

.. _final_cation:

.. figure:: /_images/tutorial2_addcation2.png
   :scale: 75
   :align: center
   :alt: Final cation placement
   
   **Final cation placement**

This completes adding the color points to the query.  If you make 
any errors use the Delete tool (eraser icon) at the left of the 3D window to 
delete a color atom and try again.

Save query
^^^^^^^^^^
In the Current Query area right–click on the query name and 
rename the query as "erantag_shape_color".  This is the query 
name that will be displayed in the Query list for any ROCS runs.  
To save the edited query click the Save Query button or use the menu 
item ``File > Save Query…``  Choose a directory in which to 
save the query and give it the name ``erantag_shape_color.sq``.  
To use this query in ROCS click on the ``Done editing`` icon in 
the 3D window or the ``Accept`` button to return to the 
Welcome screen.

Conclusions
^^^^^^^^^^^
This concludes the tutorial "Create or edit a query manually".  
In this tutorial we modified a shape grid by adding color 
atoms to build a more complex **ROCS** query containing information 
about known binding interactions.  This query can be further 
validated before use, as described in Tutorial 3: Perform a 
ROCS validation run.


﻿.. _tutorial3:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


========================================
Perform a ROCS validation run
========================================

Background information
^^^^^^^^^^^^^^^^^^^^^^

A validation run with **ROCS** allows you to select a set of active
molecules and a set of decoy molecules against which to run your query.  
**ROCS** is run against both datasets and generates statistics evaluating 
how well the query discriminated between the actives and the decoys.  
This becomes particularly important when building a complex query.  
It suggests confidence levels for this query in future **ROCS** runs 
against databases of compounds of unknown activity.

You have just been assigned to a new research project looking for 
trypsin antagonists.  There are no in-house lead molecules or SAR 
(structure activity relationship) yet.  However, you have built 
several potential queries from published trypsin antagonists using 
the **vROCS** Ligand Model Builder.  You would like to screen the 
corporate database to identify some compounds for screening in an 
in-house biological assay that has just come on-line.  You plan to 
use **vROCS** to validate your queries on a sample database and 
identify the most selective query before running it on the larger corporate database.  

After completing this tutorial the user will be aware of the 
steps required to set up and run a **ROCS** query validation in 
**vROCS** and analyze the resulting data.  The tutorial will require 
approximately 10 minutes of personal time and 30 
minutes of computer time to complete.

Setup ROCS run
^^^^^^^^^^^^^^

Open a new **vROCS** session.  At the Welcome screen select the 
option to ``Perform a ROCS validation``.

In the Inputs dialog you will need to select a query, set of 
active molecules and set of decoy molecules.  The fields that 
require data input are highlighted in red.  Note: if you did 
not open a new **ROCS** session you may have some fields populated 
with previously used queries and datasets.

Check that the Color F.F. dropdown has Implicit Mills Dean 
selected as the current color force field.  This is the force 
field that was used to build the query we will use.  
(Note: opening a query that was built with a force field other 
than that listed in the Color F.F. dropdown will result in a 
warning pop-up.  If this should occur then click Yes to accept 
the change to the active color force field.  This will update the 
Color F.F. dropdown and the list of available queries but will 
not change your default selection for future vROCS sessions in 
``Edit > Preferences``.)

In the Query input field click on ``Open…``
Use the file browser to navigate to either the directory where you
saved the queries built in Tutorial 1 or to
``OPENEYE_DIR/data/vrocs/validation/trypsin/`` 
and open the file ``Trypsin_1.sq``.  This is the first of three 
queries selected by the Ligand Model Builder and saved, as described 
in the tutorial :ref:`Build/edit a query using the Query Wizard<tutorial1>`.  The files 
are provided for you and completion of that tutorial is not a 
prerequisite to this tutorial.  It will be used as one of the queries for ROCS.  

The Trypsin_1.sq query is shown in the 3D window as green sticks.  
A molecular shape (transparent gray) and color atoms are automatically 
assigned.  For the purposes of this tutorial we will use the ligand 
query as-is.  Tutorial 2: Build/edit a query manually covers the details of editing a query.

Repeat the steps to open queries Trypsin_2.sq and Trypsin_3.sq into the query list.

Click on the first query in the list (Trypsin_1.sq) so that it is 
highlighted in blue and becomes the active query for ROCS.  Click on 
the text ROCS Run 1 in the Run Name field of the Inputs dialog and edit it to read Trypsin1.

For a validation run two databases are required.  The first contains 
the ‘active’ molecules.  This is a dataset that you would like to score 
highly against the query.  The second dataset of ‘decoys’ should contain 
molecules that you predict will align poorly to the query.  In a typical 
pharmaceutical industry setting the ‘actives’ might be compounds from 
your current SAR and the ‘decoys’ might be a sub-set of the corporate 
database.  In this tutorial we will use the Trypsin actives and decoys 
sets from the DUD (Directory of Useful Decoys) database (See [Huang-2006]_\).  The decoy 
set is property matched to the actives (e.g. similar molecular weight, 
calculated LogP) but molecules have dissimilar topology in order to 
provide a challenging validation experiment.  The more similar the 
actives and decoys the more confidence you can have that your query 
is truly selective.

The databases have been pre-prepared for this tutorial in the following manner.
1.	The ligands (actives) and decoys datasets were downloaded from DUD in mol2 file format. 
2.	Conformers were generated using OMEGA2.2 and default settings (up to 200 conformers for each molecule).

No effort was made to clean up the dataset and remove any duplicates, 
filter for molecular properties (in theory this was done by DUD) and 
enumerate stereoisomers.  These are all data preparation steps you 
should consider for your own dataset.  However, the purpose of this
tutorial is to illustrate the vROCS validation tools, not dataset preparation.

In the Inputs dialog click on the Actives option.  Browse to the 
database of 49 known active trypsin ligands at 
``OPENEYE_DIR/data/vrocs/validation/trypsin/trypsin_ligands_confs.oeb.gz``.
Similarly, populate the Decoys option with the database of 1664 property matched trypsin 
decoy ligands at 
``OPENEYE_DIR/data/vrocs/validation/trypsin/trypsin_decoys_confs.oeb.gz``.

Click Next to set the run options.

The Options dialog provides access to modify the main options for ROCS.  It also 
displays the ROCS command line, should you wish to repeat this run outside the vROCS 
interface.  Full descriptions of all the options are given in the 
:ref:`Validation Run options<run_setup_options>`.

The Working Directory is set by default to your vROCS installation directory.  
It is good practice to set a unique working directory for each run to avoid the 
risk of overwriting output files from old runs.  Alternatively, changing the 
Run Prefix option would have a similar outcome.  Create a working directory named 
``trypsin_validation`` in a location of your choice and assign the prefix ``trypsin1``.

Leave all the fields in the Options dialog with their default values except 
if you are using a computer with low memory.  In that situation you may want 
to toggle Off the 3D View option.  This will speed up the ROCS runs because 
the CPU is not being used for an Open GL 3D display of the aligned query 
and current database molecule.

Click Next to see the run summary.  This lists the run name, 
database, working directory, etc.

Run **ROCS** in validation mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Click Run **ROCS** to start the run.

As the run progresses the 3D window fills the screen.  The query is shown 
and the database molecules scroll by in their alignment with the query.  
On the right hand side of the screen the five current top scoring molecules 
are shown in 2D depiction, together with their TanimotoCombo score (or whichever 
score type was chosen in the Run Set-up Options dialog).  A progress bar at the 
bottom of the screen indicates how far the run has proceeded.  If the 3D view was 
selected Off then text-based progress information will be displayed.

This run requires about 10 minutes.
The relatively slow run speed is due to the large number 
of color features in the query used.  Manually editing the query to remove 
some of the color features does result in some run time speed up.  See 
the section :ref:`Editing ROCS queries in vROCS<editting_queryies>` 
and the tutorial :ref:`Build/edit a query manually<tutorial2>` for details 
on how to accomplish this.

Repeat the steps to set-up and run query Trypsin_2.sq with run name 
Trypsin2  and prefix ``trypsin2`` and Trypsin_3.sq with run name Trypsin3 
and prefix ``trypsin3``.

Visualize results
^^^^^^^^^^^^^^^^^

Once the three runs are complete you will see results listed for 
each run on a separate tab in the results spreadsheet at the bottom 
of the screen.  Click on the tab name for the Trypsin1 run to view the 
results of the first run.  On the left side of the screen navigate to 
the Run Set-up Inputs dialog and select/highlight the query Trypsin_1.sq 
in the Query list.  This action displays the query in the 3D window.  

.. note::

  In the case that 3D View was checked off during the runs click Done 
  in the run progress informational panel to restart the 3D window and display the query.

The spreadsheet lists the query and the top 20 scoring conformers ranked based 
on TanimotoCombo score (or whichever score type was chosen in the Run Set-up 
Options dialog).  The query is also listed as the first entry as an aid to comparison.  
Make the query visible by clicking in the visibility column (green circle) next to its entry. 
Select individual results by clicking on their name and scroll up/down the list with 
the arrow keys to check the alignments look reasonable.

Click on the Show the statistics icon at the far right of the spreadsheet to 
display the statistics panel for Trypsin1.  All the database molecules used in the 
search are included in these calculations, not just the top 20 that were listed in 
the spreadsheet for visual inspection.  AUC for the ROC curve and enrichment at 
0.5%, 1% and 2% are listed for the run, together with their upper and lower 95% 
confidence limits.  The ROC curve is also displayed.  An AUC of 0.855 indicates a 
query that is predictive and well able to separate the actives from the decoys. 
Change the score used in the calculations from TanimotoCombo to ShapeTanimoto 
in the Metric dropdown.  This will update the ROC plot and statistics to 
reflect that scoring metric.  The AUC is now 0.680, indicating that shape 
alone is a less selective metric for identifying trypsin actives from 
decoys and that color is an important addition to the query.

Inspect the score histogram plot by selecting Score Histogram in the 
Chart dropdown.  This displays color coded histograms for the score 
distribution within the active and decoy databases.  A more selective 
query will have a score distribution with higher frequency of obtaining a 
higher score (i.e. further to the right of the plot).  As before, changing the 
score metric will update this chart.

Compare results from multiple runs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

With the Trypsin1 results tab selected, making Trypsin1 the Base run, select 
Trypsin2 and Trypsin3 from the Compare to dropdown.  Choose ROC plot from the 
Chart dropdown and TanimotoCombo from the Metric dropdown.  The display should 
look similar to the image below:

.. figure:: /_images/tutorial3_compare.png
   :scale: 75
   :align: center
   :alt: Comparison of runs Trypsin1 (Base) with Trypsin2 and Trypsin3
   
   **Comparison of runs Trypsin1 (Base) with Trypsin2 and Trypsin3**
   

At a glance the ROC plot shows that Trypsin1 has the highest AUC, suggesting 
it is the most selective query over the entire database search.  Trypsin2 has 
a similar AUC to that of Trypsin1, suggesting that it is also an equally selective
query. However, this is not completely supported by the p-values.  Trypsin2 has a 
p-value of 0.370 when compared to the Trypsin1 base run, indicating that the Trypsin1 
query is probably the most selective of the two.  Run Trypsin3 has the lowest AUC and 
a p-value of 0.024 indicating that there is a very low probability of query Trypsin_3.sq being 
more selective than Trypsin1.  The early enrichments for all three runs are
comparable, especially when the ±95% confidence limits for each run are compared.
However, Trypsin1 has a slightly higher early enrichment (except at 5%), and can probably
be considered superior at ranking most of the actives very highly compared to both
Trypsin2 and Trypsin3 as the early enrichment p-values for those are mediocre. 

Save results
^^^^^^^^^^^^

An image of the ROC plot can be saved and used in presentations.  Click on the 
Trypsin1 run-name tab to make it highlighted as the active view.  
The ROC plot currently shows three curves, one each for runs Trypsin1 as well as 
Trypsin2 and Trypsin3.  In the ``Choose stats to save...`` dropdown select the 
option to Plot data.  In the dialog increase the dimensions 
(resolution) to 500 in the first box.  Since Maintain original aspect is checked on 
the second dimension will update automatically.  Use the Browse option to select a 
directory of your choice.  Change the name of the file form screenshot.png to 
trypsin_ROC_plot.png.  Click OK to save the image file.

It can also be useful to save a copy of the statistical comparison in the 
spreadsheet.  Click on the ``Choose stats to save…`` dropdown and select the option for 
Spreadsheet.  In the dialog navigate to a directory of your choice and name the file 
trypsin_spreadsheet.csv.  A file will be saved containing the AUC and enrichment values, 
95% confidence limits and p-values for the three runs currently being compared in the 
Trypsin1 tab.

Conclusions
^^^^^^^^^^^

From the comparison we can conclude that Trypsin_1.sq is the most selective 
query of the three in this validation.  When the query models were built
Trypsin_1.sq was also ranked highest by the Ligand Model Builder.  However, 
that was on a rigid dataset of the 19 single conformer candidates for 
the model building.  This validation was carried out on a multi-conformer 
set of active and decoy ligands which is closer to the real life scenario 
under which the query will be used i.e. the ROCS run of the corporate 
database to identify potential screening candidates.

This concludes the tutorial "Perform a ROCS validation".  

If you have time some suggestions for further study are:

* Try comparing the runs above to the Lingos 2D similarity metric.  Lingos is a useful metric 
  and often provides good selectivity
* Run a validation of the estrogen receptor antagonist shape + color query built in
  the tutorial :ref:`Create or edit a query manually<tutorial2>`.  
  Compare it against the shape alone 
  and the native ligand.  The following files are provided in the 
  ``OPENEYE_DIR/data/vrocs/validation/erantag/`` directory.
  
  * erantag_grid.sq – a ROCS saved query file of the grid shape
  * erantag_color.sq – a ROCS saved query file of the grid shape with added color points
  * 3ERT_lig.ent – the ligand from the 3ERT estrogen receptor crystal structure
  * er_antagonist_ligands_confs.oeb.gb – the dataset of active ligands
  * er_antagonist_decoys_confs.oeb.gb – the dataset of decoy molecules



﻿
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _tutorial4:

========================================
Perform a simple ROCS run
========================================

Background information
^^^^^^^^^^^^^^^^^^^^^^

A simple **ROCS** run allows you to choose a query and a database to search.  It will 
search the database for the closest matches to your query and load your results 
afterwards.  The majority of runs with **ROCS** are simple runs using a molecular shape-based 
query, with or without color atoms.  Other query types can also be used, in a similar 
fashion, as described in the section :ref:`ROCS shape query sources<shape_query_sources>`.

You are working on a project for which the current lead series has a problem with CYP2C9 
metabolism.  You are hoping to suggest some synthesis candidates that have a low risk for 
CYP2C9 metabolism.  You recently saw a paper by Sykes et. al. (\ [Sykes-2008]_\ ) in which they use **ROCS** to 
validate a database of 70 known Cytochrome P450 2C9 substrates.  You plan to use **ROCS** 
similarity to compounds in this database to predict whether your ideas will be metabolized 
by CYP2C9.  One of your ideas is shown in the depiction below.  You will use **ROCS** through the
vROCS interface.

 
.. figure:: /_images/tutorial4_2D.png
   :scale: 75
   :align: center
   :alt: OEDepict TK depiction of the synthesis candidate molecule and ROCS query
   
   **OEDepict TK depiction of the synthesis candidate molecule and ROCS query**

This tutorial will provide the user with the background required to set up a simple 
**ROCS** run in the **vROCS** interface from a saved query and analyze the results.  The tutorial 
will require approximately 10 minutes of personal time and 1 minute of computer time 
to complete.

Setup **ROCS** run
^^^^^^^^^^^^^^^^^^

Open a new **ROCS** session.  At the Welcome screen select the option to ``Start a simple ROCS run``.

In the Inputs dialog you will need to select a query and a database to search.  The fields 
that require data input are highlighted in red.  Note: if you did not open a new **ROCS** 
session you may have some fields populated with previously used queries and datasets.

In the Query input field click on ``Open query…``
Use the file browser to navigate to ``OPENEYE_DIR/data/vrocs/simple`` and open 
the file ``molecule_idea.sq``.  
The query was prepared by generating **OMEGA** conformers from a SMILES 
file of the molecule.  Default OMEGA parameters were used and the lowest energy conformer 
was selected as the query and saved as a **ROCS** saved query file named ``molecule_idea.sq``.  

The molecule is shown in the 3D window as green sticks.  A molecular shape 
(transparent gray) and color atoms are automatically assigned.  For the purposes of 
this tutorial we will use the ligand query as-is.  The tutorial :ref:`Create or edit a query<tutorial2>`
manually covers the details of editing a query.

Click on the text ``ROCS Run (1)`` in the Run Name field and edit it to read ``Molecule_idea``.

In the Inputs dialog click on the ``Database`` option.  Browse to the database at 
``OPENEYE_DIR/data/vrocs/simple`` and open the database file called 
``jmedchem_database.oeb.gz``.  The database was prepared from a SMILES file of 
the 70 CYP2C9 substrates, for which OMEGA conformers were generated with default parameters.

Click Next to set the run options.

In a location of your choice create a working directory called ``simple``.

In the literature, the authors obtained best results for their 
validation using the parameter ``Random Starts`` = 50 instead of 
the default Inertial start.  This allows more conformational space to be sampled 
but does increase the time taken by the run.  

.. note::

  Inertial starts will give identical results from run to run. 
  Using Random starts may result in slight variation in score 
  (e.g. 0.750 vs 0.749) if a run is repeated.
	
Click on the ``Random`` radio button for Start type and type 50 in the input box.  
Leave all other options as default.

Click ``Next`` to see the run summary.  This lists the run name, database, working 
directory, etc.  Click on the ``Command Line…`` option to view the full command line 
for the run.  This can be useful to set up future ROCS runs outside the vROCS 
interface e.g. to make use of distributed computing.

Run a simple ROCS run
^^^^^^^^^^^^^^^^^^^^^

Click Run ROCS to start the run.  

As the run progresses the 3D window fills the screen.  The query is shown 
and the 70 database molecules scroll by in their alignment with the query.  
On the right hand side of the screen the five current top scoring molecules are 
shown in 2D depiction, together with their score (TanimotoCombo by default or whichever 
score type was chosen in the Options dialog).  A progress bar at the bottom of the screen 
indicates how far the run has proceeded.

This run requires around 40 seconds.

Visualize and save results
^^^^^^^^^^^^^^^^^^^^^^^^^^

When the run is complete the query will display in the 3D window and the 20 top 
scoring hits, based on the score chosen in the Score by field during the run 
set-up (default is TanimotoCombo), are listed in the results spreadsheet.  This 
is intended as a quick summary view.  To examine all the hits then the full hitlist, 
named ``rocs_hits_1.oeb.gz`` (default filename) is automatically saved in the working directory 
for viewing with tools such as **VIDA**.  The query is also listed as an aid to comparison.
Make the query visible by clicking in the visibility column (green circle) next to its entry.
Click on a molecule name in the spreadsheet 
to display its best overlay with the query and scroll through the molecules to view each one.

Scores for all the available scoring functions are shown in the spreadsheet.  
Clicking on any one of the column headings will sort by that score and clicking 
multiple times will switch between ascending and descending.  The 20 hits listed 
in the spreadsheet will change to reflect the sort preference (score and 
ascending (bottom 20) or descending (top 20 hits)).  

With descending TanimotoCombo selected as the sort order look at 
the TanimotoCombo scores for the top scoring ligand.  One of the Suprofen conformer has a 
TanimotoCombo score of approximately 1.0.  (Because Random starts were 
used your score might be slightly different.)  The authors found that 
0.99 was a reasonable threshold for a “reliability” cutoff for alignments 
that reproduced known binding poses in CYP2C9.  This molecule satisfies 
that requirement.

Conclusions
^^^^^^^^^^^

The query molecule has a relatively high shape similarity to a Suprofen conformer. 
The Shape Tanimoto score of that conformer is one of the highest for the entire dataset.  
However, low color similarity for the Suprofen conformer results in an overall 
TanimotoCombo score around 1.0.  Given the low TanimotoCombo score to the known 
CYP2C9 ligands one might conclude that this 
molecule has a low risk of being metabolized by CYP2C9 and is worthy of
further investigation.

This concludes the tutorial "Perform a simple ROCS run" which guides the
user through the basics of running **ROCS** through the **vROCS** interface 
and visualizing the results.


﻿.. _tutorial5:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


==========================================
Perform a ROCS run from the command line
==========================================

Background information
^^^^^^^^^^^^^^^^^^^^^^

A simple **ROCS** run allows you to choose a query and a 
database to search.  It will search the database for 
the closest matches to your query and load your results 
afterwards.  The majority of runs with **ROCS** are simple runs 
using a molecular shape-based query, with or without color 
atoms.  Other query types can also be used, in a similar 
fashion, as described in section 
:ref:`ROCS shape query sources<shape_query_sources>`.

You are working on a project for which the current lead series 
has a problem with CYP2C9 metabolism.  You are hoping to suggest
some synthesis candidates that have a low risk for CYP2C9 
metabolism.  You recently saw a paper by Sykes et. al (\ [Sykes-2008]_\ ) in 
which they use ROCS to validate a database of 70 known 
Cytochrome P450 2C9 substrates.  You plan to use ROCS 
similarity to compounds in this database to predict whether 
your ideas will be metabolized by CYP2C9.  One of your ideas 
is shown in the :ref:`OEDepict TK depiction below<tutorial5_2D_fig>`.  
You plan to use ROCS command line.

.. _tutorial5_2D_fig:

.. figure:: /_images/tutorial5_2D.png
   :scale: 75
   :align: center
   :alt: OEDepict TK depiction of the synthesis candidate molecule and ROCS query
   
   **OEDepict TK depiction of the synthesis candidate molecule and ROCS query**

This tutorial will provide the user with the background required to 
set up a simple **ROCS** run in the command line ROCS interface from a 
saved query and analyze the results.  The tutorial will require 
approximately 10 minutes of personal time and 1 minute of
computer time to complete.  This is a repeat of the simple run the 
vROCS tutorial :ref:`Perform a simple ROCS run<tutorial4>`.

Setup ROCS run
^^^^^^^^^^^^^^

Open a command prompt and navigate to a working directory of your
choice.  At the very minimum **ROCS** requires an input query file and an 
input database file.  There are numerous additional parameters 
(e.g. specifying a custom color force field file) that can be added 
to the command, as well.

In the **vROCS** tutorial :ref:`Perform a simple ROCS run<tutorial4>`, 
the command line provided to **ROCS** (on Windows) is:

.. code-block:: bash

	rocs.bat \
	-query molecule_idea.sq \
	-dbase jmedchem_database.oeb.gz \
	-prefix rocs \
	-outputdir C:/Users/username \
	-besthits 500 \
	-rankby TanimotoCombo \
	-shapeonly false \
	-randomstarts 50 \
	-opt true \
	-scoreonly false \
	-optchem true \

This is found in the ``Command line…`` information field of the run 
set-up dialog.  Most of these parameters are default.  The only one 
that was changed was –randomstarts 50, instead of the default Inertial start. 

Run a simple ROCS run
^^^^^^^^^^^^^^^^^^^^^

At the command prompt type the following command to run ROCS.  

.. note::
  
  If the query and database files are in your current working 
  directory you do not need to specify a full directory path 
  to the files.  If not, specify the full path to the query and database files.

.. code-block:: bash

	rocs \
	–query \
	OPENEYE_DIR/data/vrocs/simple/molecule_idea.sq \
	–dbase \
	OPENEYE_DIR/data/vrocs/simple/jmedchem_database.oeb.gz \
	–prefix tutorial5 \
	–randomstarts 50

This run requires about 40 seconds.

Visualize and save results
^^^^^^^^^^^^^^^^^^^^^^^^^^

ROCS automatically saves the following files using the prefix given above 
in the naming convention.  If no prefix is given then the default prefix is 
rocs.

* prefix_parm
* prefix.log
* prefix_ref.sq
* prefix_1.rpt
* prefix_1.status
* prefix_hits_1.sdf

The .rpt file contains all the score data in a tab delimited format. 
The .sdf contains all the database hits in their aligned conformation, 
together with scores.  This sd file is suitable for opening in VIDA 
for further examination.

Conclusions
^^^^^^^^^^^

This concludes the tutorial "Perform a **ROCS** run from the command line"
which guides the user through the basics of running a simple **ROCS**
run through the command line interface and visualizing the results.



.. _rocs_theory:

Theory
======

.. toctree::
   :maxdepth: 2

   shape_shape
   shape_color
   shape_cff
   measure_similarity



﻿.. include:: ../substitutions
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _molecular_shape_section:

==================
Shape Theory
==================

What do we mean by shape? The word is often used without consideration
of precise meaning but in this document we shall be very clear as to
the definition of shape. Two entities will have the same shape if
their volumes exactly correspond. The more the volumes differ, the
more the shapes will differ. We will give a precise mathematical
exposition below, but it is worth noting even at this most basic level
shape is defined as a relative quantity, depending on references to
other shapes. In this we differ from approaches that attempt to
provide absolute, canonical, *shapes* by which to categorize
molecules.

What do we mean by *volume*? A volume is any scalar field. This means a
function that has a single number, or *scalar*, value at each point in
space.  The *special case* for the common understanding of volume is a
specific scalar field that has a value of one inside an object and zero
outside. The volume of a scalar field is:

.. math::

   V \mbox{(volume)} = \int f(x,y,z) dv

The volume function, **f**, is also referred to as the *characteristic*
function.  When the characteristic function corresponds to the common
definition of a volume field this integral corresponds to what is commonly
expected by volume.  However, we are not restricted to such simple functions
and can still calculate a **V**. In general the volume of a scalar field is a
*contraction* of the information represented by that characteristic
function.  It is more precisely referred to as the zeroth-order contraction,
or *moment*.  We will discuss other moments and their uses later, but one
immediate observation is that two objects cannot have the same shape if their
volumes are not the same. The converse is obviously not true. Rather, two
objects can have the same volume and not have the same shape. Volume is
typical, therefore, of most contractions of information.

We can now write down a precise definition of shape similarity. Consider the
integral:

.. math::

   S_1 = \int |f(x,y,z) - g(x,y,z)| dV

where **f** and **g** are different characteristic functions. If this
integral is zero then **f** and **g** are actually the same function and
therefore correspond to the same shape. The larger the integral, the
more different the shapes defined by **f** and **g**. It defines a metric
quantity between the two fields **f** and **g**. The word *metric* is
used loosely to mean *shape*, but here we mean the precise mathematical
definition: *i.e.* a distance that is 1) always positive, 2) zero if
and only if two entities are identical and 3) that obeys the triangle
inequality. The triangle inequality states that if entity A is
distance x from entity B and B is distance y from entity C then the
distance between A and C is bounded by **|x-y|** and **|x+y|**. The type
of comparison shown in S\ :sub:`1` is referred to as an L\ :sub:`1`
metric. Another metric is the S\ :sub:`2` metric:

.. math::

   S_2=\sqrt{\int [f(x,y,z)-g(x,y,z)]^2 dV}

Multiplying the terms in the integral out gives:

.. math::

   S_2^2 = \int f(x,y,z)^2dV + \int g(x,y,z)^2dV - 2\int f(x,y,z)g(x,y,z)dV

This is the fundamental equation for shape comparison. We rewrite it as:

.. math::

   S_{f,g} = I_f + I_g - 2O_{f,g}

The *I* terms are the self-volume overlaps of each entity (for our purposes -
molecule), while the *O* term is the overlap between the two functions. They
constitute the three terms we need to compare the shapes of two
fields. The *I* terms are independent of orientation but not *O*. Finding the
orientation that maximizes *O*, and hence minimizes *S_{f,g}*, is equivalent to
finding the best overlay between the two objects (a quantity that has its own,
distinct metric properties). We also note here that the quantity referred to
as a Tanimoto coefficient may be derived by recombining *I*'s and *O* so:

.. math::

   Tanimoto_{f,g} = \frac{O_{f,g}}{I_f+I_g-O_{f,g}} \label{Tanimoto}

Tanimoto coefficients will be familiar to those who use them for bitvector
fingerprint comparison.  An alternative measure is the Tversky coefficient,
also mostly used for similarity between bitvector fingerprints. Similarly to
the Tanimoto coefficient above, we can define a shape Tversky measure. The
base equation for the Tversky coefficient is:

.. math::

   Tversky_{f,g} = \frac{O_{f,g}}{\alpha I_f+\beta I_g} \label{tversky}

Normally, *alpha + beta = 1*, and for our current use, *alpha* is chosen to
be 0.95. Since this introduces an asymmetry, the Tversky calculation depends
on which molecule's self-overlap has the *alpha* pre-factor.
ROCS calculates two Tversky values, one with the query
molecule with *alpha* as the pre-factor and a second with the database
molecule with *alpha* as the pre-factor.  Also, note that since shape is
a field property, instead of a simple scalar like a bitvector, shape Tversky
can be larger than 1.0 since the overlap *O_{f,g}* can be larger than
a molecule's self-overlap, *I_f*.

The OpenEye Shape Toolkit is a set of calculational objects designed to
facilitate the calculation of these field-metric quantities. ROCS is an
application built on top of the Shape toolkit.

.. _gaussians_and_shape:

Shape Characteristics and the Use of Gaussians
==============================================

Molecules are traditionally viewed as a set of fused spheres, sometimes
referred to as the CPK model. The common view of molecular volume is then of a
characteristic function that is one (1) inside at least one sphere and zero
(0) outside. How do we calculate the volume of such a seemingly simple
function?  The volume of a single sphere is *(4pi r^3)/3* but the complication
for two fused spheres is that we have to account for the shared
volume and not count it twice. For more than two atoms, there are triple
intersections that must be added back in if we have removed the three
pairs of intersections.  The general formula for N spheres that explicitly
calculates the volume of every level of overlap and its correct contribution
is:

.. math::

   V = 1 - \int \prod_i^N (1 - f_i)dv

This is easy to write, not so easy to solve because the analytic formulae for
overlaps of increasing order are highly non-trivial (although they have been
derived to arbitrary order). It is fair to say that this has hindered the
development of shape comparison in many ways. Attempts to use analytic
formulae led to very slow programs and approximate methods, for instance using
grids of points that are turned *in* or *out* by each sphere, do not give
smooth gradients required for minimization. Brian Masek (AstraZeneca) was the
first to attempt to optimize overlaps of molecules using the analytic
approach [Masek-1993]_. His program would take several minutes per minimization. In addition
it would often suffer from a common problem when using functions that vary
sharply (such as solid spheres): it would often get stuck in local
minima. Nevertheless, Brian did have encouraging success using this method to
find similarities not obvious from chemical structure.

The conceptual breakthrough in shape comparison came in 1995 in a paper by
Andrew Grant (AstraZeneca) and Barry Pickup (University of Sheffield)
(\ [Grant-1995]_\ , [Grant-1996]_\ , [Grant-1997]_\ ). They showed that if one let
go of the concept of the characteristic function being
binary, and instead use a sum of continuous functions, *i.e.*
a Gaussian, that the solid-sphere volume, could be recovered to high
accuracy (typically ~0.1%). A sphere has one defining parameter,
its radius, whereas a Gaussian has two defining parameters, its prefactor,
*p*, and its width, *w*:

.. math::

   pe^{-wx^2}

Grant and Pickup found that by fixing *p* to 2.7 and setting *w* for
each atom such that the volume integral for each atom agreed with its
solid-sphere volume, they achieved remarkable precision. In addition,
the overlap terms between any two atoms, and hence any higher-order
overlaps, are all Gaussian functions themselves because of the
Gaussian Contraction formula (shown here for one spatial variable):

.. math::

   \int e^{a(x-x_i)^2}e^{b(x-x_i)^2} = \int e^{(a+b)(x-x_i)^2}

*i.e.* two atomic-Gaussians overlap to produce another Gaussian.
Likewise, a three atomic-Gaussian overlap is that of an
overlap-Gaussian with an atomic-Gaussian, hence another Gaussian. The
simplicity of these formulae and the formula for the volume of each
individual Gaussian leads to very efficient algorithms for the
calculation of the volume of a molecule so represented (the OpenEye
method calculates several thousand volumes per second while
calculating intersections up to sixth order).

In addition to simple calculation of molecular volume, which is the
zeroth-order moment of the characteristic function, the ease of
evaluation of intersections allows for accurate calculation of
high-order moments: called the *steric multipoles*. For
instance, if the product formulae for atomic and intersection
Gaussians yields *n* Gaussians, the first order moments are:

.. math::

   M_{1,x} =  \sum_{i=1}^n \int xe^{a_i|(x-x_i)^2+(y-y_i)^2+(z-z_i)^2|}

   M_{1,y} =  \sum_{i=1}^n \int ye^{a_i|(x-x_i)^2+(y-y_i)^2+(z-z_i)^2|}

   M_{1,z} =  \sum_{i=1}^n \int ze^{a_i|(x-x_i)^2+(y-y_i)^2+(z-z_i)^2|}

These integrals are easy to solve and their sum can be set to zero by an
appropriate choice of origin: the center of *mass* for the sum of Gaussians.
Second-order moments are found from integrals of the type:

.. math::

   M_{2,PQ} = \sum_{i=1}^n \int PQe^{a_i|(x-x_i)^2+(y-y_i)^2+(z-z_i)^2|}

where P and Q are chosen from (x,y,z), *e.g.* x\ :sup:`2`, xy etc.

These moments can be thought of as a symmetric 3*3 matrix which we
refer to as the *mass matrix*.  Rotating or translating the molecule
will change the moments and the transform that sets the first-order
moments to zero and diagonalizes the mass-matrix puts the molecule
into its *inertial frame*. By convention we assign the x-axis to the
largest eigenvector of the mass matrix, y-axis to the median
eigenvector, z-axis to the smallest. Note that this orientation is
still not uniquely defined: 180 degree rotations around any axis also
diagonalize the mass-matrix.  The eight (2\ :sup:`3`) possible transforms
that can be generated by combinations of such rotations actually lead
to four unique inertial orientations.

If a molecule is aligned to its inertial frame, all higher-order
steric multipoles become invariant, ignoring certain sign-changes from
the four-fold degeneracy of the inertial frame. As such they, as well
as the second-order moments, are shape *descriptors*. They are still
contractions of the information contained in the characteristic field,
*i.e.* two molecules can have the same steric moments and yet have
different shapes. (Moments are *complete* in that if we calculate
them to infinite order they do exactly define volume but this is
seldom a practical approach!) Nevertheless, they do contain useful
information and can be used as a rapid, approximate, filter for shape
similarity.

The same advantages that allow for the calculation of molecular volume
carry over to the calculation of molecular volume overlap. The overlap
of volumes are Gaussian contractions, easily tabulated and efficiently
retrieved. Andy re-wrote Brian's program and obtained an
order-of-magnitude improvement in performance as well as another
remarkable observation: if the starting orientation of each molecule
is that given from the inertial frame then very few "false" minima are
produced. The smoothness of the Gaussian characteristic function is
enough to overcome the problems with convergence in Brian's program.
The four possible "inertial" starting points were enough to find the
best, global, overlay between two molecules. This observation and the
Gaussian approach are the basis of the OpenEye Shape Toolkit and ROCS
program for rapid shape overlay.

But note, despite the algorithmic advantages, a correlation with
common perception has been lost. Because the pre-factor of each atomic
Gaussian is not unity, the characteristic function does not correspond
to the inside/outside description with which we are most
comfortable. In the Gaussian model all points in space are to some
degree inside and to some degree outside. That is, the Gaussian model
typically shows about 0.1% error with respect to the solid sphere
model due to the fact that is includes a portion of all points in
space inside the volume.



﻿
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _rocs_color_features_section:

==================
Color Features
==================

In addition to shape-alignments **ROCS**, optionally, considers chemistry 
alignment, known as ‘color’.  User specified definitions of chemistry 
can be included in the superposition and similarity analysis process to 
facilitate the identification of those compounds that are similar both 
in shape and chemistry.  

Color atoms are described as Gaussians and displayed in **vROCS** as colored spheres.  
The Gaussian for a color atom is relatively hard with a steep gradient.  
:ref:`Figure: Hard vs. Soft Gaussians<gaussians_figure>` illustrates hard vs 
fuzzy Gaussians.  Both Gaussians in the figure represent the same volume as 
the sphere.  However, the hard Gaussian,  with the steep gradient, reaches 
a probability of zero (0) within the radius of the sphere.  The color features 
are either matched, if they fall within the sphere radius, or not matched.  
In the case of the fuzzy Gaussian there are areas outside the volume 
of the sphere (the area under the curve indicated by the two arrows) where 
the Gaussian probability is greater than zero.  This would allow color features to 
match even when they align well outside the sphere representing the color atom.   
That situation would lead to less precise alignments and, for that reason, 
the ‘hard’ Gaussian is employed.
 
.. _gaussians_figure:

.. figure:: /_images/gaussians.png
   :scale: 75
   :align: center
   :alt: Hard and soft shape gaussians
   
   **Hard vs. Soft Gaussians**
   
   A sphere described by two different Gaussian functions.  The ‘hard’ 
   Gaussian (dashed) is the one employed by ROCS to approximate a color atom sphere.

**ROCS** comes pre-loaded with two color force fields, Implicit Mills Dean (default) and
Explicit Mills Dean.  These are described in color force field files (\*.cff) located 
in the **ROCS** data directory.  A sample color force field file, ``sample.cff``, 
is also provided as a template for a user’s own custom force field.  The desired force 
field file is supplied to **ROCS** either at the command line using the ``-chemff`` command 
or in the **vROCS** Preferences menu.  Further information on editing color force field 
files is given in the section :ref:`colorforcefield`.

The color force field is used to measure chemical similarity between the query 
and the database molecule 
and to refine shape-based overlays.  The color force field file describes:

* Color atom types
* Which functional groups the color atoms should be applied to.  **ROCS** uses 
  only the heavy atoms of molecules, hydrogens are ignored.
* Whether the interaction between color atoms is attractive or repulsive.  
  Interactions between color atoms of the same type are always
  attractive.  The weight term describes the strength of the interaction, 
  relative to the shape gradients and the range term affects 
  the range of the interaction.

The color features described in the Implicit and Explicit Mills Dean color force field files include:

:Donor: Functional groups that can act as H-bond donors e.g. acid-OH
:Acceptor:	Functional groups that can act as H-bond acceptors e.g. carboxylate
:Anion: Functional groups with either localized or delocalized negative charge e.g. tetrazole
:Cation: Functional groups with either localized or delocalized positive charge e.g. guanidinium
:Hydrophobe: Terminal or nonterminal aliphatic groups, including Br and I
:Rings: Rings of defined size e.g. 4-7 atoms

A custom force field file can include other features that you define e.g. positive, negative, carbonyl_linker, metal_binder.  
For each color atom type a set of SMARTS is used to define the specific functional groups to which the color atom will be applied.  The Implicit and Explicit Mills Dean force fields differ in these functional group definitions.  For example, the Explicit Mills Dean force field allows a primary amine to be an acceptor as well as a donor whereas it is a donor only in the Implicit Mills Dean force field.

The color force field can also be used for post-shape scoring either alone, e.g. ColorTanimoto and Color Tversky, or in combination with shape scores, e.g. TanimotoCombo and TverskyCombo.  Some additional scores are available with color:

* ScaledColor	
* ComboScore
* ColorScore

These scores are defined in the section :ref:`Report File <reportfile>`.

﻿.. include:: ../substitutions
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _colorforcefield:

===================
Color Force Field
===================

The chemical force field can be used to measure chemical complementarity, and to 
refine shape based superpositions based on chemical similarity. The CFF is 
composed of SMARTS rules that determine chemical centers, plus rules to determine 
how such centers interact.

Default Color Files
-------------------

Two color force fields, ImplicitMillsDean and ExplicitMillsDean, are built into 
ROCS. Both these force fields define six similar TYPE color force-fields. The 
types are hydrogen-bond donors, hydrogen-bond acceptors, hydrophobes, anions, 
cations, and rings. The ImplicitMillsDean force field is recommended.

ImplicitMillsDean includes a simple pKa model that assumes pH=7. It defines 
cations, anions, donors and acceptors in such a way that they will be assigned 
the appropriate value independent of the protonation state in the dbase or query 
file. For example, if a molecule contains a carboxylate, ImplicitMillsDean will 
consider it an anionic center independent of whether it is protonated or 
deprotonated in the dbase file. This is convenient for searching databases which 
have not had careful curation of their protonation states. The ExplicitMillsDean 
file has a similar overall interaction model, however, it does not include a 
pKa model. It interprets the protonation and charge state of each molecule 
exactly as it is in the database. Thus, if a sulfate is protonated and neutral, 
it will not consider it an anion.

The hydrogen-bond models in both ImplicitMillsDean and ExplicitMillsDean are 
extensions of the original model presented by Mills and Dean (\ [Mills-Dean-1996]_\ ).  They both have
donors and acceptors segregated into strong, moderate and weak categories.

Color File Format
-----------------

As an alternative to the built-in force fields, the user can define a new 
color force field using the format described in this section.
The following is a simplified example of a color force field specification.

::
  
  DEFINE hetero [#7,#8,#15,#16]
  DEFINE notNearHetero [!#1;!$($hetero);!$(*[$hetero])]
  #
  #
  TYPE donor
  TYPE acceptor
  TYPE rings
  TYPE positive
  TYPE negative
  TYPE structural
  #
  #
  PATTERN donor [$hetero;H]
  PATTERN acceptor [#8&!$(*~N~[OD1]),#7&H0;!$([D4]);!$([D3]-*=,:[$hetero])]
  PATTERN rings [R]~1~[R]~[R]~[R]1
  PATTERN rings [R]~1~[R]~[R]~[R]~[R]1
  PATTERN rings [R]~1~[R]~[R]~[R]~[R]~[R]1
  PATTERN rings [R]~1~[R]~[R]~[R]~[R]~[R]~[R]1
  PATTERN positive [+,$([N;!$(*-*=O)])]
  PATTERN negative [-]
  PATTERN negative [OD1+0]-[!#7D3]~[OD1+0]
  PATTERN negative [OD1+0]-[!#7D4](~[OD1+0])~[OD1+0]
  PATTERN structural [$notNearHetero]
  #
  #
  INTERACTION donor donor attractive gaussian weight=1.0 radius=1.0
  INTERACTION acceptor acceptor attractive gaussian weight=1.0 radius=1.0
  INTERACTION rings rings attractive gaussian weight=1.0 radius=1.0
  INTERACTION positive positive attractive gaussian weight=1.0 radius=1.0
  INTERACTION negative negative attractive gaussian weight=1.0 radius=1.0
  INTERACTION structural structural attractive gaussian weight=1.0 radius=1.0

There are four basic keywords in a cff file: DEFINE, TYPE, PATTERN, and 
INTERACTION. The TYPE field can be any user-defined term. TYPES can be 
any user-specified string such as “donor”, “acceptor”, “lipophilic anion” 
etc. The PATTERN keyword is used to associate SMARTS patterns with these 
types. There is no restriction on the number of patterns that can be 
associated with a user defined type. The position in Cartesian space 
of the PATTERN is taken as the average of the coordinates of the atoms 
that match the SMARTS pattern. If the desired location of the PATTERN 
is on a single atom of a larger SMARTS pattern recursive SMARTS 
(written as ‘[$(SMARTS)]’ can be used to this effect. Only the first atom 
in a recursive SMARTS pattern ‘matches’ the molecule, and the rest of the 
SMARTS pattern defines an environment. By writing a SMARTS pattern in 
recursive notation the location of the PATTERN will be taken as the
atomic position of the first matching atom in the pattern. In order to 
simplify both reading and writing SMARTS, intermediate SMARTS can be 
associated with words using the DEFINE keyword. Once defined, these words 
can then be used as atom primitives in subsequent SMARTS patterns with the 
$ prefix (see “DEFINE hetero” and “PATTERN donor” above).

Interactions between types are associated with the INTERACTION keyword. 
Two user-defined types must be listed, and whether their interaction is 
attractive or repulsive. The height and radius can be modified by keywords 
WEIGHT and RADIUS. At present, the only alternative to a Gaussian decay is 
invoked by the DISCRETE keyword. A discrete interaction contributes all of 
WEIGHT if the inter-type distance is less than RADIUS, or zero. Since it 
is not differentiable it makes no contribution to optimization (i.e. because 
the gradient of a DISCRETE function is 0 or infinite).

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _shape_similarity_section:

.. _shape_similarity:

======================
Similarity Measures
======================

Measuring molecular similarity or dissimilarity has two basic components:
the representation of molecular characteristics (such as shape and color)
and the similarity coefficient that is used to quantify the degree of
resemblance between two such representations. Different similarity coefficients 
quantify different types of structural resemblance. 

The table below defines the basic terms that are used in
shape-based similarity calculations.

.. _table_shape_basic_terms:

.. list-table:: **Basic components of similarity calculation**
   :widths: 40 160
   :header-rows: 1

   * - Symbol
     - Description

   * - :math:`selfA`
     - Self-overlap or self-color score for molecule A

   * - :math:`selfB`
     - Self-overlap or self-color score for molecule B

   * - :math:`overlapAB`
     - Overlap or color score between molecules A and B

.. _shape_tanimoto:

Tanimoto
----------------------------------------------------------------

**Formula:**

  :math:`Tanimoto_{A,B} = \frac{overlapAB}{selfA + selfB - overlapAB}`

The Tanimoto similarity measure is symmetric and always has a value between
0.0 and 1.0 for both shape and color.

.. _shape_tversky:

Tversky
----------------------------------------------------------------

**Formula:**

  :math:`Tversky_{A,B} = \frac{overlapAB}{\alpha * selfA + \beta * selfB}`

The Tversky similarity measure is asymmetric.
Setting the parameters :math:`\alpha = \beta = 0.5` makes it symmetric and 
somewhat identical to using the :ref:`shape_tanimoto` measure.

The factor :math:`\alpha` weights the contribution of the first
`reference` molecule. The larger :math:`\alpha` becomes, the more
weight is put on the self-overlap of the reference molecule.

Unlike Tanimoto similarity, Tversky similarity may not always have a
value between 0.0 and 1.0.  This is true for both shape and color.
Depending on the number of atoms between molecules A and B,
it is possible to have :math:`|overlapAB| > |selfA|`, and that along with
certain values of :math:`\alpha` can sometimes lead to :math:`Tversky_{A,B} > 1.0`.

.. Note::

    The default settings for ``RefTversky`` use :math:`\alpha = 0.95` and
    :math:`\beta = 0.05`, and the default settings for ``FitTversky`` use
    :math:`\alpha = 0.05` and :math:`\beta = 0.95`.





.. _rocs_releasenotes:

Release History
===============

.. toctree::
   :maxdepth: 3

   version3_10_0
   version3_9_0
   version3_8_0
   version3_7_0
   version3_6_2
   version3_6_1
   version3_6_0
   version3_5_1
   version3_4_3
   version3_4_2
   version3_4_1
   version3_4_0
   version3_3_2
   version3_3_1
   version3_3_0
   version3.2.2
   version3.2.1
   version3.2.0
   version3.1.2
   version3.1.1
   version3.1.0
   version3.0.0
   version2.4.2
   version2.4.1
   version2.3.1
   version2.3.0
   version2.2.0

.. only:: oehtml


#################
ROCS 3.9.0
#################

.. program:: rocs

****************************************
New Features
****************************************

* A new option, :option:`-coloronly`, has been added that enables overlay optimization against
  only the color components of a query.

* Molecules containing just color atoms or :ref:`OEShapeQuery<OEShape_OEShapeQuery>`
  containing just color Gaussians are now allowed as queries through :option:`-query`.

****************************************
Related Toolkit Information
****************************************



Shape TK 3.9.0
================================================================================

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

* The :ref:`SetupRef<OEShape_OEOverlay_SetupRef>` method in 
  :ref:`OEOverlay<OEShape_OEOverlay>` now accepts molecules containing only color
  atoms. Accordingly, any molecule containing only color atoms or an
  :ref:`OEShapeQuery<OEShape_OEShapeQuery>` containing only color Gaussians
  can now be used as a reference for overlay optimization.

* The :ref:`SetupRef<OEShape_OEOverlapFuncBase_SetupRef>` method in 
  :ref:`OEOverlapFunc<OEShape_OEOverlapFunc>` now accepts molecules and
  :ref:`OEShapeQuery<OEShape_OEShapeQuery>` containing just color components.

* A new class, :ref:`OEHermiteOverlay <OEShape_OEHermiteOverlay>`, and a corresponding options class,
  :ref:`OEHermiteOverlayOptions <OEShape_OEHermiteOverlayOptions>`, are introduced, enabling
  overlays using the Hermite expansion approach. Three types of reference and database molecule
  representations are supported: Hermite vector, molecule, and scalar grid. Consequently, grid/grid
  overlays are enabled by using these classes.

* The grid-to-Gaussians fit algorithm, to add Gaussians in an :ref:`OEShapeQuery<OEShape_OEShapeQuery>`
  using :ref:`AddShapeGaussians<OEShape_OEShapeQuery_AddShapeGaussians>` and 
  :ref:`AddColorGaussians<OEShape_OEShapeQuery_AddColorGaussians>`,
  has been improved for better representation of the grid by the generated Gaussians.
  With the introduction of the modified algorithm, some of the associated options in
  :ref:`OEShapeQueryOptions <OEShape_OEShapeQueryOptions>` are no longer relevant and have been
  removed from the class API. The following functions have been removed:


  * ``GetDuplicateDistance`` and ``SetDuplicateDistance``
  * ``GetMaxNumGaussians`` and ``SetMaxNumGaussians``


* A new overload has been added for :ref:`Transform <OEShape_OEBestOverlayScore_Transform>` that enables
  transformation of a scalar grid by the rigid transformation in 
  :ref:`OEBestOverlayScore<OEShape_OEBestOverlayScore>`.

* A new overload has been added for :ref:`Setup<OEShape_OEStarts_Setup>` that enables
  setting up :ref:`OEStarts<OEShape_OEStarts>` with known fit symmetry.

* The following new methods have been added to :ref:`OEHermite <OEShape_OEHermite>` to
  enhance usability:

  * :ref:`NumCoefficients<OEShape_OEHermite_NumCoefficients>`
  * A new overload for :ref:`GetCoefficients<OEShape_OEHermite_GetCoefficients>`

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

* An issue related to :ref:`Init <OEShape_OEColorForceField_Init>`
  was causing intermittent slowdown in some API calls, especially in CUDA-enabled builds. This has been fixed.




####################
ROCS 3.8.0
####################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


Shape TK 3.8.0
================================================================================

New Features
--------------------------------------------------------------------------------
* A new method, :ref:`AddShapeGaussians <OEShape_OEShapeQuery_AddShapeGaussians>`,
  has been added that allows adding shape Gaussians to the
  :ref:`OEShapeQuery <OEShape_OEShapeQuery>` based on the intensity of values
  on a grid.

* A new class, :ref:`OEShapeQueryOptions <OEShape_OEShapeQueryOptions>`,
  has been added that allows modifying options that would be
  used in adding Gaussians using the :ref:`AddColorGaussians <OEShape_OEShapeQuery_AddColorGaussians>` 
  and :ref:`AddShapeGaussians <OEShape_OEShapeQuery_AddShapeGaussians>`. Subsequently,
  a new constructor for :ref:`OEShapeQuery<OEShape_OEShapeQuery>`
  has been added that takes the :ref:`OEShapeQueryOptions <OEShape_OEShapeQueryOptions>`
  as an argument.




ROCS 3.7.0
===============

.. program:: checkcff

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

* The utility application :ref:`CheckCff <chapter_checkcff>` has been restructured 
  to provide the same underlying functionality for color assignment as that of the :ref:`Prep<OEShape_OEOverlapPrep_Prep>`
  method from the :ref:`OEOverlapPrep<OEShape_OEOverlapPrep>` class. The
  following new command line parameters have been added.

    * :option:`-removeDups`: Flag if color atoms within a certain distance from each other should be removed.
    * :option:`-minDistance`: Minimum distance between color atoms for them to be treated as duplicates.

* The modified :ref:`CheckCff <chapter_checkcff>` always generates a report file in ``.csv``
  format and :option:`-report` can be used to provide a nondefault name to the report file.

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

* ``--help -chemff`` for the :ref:`CheckCff <chapter_checkcff>` now properly displays
  all of the available options.



Shape TK 3.7.0
================================================================================

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

* A new method, :ref:`AddColorGaussians <OEShape_OEShapeQuery_AddColorGaussians>`,
  has been added that allows adding color Gaussians to the
  :ref:`OEShapeQuery <OEShape_OEShapeQuery>` based on intensity of values
  on a grid.

* A new class, :ref:`OEOverlapPrepOptions <OEShape_OEOverlapPrepOptions>`,
  has been added that allows modifying options that would be
  used during the :ref:`Prep <OEShape_OEOverlapPrep_Prep>`. Subsequently,
  a new constructor for :ref:`OEOverlapPrep<OEShape_OEOverlapPrep>`
  has been added that takes the :ref:`OEOverlapPrepOptions <OEShape_OEOverlapPrepOptions>`
  as an argument.

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

* Color force field names in :ref:`OEColorFFParameter <OEShape_OEColorFFParameter>`
  are now treated as case-insensitive.



ROCS 3.6.2
===============

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

* Command line flags related to the **EON** input generation category have been removed. 
  This is a consequence of new behavior of **EON** which no longer requires pre-alignment 
  of input molecules. In particular, ``-eon_input``, ``-eon_maxconfs``, ``-eon_input_size``, 
  and ``-eon_input_file`` are no longer command line flags of this version of 
  the **ROCS** Application.

* Double-clicking a shape query *.sq* file or selecting
  ``Open with vROCS`` will now start **vROCS** with the query loaded and
  available for editing or use in a run.

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

* Color force field files ``ImplicitMillsDean.cff`` and ``ExplicitMillsDean.cff``
  shipped with ``Applications data`` are now consistent with the internal implementation
  of the corresponding force fields. This update specifically fixes an issue with the
  definition of ``tertiaryAmine``.

* 2D hitlist depictions during a run in **vROCS** have been hidden
  on macOS, due to an incorrect graphical display.

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

* During query editing in **vROCS**, the behavior of right-clicking
  on an atom and ``Create a Color Atom`` has more appropriate restrictions
  and no longer causes a crash.



Shape TK 3.6.2
================================================================================

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

* The following preliminary API classes have been made permanent.

  * :ref:`OEColorFFParameter<OEShape_OEColorFFParameter>`
  * :ref:`OEFlexiOverlapFunc<OEShape_OEFlexiOverlapFunc>`
  * :ref:`OEFlexiOverlapOptions<OEShape_OEFlexiOverlapOptions>`
  * :ref:`OEFlexiOverlapResults<OEShape_OEFlexiOverlapResults>`
  * :ref:`OEFlexiOverlay<OEShape_OEFlexiOverlay>`
  * :ref:`OEFlexiOverlayOptions<OEShape_OEFlexiOverlayOptions>`

* New methods, :ref:`SetAtomStrength<OEShape_OEShapeQuery_SetAtomStrength>`
  and :ref:`GetAtomStrength<OEShape_OEShapeQueryBase_GetAtomStrength>`, have been
  added that allow multiplying the contribution of shape overlap for any atoms,
  without adding an additional atom or Gaussian.




ROCS 3.6.1
===============

Minor bug fixes
--------------------------------------------------------------------------------
* Multiple successive runs of **vROCS** now correctly provide default job names.

Minor internal improvements have been made.



Shape TK 3.6.1
================================================================================

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

* Memory consumption when initiating an
  :ref:`OEColorForceField <OEShape_OEColorForceField>` has been reduced
  by moving instantiation of internal :ref:`OESubSearch <OEChem_OESubSearch>`-based
  `colorer` objects to a lazy instantiation mode.




ROCS 3.6.0
===============

Minor internal improvements have been made.



Shape TK 3.6.0
================================================================================

New features
--------------------------------------------------------------------------------
* :ref:`OEFlexiOverlapFunc <OEShape_OEFlexiOverlapFunc>` and 
  :ref:`OEFlexiOverlay <OEShape_OEFlexiOverlay>` have been updated to 
  allow users to use a 
  Shape Query as the reference system.  This allows
  :ref:`OEFlexiOverlapFunc SetupRef <OEShape_OEFlexiOverlapFunc_SetupRef>` and
  :ref:`OEFlexiOverlay SetupRef <OEShape_OEFlexiOverlay_SetupRef>` to
  accept a Shape Query.

* A new method, :ref:`SetupFlex <OEShape_OEOverlapFuncBase_SetupFlex>`,
  has been added.  This method can be used to set up overlap calculation functions when
  molecules are expected to be flexible and their self overlaps 
  are not fixed to the initial value.

* A new method, :ref:`SortedOverlay <OEShape_OEOverlay_SortedOverlay>`,
  has been added as an alternative to :ref:`Overlay <OEShape_OEOverlay_Overlay>`.
  This method provides a desired number of top hit results instead of all
  of the hits and is especially suitable when working with molecules
  with excessive numbers of conformers.

* Two additional control flags, :ref:`GetRigidOverlay <OEShape_OEFlexiOverlayOptions_GetRigidOverlay>` and
  :ref:`SetRigidOverlay <OEShape_OEFlexiOverlayOptions_SetRigidOverlay>`, have been added to
  the :ref:`OEFlexiOverlayOptions <OEShape_OEFlexiOverlayOptions>` class. 
  These flags indicate if rigid overlay optimization between the fit molecule 
  conformers and the reference system should be performed prior to the flexible 
  optimization.

Major bug fixes
--------------------------------------------------------------------------------
* An issue in :ref:`OEFlexiOverlay <OEShape_OEFlexiOverlay>` 
  that caused a TanimotoCombo value greater than 2.0 when a molecule was 
  flexibly fitted against itself has been fixed.

Minor bug fixes
--------------------------------------------------------------------------------
* The default value for the ``color`` function in 
  :ref:`OEFlexiOverlapOptions <OEShape_OEFlexiOverlapOptions>` during
  :ref:`OEFlexiOverlay <OEShape_OEFlexiOverlay>` has been changed from
  ``none`` to ``exact``.  This ensures that color overlaps are reported
  when flexible optimization is performed with default parameters.

* An issue has been fixed with :ref:`OEFlexiOverlay <OEShape_OEFlexiOverlay>`
  that was causing shape Tanimoto to be occasionally reported as larger than 1.0
  after a flexible optimization.

* The legal range of values for the color score multiplier 
  has been added to the 
  :ref:`OEFlexiOverlapOptions <OEShape_OEFlexiOverlapOptions>` and 
  :ref:`OEOverlayOptions <OEShape_OEOverlayOptions>` option classes.

* :ref:`OEColorFFParameter <OEShape_OEColorFFParameter>` 
  now allows users to select `explicitmillsdeannorings` properly
  as the color force field.

* The acceptable ranges for the number of optimization iteration 
  steps have been defined for 
  :ref:`OEFlexiOverlayOptions <OEShape_OEFlexiOverlayOptions>` and 
  :ref:`OEOverlayOptions <OEShape_OEOverlayOptions>`.

* Newer implementation of Hermite code had limits on lambda
  parameters of the expansion. In rare cases, these were affecting the lambda parameter
  search (Newton optimization stepping outside the limits). Removing the limits fixed the previous problems with
  finding lambda parameters.

.. WIP * Default contour values
  for shape representation have been adjusted for visual representation of large
  proteins.



ROCS 3.5.1
===============

*Fall 2022*

Minor internal improvements have been made.


Shape TK 3.5.1
================

New features
--------------------------------------------------------------------------------
* The following new methods have been added to  
  :ref:`OEOverlayOptions <OEShape_OEOverlayOptions>`
  to improve flexibility in defining parameters:

    * :ref:`SetShapeFuncType <OEShape_OEOverlayOptions_SetShapeFuncType>`
    * :ref:`GetShapeFuncType <OEShape_OEOverlayOptions_GetShapeFuncType>`
    * :ref:`SetColorFuncType <OEShape_OEOverlayOptions_SetColorFuncType>`
    * :ref:`GetColorFuncType <OEShape_OEOverlayOptions_GetColorFuncType>`
    * :ref:`SetShapeOptions <OEShape_OEOverlayOptions_SetShapeOptions>`
    * :ref:`GetShapeOptions <OEShape_OEOverlayOptions_GetShapeOptions>`
    * :ref:`SetColorOptions <OEShape_OEOverlayOptions_SetColorOptions>`
    * :ref:`GetColorOptions <OEShape_OEOverlayOptions_GetColorOptions>`

* A new overload for the method :ref:`CreateGrid <OEShape_OEHermite_CreateGrid>` has been
  added that takes a transform object as an additional argument that
  is applied after the grid is generated.

Major bug fixes
--------------------------------------------------------------------------------
* Default forcefields in :ref:`OEFlexiOverlapOptions <OEShape_OEFlexiOverlapOptions>`
  now ignore electrostatic interactions, as electrostatics appear to have
  negligible effects on optimized overlaid structures.  Ignoring the electrostatic
  interactions also improves efficiency of optimization for the corresponding
  :ref:`OEFlexiOverlapFunc <OEShape_OEFlexiOverlapFunc>`.

* The default for :ref:`OEOverlapFunc <OEShape_OEOverlapFunc>` in
  :ref:`OEFlexiOverlayOptions <OEShape_OEFlexiOverlayOptions>` now consists of
  ``Shape`` only and no ``Color``.  The default ``Shape score`` used
  is :ref:`Overlap <OEShape_OEScoreType_Overlap>`.


Minor bug fixes
--------------------------------------------------------------------------------
* A mismatch between the Hermite grid and the input molecule has been fixed.

* The maximum value on the Hermite resolution parameter has been increased from 30 to 100.


Documentation changes
--------------------------------------------------------------------------------
The following C++ and Python examples have been added to demonstrate how to use
new preliminary APIs:

* Two new C++ and Python examples have been added to the
  :ref:`chapter_flexi_overlay_examples` 
  section that show flexible overlay optimization of the fit molecules
  against a single reference molecule conformer. 
  
* When using
  :ref:`BestOverlay<OEShape_OEFlexiOverlay_BestOverlay>`, only one
  conformer that has the highest Tanimoto-combo similarity to the reference
  molecule is returned. 



ROCS 3.4.3
================================================================================

*Fall 2021*

* Minor internal improvements have been made.


Shape TK 3.4.3
================================================================================

*Fall 2021*

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

* A new method, :ref:`OEMol2Query <OEShape_OEMol2Query>`, has been added that creates an
  :ref:`OEShapeQuery <OEShape_OEShapeQuery>` from an input :ref:`OEMolBase <OEChem_OEMolBase>`.

* A new preliminary API class, :ref:`OEColorFFParameter <OEShape_OEColorFFParameter>`,
  has been added as part of the extended set of :ref:`OEParameter <OESystem_OEParameter>` classes.
  The new parameter class works with predefined color force fields using an 
  :ref:`OEColorForceField <OEShape_OEColorForceField>` object.

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

* :ref:`OESetColorParents <OEShape_OESetColorParents>` now errors out properly if the color atom
  and the parent atoms specified do not have the same parent molecule.






ROCS 3.4.2
================================================================================

*July 2021*

* Minor internal improvements have been made.


Shape TK 3.4.2
================================================================================

*July 2021*

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

* A bug that caused some molecules to get a perfect Shape Tanimoto score of 1.0,
  even though their overlap was not optimal, has been fixed.




ROCS 3.4.1.0
================================================================================

*Fall 2020*

* Minor internal improvements have been made.


Shape TK 3.4.1
================================================================================

*Fall 2020*

New features
--------------------------------------------------------------------------------
* A new function, :ref:`OEIsFastROCSShapeQuery <OEShape_OEIsFastROCSShapeQuery>`, has been added that determines if
  an :ref:`OEShapeQuery <OEShape_OEShapeQuery>` object is compatible with **FastROCS TK**.

Major bug fixes
--------------------------------------------------------------------------------
* An issue that caused performance slowdown in :ref:`OESelfShape <OEShape_OESelfShape>` has been fixed.

* An issue that caused :ref:`OEGridColorFunc <OEShape_OEGridColorFunc>` to give incorrect results when used with
  a custom color force field containing a range value other than 1.0 has been fixed.

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

* The UserColor example has been updated to more robustly check return statuses.
  See :ref:`chapter_shape_examples`.






ROCS 3.4.0
================================================================================

*Spring 2020*

* This version of **ROCS** has been built using **OEToolkits 2020.0**.

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

* Shape queries with the file extension SQ no longer give incorrect shape Tanimoto scores.

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

* ``ScaledColor`` and ``ComboScore`` are no longer available as options for the
  ``-rankby`` parameter.  Accordingly, those quantities are also no longer reported in the output results files. Users are encouraged to use ``ColorTanimoto`` and ``TanimotoCombo`` instead.

* Images in the **RocsReport** documentation have been updated.



.. _rocs_releasenotes_220:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


..  program:: rocs

ROCS 2.2.0
===========

*March 2006*

Enhancements
---------------

*  Added ability to read rotor-offset-compressed OEB files as 
   written from **OMEGA** 2.0 and later.

*  Added new :option:`-tanimoto_cutoff` flag that can be used to
   limit output hits to only those with some minimum shape score. This
   can be used regardless of which score is chosen (-rankby) for ranking
   the hitlist. For example, using

   .. code-block:: bash
  
      -rankby combo -cutoff 1.2 -tanimoto_cutoff 0.6

   any molecule with Shape Tanimoto <= 0.6 will not be
   retained. Additionally, the constraint on combo to be at least 1.2
   implies that scaledcolor must also be > 0.6 so that the sum can be
   greater than 1.2.

*  :option:`-scoreonly` flag to allow scoring of pre-aligned positions. Using 
   this one flag is the equivalent of the following settings:

   ::
   
      -opt false
      -besthits 0
      -maxhits 0
      -scdbase  

*  New :option:`-conflabel` flag to control where conformer indices
   are placed in output files. Previous versions added the conformer
   index at the end of the molecule title following an underscore. The
   new flag has 4 possible values:

   *  ``title`` just like previous behavior, added index
      to end of title
   *  ``sdtag`` Conf idx is placed in SD tag <ConfIndex>
   *  ``both``  combination of previous two places
   *  ``none``  conformer indices are not marked on output.

   .. note::

      ``sdtag`` is only useful if the output file is SDF or OEB.

*  Several new flags have been added to allow more complete control of the 
   different files **ROCS** can output. The added flags include:

*  :option:`-logfile` Instead of writing to stderr, all logging
   information goes into a file provided by this switch can be
   filename or full/relative path

*  :option:`-reportfile` Instead of writing to :file:`PREFIX_n.rpt` where
   PREFIX is provided by the :option:`-prefix` commandline flag, write all
   report information (stats) to the file provided with this flag. Can
   be filename or full/relative path. Note that if more than one query
   molecule is provided, this flag will not work unless the ``-report one`` 
   flag is also provided to put all report info into one report file.

*  :option:`-hitsfile` Instead of writing to :file:`PREFIX_hits_n.sdf`
   (for example) where PREFIX is provided by the :option:`-prefix`
   commandline flag, write all hit structures to the file provided
   with this flag. Can be a filename or full/relative path.  Also, if
   the name provided is actually a molecule file format extension
   (i.e. .sdf, .mol2.gz, .oeb, etc.), **ROCS** will write to stdout using
   the format derived from the file extension. For example if the
   following is used

   .. code-block:: bash

      -hitsfile .sdf

   then ROCS will write all the hits out to stdout in SDF format.
  
   Note that this option will only work for a single molecule
   query. If more than one query is provided along with the
   :option:`-hitsfile` option, **ROCS** will issue an error and stop.

*  In order to facilitate using **ROCS** as part of a larger workflow, the :option:`-dbase`
   flag can now be used to force **ROCS** to read its dbase molecules from stdin.
   If a file extension (i.e. .sdf, .mol2.gz, etc.), is used as the 
   -dbase filename, ROCS will attempt to read dbase molecules from stdin 
   in the format described by that file extension. For example, if the 
   following is used:

   .. code-block:: bash

      -dbase .sdf

   then ROCS will read the dbase molecules from stdin in SDF format.

   Note that this option will only work for a single molecule query. If more
   than one query is provided along with a -dbase flag attempting to read 
   from stdin, **ROCS** will issue an error and stop.

*  Changed the way untitled ref and fit molecules are named so that
   in hits files, they can be distinguished and so that untitled names
   are different than conformer index names.

*  ``-allcolor`` flag has been deprecated and will be removed from 
   a future version of **ROCS**.

*  Added new :option:`-out<checkcff -out>` flag to checkcff to output molecules to an
   OEB file with color atoms attached. This file can be loaded into VIDA
   and the atoms labeled with "Name" to show the location and type of all
   added color atoms.

Bug fixes
------------

*  Added check for untitled reference (query) molecules. If no title is
   found, a title similar to "untitled-ref-N" is applied. This address a bug
   in EON caused by blank titles in **ROCS** queries, resulting in broken SD tags
   in the input to **EON**.

*  Fixed a bug that caused molecules of high-symmetry to be skipped. If a
   molecule's moments of inertia were all equal, it would be skipped. If the
   molecule was the reference, no hits would be found. 

*  Fixed a bug in random starts. 


.. _rocs_releasenotes_230:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: rocs

ROCS 2.3.0
===========

*August 2007*

Enhancements
-------------

*  Use of the color force field is now on by default. With this, the
   default score to rank the hitlist has been changed to ``combo``.
   The following new default flag values:

   ::

      -chemff ImplicitMillsDean
      -optchem
      -rankby combo

*  **ROCS** now has multiple methods of showing job progress. In addition
   to the dots of previous versions, ROCS now has a progress bar by
   default that show percent completion of the dbase file. Note that
   means that when **ROCS** starts, it will count the number of molecules
   in the dbase and then use that value to measure percent
   completion. This also allows log file messages to be tagged to the
   index into the dbase file for each molecule as it is scored.  See
   the description for the new flag :option:`-progress` for info on the
   other options.

*  Since color is now on by default, a new flag :option:`-shapeonly` has
   been added to turn on the shape only features of previous versions for **ROCS**. 
   This is only a convenience flag that just sets the following:

   ::

      -chemff none
      -optchem false
      -rankby tanimoto

*  Since **ROCS** is routinely used to preparation of input files for **EON**,
   a new set of flags have been added that aid in creation of a
   specific **EON** input file, different from the standard **ROCS** hits
   file. Please see the section about describing these options:

   ::

      -eon_input
      -eon_maxconfs
      -eon_input_size
      -eon_input_file

*  Added a new status file (``rocs.pvmlog`` by default), that shows PVM
   master and slave statistics, during PVM runs. The actual filename
   can be modified with the new ``-pvmlog`` switch.

*  Deprecated in the last release, the ``-allcolor`` flag has
   now been removed.



.. _rocs_releasenotes_231:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

ROCS 2.3.1
===========

*August 2007*

Bug fixes
----------

*  Fixed a bug reading .rocsdb files. 

*  Fixed a subtle bug that caused ``-report one`` to only work if
   ``-reportfile`` is also used. Using ``-report one`` will now create
   a single report file named based on the ``-prefix`` given.

*  Removed an annoying but benign warning about the now deprecated
   and removed ``-allcolor`` flag.

*  Fixed a bug where the ``-eon_maxconfs`` flag expected a value
   greater than 1. Now any value greater than zero is valid.

.. _rocs_releasenotes_241:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


ROCS 2.4.1
===========

*May 2009*

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

*  As of this release, the new default score for ranking is the
   TanimotoCombo, the sum of Shape Tanimoto and the new Color
   Tanimoto. Version 1.7 of the Shape Toolkit introduced new color
   scores based on Tanimoto. This version of **ROCS** incorporates all the
   new scores including Color Tanimoto and the resulting Color Tversky
   scores. Additionally all the Tversky scores are now named relative
   to either the Ref(erence) or Fit molecule, instead of the former
   query and dbase labels. This move is designed to standardize the
   names used in **ROCS** and the Shape Toolkit.

*  In order to facilitate all the new scores, the Report file
   columns have been renamed and re-ordered.

*  **ROCS** no longer counts the input file prior to starting the
   calculation. Progress is now based on file size not number of
   molecules processed. This alleviates a problem with very long
   start-up times for extremely large database files.

*  This release adds **ROCS** to the set of applications that now use a
   common script in ``openeye/bin`` to determine the appropriate
   architecture and run the appropriate binary.

*  On Windows, there is now an installer that installs the
   documentation and sets up a command prompt to facilitate running
   the ROCS command line.

Bug Fixes
-----------

*  Fixed a bug that caused a crash when trying to write an empty hitlist.

.. _rocs_releasenotes_242:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


ROCS 2.4.2
===========

*September 2009*

Bug Fixes
----------

*  Fixed a bug that caused a crash on Windows when trying to load an 
   external CFF file. (Case 3413)

*  Fixed the additional utilities so that they only require a "rocs" license and 
   not an "oechem" license. (Cases 3350, 3435, 3440)

*  Removed some extraneous command line arguments from "checkcff" (Case 3392)


.. _rocs_releasenotes_300:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


ROCS 3.0.0
===========

*November 2009*

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

*  **ROCS** now comes with a new graphical application, **vROCS**, for setting up and testing queries. There are 
   new sections in the manual that describe **vROCS** and new tutorials that walk you through using
   it. Please note that while **vROCS** makes creating complex queries much more manageable, it is **not** 
   required. The *rocs* command line app will continue to be the core of **ROCS**. **vROCS** is not available on
   AIX or Solaris

*  **vROCS** saves queries as Shape Query (.sq) files. Running **ROCS** from the command line will not accept Shape 
   Query files as well as all the previously supported file formats. 

*  **ROCS** now supports MPI as well as PVM for distributed job management. This new feature is built on top
   of Open MPI and doesn't require any additional installs on cluster machines.

Bug Fixes
----------

*  Fixed a bug that could cause a crash when piping molecules into **ROCS** via stdin.

*  Updated documentation to show that XYZ (.xyz) files are also suitable as **ROCS** queries.

*  Fixed a bug when using .list files, the progress bar was not reset.


.. _rocs_releasenotes_310:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


ROCS 3.1.0
===========

*November 2010*

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

*  Added new platforms: Ubuntu 10 x64 and Sled 11 x64.

*  **ROCS** now works with named pipes created using mkfifo on non-Windows platforms.

*  The hlmerge application was not opening lists unless the file had an extension of ".list".  Now hlmerge will attempt to open any non-molecule file as a list.

Bug Fixes
----------
*  Fixed a bug related to saving screenshots on Linux.

*  Fixed a bug related to adding color atoms to a query.

*  Fixed a bug related to the contour slider losing focus.

*  Fixed a bug related to two contours overlapped by default causing display artifacts. 

*  Removed spurious warnings for "-auto" and "-rqedbmols".

*  Fixed a bug in chunker that was causing the output file to be empty.

*  Fixed a bug where the "-reportfile" option was being ignored.

*  Fixed a bug where the "-maxconfs" option was being ignored.

*  Fixed a bug in the coloring of aldehydes.

*  Fixed a bug where multiple processor jobs would print "Slave started on host Host".  The message now prints the proper hostname for the process.

*  Fixed a bug where using "-stats best" was causing an empty report file.

.. _rocs_releasenotes_311:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


ROCS 3.1.1
===========

*February 2011*

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

*  Added new platform: RedHat 6 x64

Bug Fixes
----------
*  Fixed a bug running user-provided command line options in **vROCS**.

*  Fixed a bug of reporting erroneous error messages.

*  Fixed a problem concerning DLL dependencies on Windows.


.. _rocs_releasenotes_312:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


ROCS 3.1.2
===========

*June 2011*

Bug Fixes
----------
*  Fixed a bug where **EON** input files were not generated correctly when using multiple queries.
*  Fixed a bug where the query was written to the **EON** input file too many times.
*  Fixed a bug concerning validation runs failing in **vROCS**.
*  Fixed a bug where application could crash on exit when using the ``-maxhits`` option
*  Fixed a bug concerning output of color atoms to non-OEB format.  Now precalculated color will only pass through if the output format is OEB.
*  Now **ROCS** will not write EON_input if the **ROCS** input is a shape query.  Only real molecules can be used as **ROCS** input when writing EON_input.

.. _rocs_releasenotes_320:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


ROCS 3.2.0
===========

*September 2013*

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

*  The default hitlist format has been changed from sdf to oeb for increased functionality and decreased filesize.  The output format is adjustable with the `-oformat` parameter.

*  The `-subrocs` option has been added.  The `-subrocs` starting points include 4 positions at every heavy atom in addition to the default inertial alignments.

*  The rocs_report application has been added for making pdf reports from a hitlist. 

*  Now SD tags are prefixed with `ROCS_`.  The tags are now optional with the `sdTags` parameter.

*  **vROCS** now supports the manual merging of selected color atoms, to create a 
   new color atom at their centroid.

*  An improved molecule sketcher in **vROCS** now highlights unspecified 
   stereochemistry in atoms and bonds when they occur in query structures, 
   and requires the user to correct any unspecified stereochemistry before 
   proceeding with a query.

*  Numerous minor enhancements have been made to the user interface.
  

Bug Fixes
---------

*  Multiconformer molecules from **OMEGA** could be split into multiple molecule when the OMEGA output was written to .sdf instead of .oeb and had invertible stereocenters.  
   Now ROCS will keep these .sdf multiconformer molecules together.

*  Color atoms are now removed from **ROCS** hitlists for all output formats.  Color atoms can be added to hitlists using the `checkcff` utility.

*  Fixing bug for when eon_input_size is larger than -best, now it increase -best when needed.

*  Now when **ROCS** hits are being streamed with -besthits 0, then eon_input molecules will be as well.

*  Fixed a bug where sometimes .sdf files would get warts applied twice.

*  Cleaned up missing entries or zeroes for Subtan and the conf index in the report file.

*  Fixed a bug where report file entries could be duplicated with the `-scoreonly` flag.

*  Fixed a bug where `-report one` could cause problems writing status files.

*  Failure cases have been cleaned up.  Incorrect and incompatible command line flags will cause ROCS to exit quickly and cleanly.

*  Fixed a bug in **vROCS** in which files saved with a filename ending in 
   ".sq.gz" would have an additional ".sq" appended to the end of the name.

*  Fixed a problem where **ROCS** database files (.rocsdb) were not being read
   properly by vROCS.

Other changes
---------------------------------------------------------------------------------

* PVM (parallel virtual machine) is no longer supported. OpenMPI version 1.6 is supported
  on all platforms.  The `-mpi_np` and `-mpi_hostfile` flags are now used to run `ROCS` in MPI mode.
  These new flags replace the `oempirun` script.

* This will be the last release to support SuSe 10.

.. _rocs_releasenotes_321:
.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


ROCS 3.2.1
===========

*September 2015*

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

*  The default **ROCS** output format is now gzipped OEBinary, ``oeb.gz``, in order to save disk space.

*  **ROCS** will treat database list file entries that do not include a path
   as though they are relative to
   the list file location, rather than relative to the working directory.
   The *hlmerge* application will do the same with entries in lists of hit lists.

Bug Fixes
---------

*  **ROCS** will no longer crash if an empty shape query is given.

*  **ROCS** now writes a warning and skips any database molecule that have either missing xyz coordinates
   or are clearly 2 dimensional (z coordinates are all zero and dimension set to 2).

*  **ROCS** now issues a warning and halts if `-subrocs` is true and the query is a grid. Grids are not
   supported for SubROCS.

*  **ROCS** now issues a warning and halts if a query grid contains negative values. Grids with negative
   values are not supported in **ROCS**.

*  Rocs_report will halt if it does not detect a query. Previously, an incorrect query mol was
   shown in the report when
   there was no query in the **ROCS** output file and `-refmol` was not specified.

*  **ROCS** now writes files ending in ``_ref.grd``, ``_ref.sq``, ``_errors.sdf``, ``_eon_input.oeb.gz``
   to the directory defined when the `-outputdir` parameter is specified,
   along with all the other output files.

*  ROCS now works with gzipped grid queries.

*  ROCS now issues a warning to clarify that the `-optchem` parameter is ignored when `-opt` is false
   and `-scoreonly` is false.

*  Setting the **ROCS** parameter `-opt` to false now turns off optimization directly. Previously,
   the parameter `-scoreonly` did this when set to true.

*  The **ROCS** parameter `-eon_input_size` can now be set to 0, to indicate that no hit list is to
   be maintained and results are to be streamed, as previous documentation had indicated.
   Setting the parameter to 0 is required if `-besthits` and `-maxhits` are both 0.

*  **ROCS** will terminate if a color force field specified by `-chemff` is not identical to that defined
   in a shape query file.

*  The **ROCS** parameter `-tanimoto_cutoff` is now restricted to the range 0.0 to 1.0.

*  Subtan SD tags are removed if `-subtan` is false.

*  The *rocs_report* application parameter `-maxpages` now properly counts the title page.

*  The input file to the *checkcff* and *makerocsdb* applications is now checked to ensure it is 3-dimensional.

.. note::
   
   On Windows it is advisable to use the 64-bit ROCS executable
   during memory-intensive tasks
   (for example, combining `-mcquery` with `-subrocs`)
   to avoid a crash due to insufficient memory.


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _rocs_releasenotes_322:

ROCS 3.2.2
===========

*June 2017*

Platform Support
----------------

*  Support has been added for Ubuntu 16, OSX 10.10, OSX 10.11, and macOS Sierra.
*  OSX 10.7, OSX 10.8, OSX 10.9, and Redhat 5 x86 are no longer supported.
*  This is the last release to support Redhat 5 x64.
*  SUSE Linux is no longer supported.

Bug Fixes
---------

*  **ROCS** will no longer crash if a query contains only hydrogens or dummy atoms. If the
   query file contains multiple queries, **ROCS** will skip the bad structure and continue
   the search; if the query file contains only a bad structure, **ROCS** will halt the search.
*  A bug that caused **ROCS** to ignore the ``-eon_input_file`` command line flag has been fixed.
*  A bug that caused ROCS to ignore the ``-shapeonly`` option if a shape query (.sq) was
   used has been fixed. **ROCS** now issues a warning and terminates the search.
*  **ROCS** will no longer terminate a search if a molecule stream is used as the database file.
*  **ROCS** will no longer terminate a search if a named pipe is used as the database file.
*  A bug that caused **CHUNKER** to fail when splitting large conformer databases has
   been fixed. **CHUNKER** will now split large databases into the sizes requested by the user.
*  **CHUNKER** will no longer accept negative numbers for ``-chunksize`` and ``-nchunks`` command line options.
*  A bug that caused **CHUNKER** to crash if the input file was empty or did not exist has been fixed.
*  Query information reported by **ROCS** has been enhanced. For example, for a multi-conformer
   query, **ROCS** will output conformer information as follows:  Query (#1): acetsali conformer 1 of 15,
   Query (#2): acetsali conformer 2 of 15 ...  and so on.
*  **CHECKCFF** will no longer accept non-OEB format as output file format.
*  **HLMERGE** will no longer accept negative numbers for ``-besthits`` command line option.
*  An issue causing subsequent runs in **vROCS** to have odd naming has been fixed.
*  Obsolete *Rank By* run options in **vROCS** have been removed.



ROCS 3.3.0
================================================================================

*November 2018*

* This version of **ROCS** has been built using **OEToolkits 2018.Oct**. The previous 
  version was built using **OEToolkits 2016.Oct**.

* The engine behind **ROCS**, **Shape TK**, has gone through a major re-engineering 
  in the **OpenEye Toolkits v2017.Oct** release. With the introduction of 
  **Shape TK 2.0**, overlay optimization in ROCS is now approximately 10% faster 
  than in the previous release.

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

* An issue that caused **ROCS** to crash when a shape query from
  **Shape TK** was used as a **ROCS** query has been fixed.

* The ``Ligand Model Builder`` in **vROCS** now properly handles
  queries that contain no heavy atoms.

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

* The ``Documentation`` sub-menu of **vROCS** now correctly points to the 
  online documentation.

* Negative values and values larger than 1.0 for color Tanimoto are no longer reported.

* The Rank by drop-down menu of the Options tab in **vROCS** validation has been modified 
  to use the same score names as those used in the **ROCS** application.


ROCS 3.3.1
================================================================================

*May 2019*

* This version of **ROCS** has been built using **OEToolkits 2019.Apr**. The previous
  version was built using **OEToolkits 2018.Oct**.

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

Users can now specify **oez** files as input to **ROCS**.

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

* **ROCS** now properly handles empty query objects and queries consisting of
  only color atoms.

* **ROCS** now properly handles molecules without coordinates.

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

* ``ROCS_ShapeQuery`` field now contains conformer ID when using ``-mcquery true``.

* **ROCS** no longer throws warning when used with a shape query that contains
  no molecule.


ROCS 3.3.2
================================================================================

*Nov 2019*

* This version of **ROCS** has been built using **OEToolkits 2019.Oct**. The previous
  version was built using **OEToolkits 2019.Apr**.

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

* **vROCS** now properly accepts a custom force field file.

* An issue that caused **ROCS** to fail to properly reporting molecule read failures when running with
  ``-mpi_np`` has been fixed.

* An issue with misaligned molecules when using a multi-conformer query has been fixed in **ROCS**.

* **ROCS** now appends a conformation number to the  molecule even for single conformer molecules
  in an output molecules.

* Hardset limitation of 100,000 decoys for **vROCS** validation runs have been removed.

* The **ROCS** output file for **EON** now contains proper title numbering (wart).

* The ``Custom`` option for the ``-pagesize`` parameter in **RocsReport** has been removed.



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. |COMPCHEM| replace:: *Computational Chemistry*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*

.. _rocs_pubs:

==================================
Selected ROCS Publications
==================================

Numerous journal articles have been published about ROCS through the years. Included here are some of the more impactful
papers. They are arranged in chronological order, beginning with the seminal work on Gaussians by Grant, Gallardo, and Pickup.

.. _paper1:

*  Grant, J.A.; Gallardo, M.A.; Pickup, B.T. **A Fast Method of Molecular Shape Comparison. A Simple Application of a Gaussian
   Description of Molecular Shape.** *J. Comput. Chem.* **1996**, *17* (14), 1653–1666. DOI: 10.1002/(sici)1096-987x(19961115)17:14<1653::aid-jcc7>3.0.co;2-k

.. _paper2:

*  Nicholls, A.; MacCuish, N.E.; MacCuish, J.D. **Variable Selection and Model Validation of 2D and 3D Molecular Descriptors.**
   *J. Comput.-Aided Mol. Des.*  **2004**, *18* (7), 451–474.
   DOI: 10.1007/s10822-004-5202-8

.. _paper3:

*  Rush, T.S.; Grant, J.A.; Mosyak, L.; Nicholls, A. **A Shape-Based 3D Scaffold Hopping Method and Its Application to
   a Bacterial Protein–Protein Interaction.** *J. Med. Chem.* **2005**, *48* (5), 1489–1495. DOI: 10.1021/jm040163o

.. _paper4:

*  Haigh, J.A.; Pickup, B.T.; Grant, J.A.; Nicholls, A. **Small Molecule Shape-Fingerprints.** *J. Chem. Inf. Model.*
   **2005**, *45* (3), 673-684. DOI: 10.1021/ci049651v

.. _paper5:

*  Chen, H.; Lyne, P.D.; Giordanetto, F.; Lovell, T.; Li, J. **On Evaluating Molecular-Docking Methods for Pose Prediction
   and Enrichment Factors.** *J. Chem. Inf. Model.* **2006**, *46* (1), 401–415. DOI: 10.1021/ci0503255

.. _paper6:

*  Muchmore, S.W.; Souers, A.J.; Akritopoulou-Zanze, I. **The Use of Three-Dimensional Shape and Electrostatic Similarity Searching
   in the Identification of a Melanin-Concentrating Hormone Receptor 1 Antagonist.** *Chem. Biol. Drug Des.* **2006**,
   *67* (2), 174–176. DOI: 10.1111/j.1747-0285.2006.00341.x

.. _paper7:

*  Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. **Comparison of Shape-Matching and Docking as Virtual Screening Tools.**
   *J. Med. Chem.* **2007**, *50* (1), 74–82. DOI: 10.1021/jm0603365

.. _paper8:

*  McGaughey, G.B.; Sheridan, R.P.; Bayly, C.I.; Culberson, J.C.; Kreatsoulas, C.; Lindsley, S.; Maiorov, V.; Truchon, J.-F.; Cornell, W.D.
   **Comparison of Topological, Shape, and Docking Methods in Virtual Screening.** *J. Chem. Inf. Model.* **2007**, *47* (4), 1504–1519.
   DOI: 10.1021/ci700052x

.. _paper9:

*  Bostr |dotdoto| m, J.; Berggren, K., Elebring, T.; Greasley, P.J.; Wilstermann, M.
   **Scaffold Hopping, Synthesis and Structure–Activity Relationships of 5,6-diaryl-pyrazine-2-amide Derivatives: A Novel Series of CB1 Receptor Antagonists.**
   *Bioorg. Med. Chem.* **2007**, *15* (12), 4077–4084. DOI: 10.1016/j.bmc.2007.03.075

.. _paper10:

*  Sutherland, J.J.; Nandigam, R.K.; Erickson, J.A.; Vieth, M. **Lessons in Molecular Recognition. 2. Assessing and Improving Cross-Docking Accuracy.**
   *J. Chem. Inf. Model.* **2007**, *47* (6), 2293–2302. DOI: 10.1021/ci700253h

.. _paper11:

*  Freitas, R.F.; Oprea, T.I.; Montanari, C.A. **2D QSAR and Similarity Studies on Cruzain Inhibitors Aimed at Improving
   Selectivity over cathepsin L.** *Bioorg. Med. Chem.* **2008**, *16* (2), 838–853. DOI: 10.1016/j.bmc.2007.10.048

.. _paper12:

*  Sheridan, R.P.; McGaughey, G.B.; Cornell, W.D. **Multiple Protein Structures and Multiple Ligands: Effects on the Apparent
   Goodness of Virtual Screening Results.** *J. Comput.-Aided Mol. Des.* **2008**, *22*, 257–265. DOI: 10.1007/s10822-008-9168-9

.. _paper13:

*  Venhorst, J.; Núñez, S.; Terpstra, J.W.; Kruse, C.G. **Assessment of Scaffold Hopping Efficiency by Use of Molecular Interaction
   Fingerprints.** *J. Med. Chem.* **2008**, *51* (11), 3222–3229. DOI: 10.1021/jm8001058

.. _paper14:

*  Nandigam, R.K.; Evans, D.A.; Erickson, J.A.; Kim, S.; Sutherland, J.J. **Predicting the Accuracy of Ligand Overlay Methods with Random Forest Models.**
   *J. Chem. Inf. Model.* **2008**, *48* (12), 2386–2394. DOI: 10.1021/ci800216f

.. _paper15:

*  Sheridan, R.P. **Alternative Global Goodness Metrics and Sensitivity Analysis: Heuristics to Check the Robustness of
   Conclusions from Studies Comparing Virtual Screening Methods.** *J. Chem. Inf. Model.* **2008**, *48* (2), 426–433. DOI: 10.1021/ci700380x

.. _paper16:

*  Lee, H.S.; Choi, J.; Kufareva, I.; Abagyan, R.; Filikov, A.; Yang, Y.; Yoon, S. **Optimization of High Throughput Virtual
   Screening by Combining Shape-Matching and Docking Methods.** *J. Chem. Inf. Model.* **2008**, *48* (3), 489–497. DOI: 10.1021/ci700376c

.. _paper17:

*  P |accente| rez-Nueno, V.I.; Ritchie, D.W.; Rabal, O.; Pascual, R.; Borrell, J.I.; Teixidó, J. **Comparison of Ligand-Based
   and Receptor-Based Virtual Screening of HIV Entry Inhibitors for the CXCR4 and CCR5 Receptors Using 3D Ligand Shape Matching
   and Ligand-Receptor Docking**, *J. Chem. Inf. Model.* **2008**, *48* (3), 509–533. DOI: 10.1021/ci700415g

.. _paper18:

*  Moffat, K.; Gillet, V.J.; Whittle, M.; Bravi, G.; Leach, A.R. **A Comparison of Field-Based Similarity Searching Methods:
   CatShape, FBSS, and ROCS.** *J. Chem. Inf. Model.* **2008**, *48* (4), 719–729. DOI: 10.1021/ci700130j

.. _paper19:

*  Muchmore, S.W.; Debe, D.A.; Metz, J.T.; Brown, S.P.; Martin, Y.C.; Hajduk, P.J. **Application of Belief Theory to Similarity
   Data Fusion for Use in Analog Searching and Lead Hopping.** *J. Chem. Inf. Model.* **2008**, *48* (5), 941–948. DOI: 10.1021/ci7004498

.. _paper20:

*  Naylor, E.; Arredouani, A.; Vasudevan, S.R.; et al.
   **Identification of a Chemical Probe for NAADP by Virtual Screening.** *Nat. Chem. Biol.*
   **2009**, *5*, 220–226. DOI: 10.1038/nchembio.150

.. _paper21:

*  Oyarzabal, J.; Howe, T.; Alcazar, J.; Andres, J.I.; Alvarez, R.M.; Dautzenberg, F.; Iturrino, L.; Martınez, S.; Van der Linden, I.
   **Novel Approach for Chemotype Hopping Based on Annotated Databases of Chemically Feasible Fragments and a Prospective Case
   Study: New Melanin Concentrating Hormone Antagonists.** *J. Med. Chem.* **2009**, *52* (7), 2076–2089. DOI: 10.1021/jm8016199

.. _paper22:

*  Tresadern, G.; Bemporad, D.; Howe, T. **A Comparison of Ligand Based Virtual Screening Methods and Application to Corticotropin
   Releasing Factor 1 Receptor.** *J. Mol. Graphics Modell.* **2009**, *27* (8), 860–870. DOI: 10.1016/j.jmgm.2009.01.003

.. _paper23:

*  Tuccinardi, T.; Ortors, G.; Santos, M.A.; Marques, S.M.; Nuti, E.; Rossello, A.; Martinelli, A. **Multitemplate Alignment
   Method for the Development of a Reliable 3D-QSAR Model for the Analysis of MMP3 Inhibitors.** *J. Chem. Inf. Model.*
   **2009**, *49* (7), 1715–1724. DOI: 10.1021/ci900118v

.. _paper24:

*  Nicholls, A.; McGaughey, G.B.; Sheridan, R.P.; Good, A.C.; Warren, G.; Mathieu, M.; Muchmore, S.W.; Brown, S.P.; Grant, J.A.;
   Haigh, J.A.; Nevins, N.; Jain, A.N.; Kelley, B. **Molecular Shape and Medicinal Chemistry: A Perspective.** *J. Med. Chem.*
   **2010**, *53* (10), 3862–3886. DOI: 10.1021/jm900818s

.. _paper25:

*  Krüger, D.M.; Evers, A. **Comparison of Structure- and Ligand-Based Virtual Screening Protocols Considering Hitlist
   Complementarity and Enrichment Factors.** *ChemMedChem* **2010**, *5* (1), 148–158. DOI: 10.1002/cmdc.200900314

.. _paper26:

*  Swann, S.L.; Brown, S.P.; Muchmore, S.W.; Patel, H.; Merta, P.; Locklear, J.; Hajduk, P.J. **A Unified Probabilistic
   Framework for Structure- and Ligand-Based Virtual Screening.** *J. Med. Chem.* **2011**, *54* (5), 1223–1232. DOI: 10.1021/jm1013677

.. _paper27:

*  Wollenhaupt, J.; Metz, A.; Barthel, T.; Lima, G.M.A.; Heine, A.; Mueller, U.; Klebe, G.; Weiss, M.S. **F2X-Universal
   and F2X-Entry: Structurally Diverse Compound Libraries for Crystallographic Fragment Screening.** *Structure* **2020**, *28* (6),
   694–706.e5. DOI: 10.1016/j.str.2020.04.019

.. _paper28:

*  Taylor, A.I.P.; Xu, Y.; Wilkinson, M.; Chakraborty, P.; Brinkworth, A.; Willis, L.F.; Zhuravleva, A.; Ranson, N.A.; Foster, R.;
   Radford, S.E. **Kinetic Steering of Amyloid Formation and Polymorphism by Canagliflozin, a Type-2 Diabetes Drug.**
   *J. Am. Chem. Soc.* **2025**, *147* (14), 11859–11878. DOI: 10.1021/jacs.4c16743

.. _paper29:

*  Rossen, L.; Sirockin, F.; Schneider, N.; Grisoni, F. **Scaffold Hopping with Generative Reinforcement Learning.**
   *J. Chem. Inf. Model.* **2025**, *65* (13), 6513–6525. DOI: 10.1021/acs.jcim.5c00029


.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _rocs_citation:

************
Citation
************

.. note:: To cite ROCS please use the following:

    ROCS |rocs_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking as Virtual Screening Tools.
*J. Med. Chem.* **2007**, *50* (1), 74–82. DOI: 10.1021/jm0603365



.. SiteHopper documentation master file
.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



#################################
SiteHopper |sitehopper_version|
#################################

.. toctree::
   :maxdepth: 3

   introduction
   sitehopper_search/sitehopper_search
   sitehopper_build/sitehopper_build
   releasenotes/index
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt





.. _sitehopper_introduction:

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


************
Introduction
************

==============
Overview
==============
The **SiteHopper** application is used to compare binding sites between proteins.

==============
Applications
==============

The **SiteHopper** distribution comprises 2 main applications:

   :ref:`sitehopper_build <chapter_sitehopper_build>`

   The :ref:`sitehopper_build <chapter_sitehopper_build>` program is used to
   convert a set of OEDesignUnit (`*.oedu`) files to a database that can be
   searched with the :ref:`sitehopper_search <chapter_sitehopper_search>`
   program.

   :ref:`sitehopper_search <chapter_sitehopper_search>`

   The :ref:`sitehopper_search <chapter_sitehopper_search>` program is used to
   search a database of OEDesignUnits for binding sites similar to a query OEDesignUnit.


.. _chapter_sitehopper_search:

*********************************
SiteHopper Search
*********************************

   .. toctree::
      :maxdepth: 2

      sitehopper_search_overview
      sitehopper_search_gpu
      sitehopper_search_example
      sitehopper_search_help
      sitehopper_search_req_params
      sitehopper_search_opt_params



.. _sitehopper_search_overview:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: sitehopper_search

======================
Overview
======================

:ref:`sitehopper_search <chapter_sitehopper_search>` is used to search a
database of OEDesignUnits similar to a query OEDesignUnit.

.. note::

  To use GPU prescreen, an NVIDIA GPU is required to run :ref:`sitehopper_search <chapter_sitehopper_search>`.
  See :ref:`GPU Prerequisites <sitehopper_search_gpu>` for details.
  If not GPU is available, search will revert to CPU only search.  

Basic Search Process
====================

Search consists of several phases.

   #. **GPU prescreen**: (assuming a compatible GPU is available and :option:`-use_gpu` is `true`).
      Data is loaded into memory and then searched, keeping the top 5000 hits to send on
      to CPU Search.
   #. **CPU Search**:
      Use :option:`-ncpu` CPU threads to search. If GPU prescreen, this searches the
      5000 results from step 1, otherwise it will search the entire database.
   #. **Hitlist processing**:
      Hits are extracted from the database, transformed into their final orientation and
      if :option:`-normalize_and_rescore` is used, that will happen in this step.
   #. **Writing results files**

Output from sitehopper_search
=============================

**sitehopper_search** will create several files:

   #. The `.csv` file contains scores from the top hits in comma-separated format.

   #. The `.oedu` file holds the OEDesignUnits for the hits, as well as a surface
      representation of the binding site.  The protein in each OEDesignUnit is tagged
      with Patch Score, Patch Shape Score, and Patch Color Score and Sequence
      Similarity. These values can be found in the Proteins spreadsheet window in
      VIDA.

   #. The `.log` file contains any warnings or messages from the search, as well
      as a second copy of the scores.

   #. The `.param` contains all the parameters used to run search and can be used to
      re-run the identical search using the :option:`-param` flag.

Scoring in sitehopper_search
============================

**sitehopper_search** orders hits according Patch Score. Instead of calculating
a Color Tanimoto from 0-1, **sitehopper_search** calculates a color score from
0-3, by multiplying Color Tanimoto by 3. This value is called Patch Color Score.
The shape tanimoto is calculated the same as in ShapeTK, and called Patch Shape
Score. The resulting Patch Score in **sitehopper_search** is equal to the sum of
the Patch Color and Patch Shape scores, analogous to how the Tanimoto combo
score is the sum of Tanimoto shape and color. Patch Score ranges from 0-4,
rather than 0-2, with 4.0 being perfect overlap, and 0.0 being no overlap. The
shape and color components are output alongside the combo score in the log file,
and can also be viewed in the spreadsheet window under the protein tab in VIDA.

Binding site surface visualization
==================================

A surface representation of the binding site is included as part of the output
design units. An example is shown below:

.. _sitehopper_search_binding_site_viz:

.. figure:: /_images/sitehopper_search_binding_site_viz_1UYG.png
   :align: center
   :width: 400

   **1UYG with binding site surface visualization**

The surface represents residues that are close enough to interact with the
ligand. The surface is comprised of four colors: white, yellow, red and blue.
White corresponds to non-polar residues, yellow to polar residues, red to acidic
residues, and blue to basic residues.

Pre-Built SiteHopper Database
====================================

Included in the SiteHopper product is a large database which can be searched
using sitehopper_search. This database is available for `download
<http://www.eyesopen.com/db-downloads>`_ in a platform-independent format.


.. _sitehopper_search_gpu:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: sitehopper_search

======================
GPU Prerequisites
======================

The following is required in order to use GPU-accelerated OpenEye toolkits and applications:

.. _section_supported_gpu_plats:

Supported Platforms
====================

CUDA-enabled OpenEye software is only available on supported Linux platforms.
For supported Linux platforms see above and/or the `Platform Support Page <https://www.eyesopen.com/supported-platforms>`_

.. _section_supported_gpus:

Supported GPUs
===============

An NVIDIA `Tesla <http://www.nvidia.com/object/tesla-supercomputing-solutions.html>`_,
`Quadro <http://www.nvidia.com/object/workstation-solutions.html>`_, or
`GeForce <http://www.nvidia.com/object/geforce_family.html>`_ GPU with a **compute capability of 3.5**
or higher is required on your system. For a comprehensive table of which GPUs fall into which compute capability
category please refer to the `CUDA <https://en.wikipedia.org/wiki/CUDA>`_ wikipedia page.

.. _section_supported_gpus_drivers:

NVIDIA Drivers
===============

* **Minimum NVIDIA Driver version: 450.x**.

* CUDA is **not** required to be installed.


.. _sitehopper_search_example:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: sitehopper_search

======================
Example Commands
======================

The simplest way to run **sitehopper_search** is by passing in a query DesignUnit and a database.

.. code-block:: bash

   prompt> sitehopper_search -query 4I0D_A__DU__1B7_A-504.oedu -db SiteHopper.shdb -out hits.oedu

Here, **sitehopper_search** will search through SiteHopper.db for protein with
similar binding sites to 4I0D_A__DU__1B7_A-504.oedu. **sitehopper_search** will
write out the top 200 most similar proteins in oedu format to hits.oedu.

If you want to control the number of results, you may do so with the :option:`-max_hits` parameter.

.. code-block:: bash

   prompt> sitehopper_search -query 4I0D_A__DU__1B7_A-504.oedu -db SiteHopper.shdb -out hits.oedu -max_hits 100

The above command will reduce the number of hits written out from 200 to 100.

Another commonly used option is :option:`-normalize_and_rescore`.

.. code-block:: bash

   prompt> sitehopper_search -query 4I0D_A__DU__1B7_A-504.oedu -db SiteHopper.shdb -out hits.oedu -max_hits 100 -normalize_and_rescore true

This will normalize the sitehopper scores of the hits by the difference in the
size of the binding sites of the query, in this case 4I0D_A__DU__1B7_A-504.oedu,
and the size of the hit binding site.



.. _sitehopper_search_help:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: sitehopper_search

======================
Command Line Help
======================

A description of the commandline interface can be obtained by executing **sitehopper_search**
with the `--help` option.

.. code-block:: bash

   prompt> sitehopper_search --help

will generate the following output:

::

   Help functions:
     sitehopper_search --help simple      : Get a list of simple parameters
     sitehopper_search --help all         : Get a complete list of parameters
     sitehopper_search --help defaults    : List the defaults for all parameters
     sitehopper_search --help <parameter> : Get detailed help on a parameter



.. _sitehopper_search_req_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: sitehopper_search

======================
Required Parameters
======================

.. option:: -query <filename>

   File containing an OEDesignUnit to query against an input database.

   File format for :option:`-query` must be .oedu

   [Aliases=**-q**]

.. option:: -database <filename>

   Database of OEDesignUnits to search against. Generated by **sitehopper_build**.

   File format for :option:`-database` must be .shdb

   [Aliases=**-db**]


.. _sitehopper_search_opt_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: sitehopper_search

=======================
Optional Parameters
=======================

Input/Output
=============

.. option:: -out <filename>

   Option to specify the output file to write hits in oedu format.

   [Default=sitehopper_hits.oedu]

SiteHopper Search Options
=========================

.. option:: -max_hits <value>

   Option to specify the maximum number of hits to write out. Note that if fewer
   than this value are found, all hits will be written out

   [Default=200]

.. option:: -normalize_and_rescore <bool>

   Option to normalize the sitehopper score of hits by the difference in binding
   site size between query and hit.

   [Default=false]

.. option:: -cutoff <float>

   Minimum PatchScore to retain in the hit list. 

   [Default=0.0]

.. option:: -sequence_cutoff <float>

   Only keeps hits that have a protein sequence similarity to the query that is
   less than this value. This is useful to remove obvious results.

   [Default=100.0]

.. option:: -ncpu <value>

   Number of CPU threads to use for the search. Setting this to zero implies use all available. 
   Search requires 1GB available RAM per thread, so this value may be reduced at runtime.

   [Default=0]

.. option:: -use_gpu <bool>

   Use NVIDIA GPU as a pre-screen search. This option is only available on Linux
   platforms with a compatible NVIDIA GPU.

   [Default=true]

Logging
=======

.. option:: -log <logfile>

   The argument for this flag specifies the name of
   the log file. This overrides any specified prefix.

   [Default=sitehopper_search_output.log]

.. option:: -param <paramfile>

   The argument for this flag specifies the name of
   the settings file. This overrides any specified prefix.

   [Default=sitehopper_search_settings.param]

   [Aliases=**-settings**]

.. option:: -prefix <prefix>

   Prefix used to name output files, default is blank

.. option:: -verbose

   Triggers copious logging output

.. _chapter_sitehopper_build:

*********************************
SiteHopper build
*********************************

.. toctree::
   :maxdepth: 2

   sitehopper_build_overview
   sitehopper_build_example
   sitehopper_build_help
   sitehopper_build_req_params
   sitehopper_build_opt_params


.. _sitehopper_build_overview:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: sitehopper_build

======================
Overview
======================

:ref:`sitehopper_build <chapter_sitehopper_build>` is used to generate a
database of proteins to be searched with **sitehopper_search**


.. _sitehopper_build_example:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: sitehopper_build

======================
Example Commands
======================

To run **sitehopper_build**, pass in a path to a directory containing 1 or more OEDesignUnit files
(.oedu).

.. code-block:: bash

   prompt> sitehopper_build -dir path_to_directory -db SiteHopper.shdb

Here, **sitehopper_build** will create a database file, SiteHopper.shdb, which can be searched using **sitehopper_search**



.. _sitehopper_build_help:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: sitehopper_build

======================
Command Line Help
======================

A description of the commandline interface can be obtained by executing **sitehopper_build**
with the `--help` option.

.. code-block:: bash

   prompt> sitehopper_build --help

will generate the following output:

::

   Help functions:
     sitehopper_build --help simple      : Get a list of simple parameters
     sitehopper_build --help all         : Get a complete list of parameters
     sitehopper_build --help defaults    : List the defaults for all parameters
     sitehopper_build --help <parameter> : Get detailed help on a parameter



.. _sitehopper_build_req_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: sitehopper_build

======================
Required Parameters
======================

.. option:: -dir <path>

   path to a directory containing one or more design units

.. option:: -dbase <filename>

   Database of SiteHopper patches and OEDesignUnits to be generated.
   File extension for :option:`-dbase` must be .shdb

   [Aliases=**-db**]


.. _sitehopper_build_opt_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: sitehopper_build

=======================
Optional Parameters
=======================

Input/output
============

.. option:: -prefix <prefix>

   Prefix used to name output files. [Default=sitehopper_build]

Database options
================

.. option:: -overwrite

   Option to overwrite existing database (if exists). [Default=false]

.. option:: -append

   Option to append to an existing database. [Default=false]

.. option:: -ncpu

   Number of CPUs to use when building the database.
   0 implies use all available CPUs on the local machine. [Default=0]

Logging
=======

.. option:: -log <logfile>

   The argument for this flag specifies the name of
   the log file. This overrides any specified prefix.
   The default will be determined by -prefix if no log file is specified.

.. option:: -param <param_file>

   The argument for this flag specifies the name of
   the a param file. All command line parameters will
   be written to this file. Passing an existing file
   will cause **sitehopper_build** to use parameters
   read from the file.

   [Default=sitehopper_build_settings.param]

   [Aliases=**-settings**]

.. option:: -progress

   Show progress while building. [Default=true]

.. option:: -verbose

   Triggers copious logging output. [Default=false]



.. _sitehopper_releasenotes:

Release History
===============

.. toctree::
   :maxdepth: 3

   version2_1_4
   version2_1_3
   version2_1_2
   version2_1_1
   version2_1_0
   version2_0_4
   version2_0_3
   version2_0_2
   version2_0_1
   version2_0_0
   version1_0_0


#################
SiteHopper 2.1.3
#################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************



Sitehopper TK 2.1.3
================================================================================

Minor internal improvements have been made.



##########################
SiteHopper 2.1.2
##########################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


SiteHopper TK 2.1.2
================================================================================

Minor internal improvements have been made.



SiteHopper  2.1.1
====================

Minor internal improvements have been made.



SiteHopper TK 2.1.1
================================================================================

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

* The :ref:`OESiteHopperIsGPUReady <OESiteHopper_OESiteHopperIsGPUReady>` function has been safeguarded from a rare crash.



SiteHopper  2.1.0
====================

Minor internal improvements have been made.

SiteHopper TK 2.1.0
================================================================================

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

* GPU-based **SiteHopper** is no longer used to prescreen but is enabled as a
  stand-alone search method.


SiteHopper  2.0.4
====================


Sitehopper TK 2.0.4
================================================================================

Minor internal improvements have been made.



SiteHopper  2.0.3
====================



Sitehopper TK 2.0.3
================================================================================

Minor internal improvements have been made.



SiteHopper  2.0.2
====================

 *Fall 2022*

Minor internal improvements have been made.
 
Sitehopper TK 2.0.2
=========================

Minor internal improvements have been made.



SiteHopper  2.0.1
================================================================================

*Spring 2022*

* Minor internal improvements have been made.
  


Sitehopper TK 2.0.1
================================================================================

Python-specific changes
--------------------------------------------------------------------------------

* An issue with :ref:`OEGetPatchSurface <OESiteHopper_OEGetPatchSurface>` wrapping to Python was fixed.




SiteHopper  2.0.0
================================================================================

*Fall 2021*

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

* This release includes support for all platforms: Linux, Windows and macOS.

* CPU-only search is now available on all platforms.

* On Linux, a new feature where GPU is used for a pre-screen with compatible
  NVIDIA cards as been added.

* The sitehopper_build application is now multi-threaded, resulting in much 
  faster build times.

* Databases built with the previous SiteHopper release are not compatible with
  these v2.0



SiteHopper TK 2.0.0
================================================================================

*Fall 2021*

This is the initial release of the **SiteHopper TK**.





SiteHopper  1.0.0
================================================================================

*July 2021*

This is first release of the **SiteHopper** application suite. **SiteHopper**
can search a database containing hundreds of thousands of design units for
proteins with similar binding sites to a query design unit in a few minutes
using an NVIDIA GPU.  **SiteHopper** can also create this database from a series
of biomolecular structures in ``OEDU`` format. The **SiteHopper** application
suite consists of the following applications:

* :ref:`sitehopper_build <chapter_sitehopper_build>` generates a database of
  patches from design units to be searched with :ref:`sitehopper_search <chapter_sitehopper_search>`.

* :ref:`sitehopper_search <chapter_sitehopper_search>` searches a database of
  design units for proteins with binding sites similar to a query design unit.

* A large database of patches based on the public is available for 
  `download <http://www.eyesopen.com/db-downloads>`_ in a platform-independent format.


.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _sitehopper_citation:

************
Citation
************

.. note:: To cite SiteHopper please use the following:

    SiteHopper |sitehopper_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



.. spruce documentation master file
.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _spruce-application-landing-page:

#################################
SPRUCE |spruce_version|
#################################

.. toctree::
   :maxdepth: 3

   theory/introduction
   spruce/spruce
   superposition/superposition
   enumsites/enumsites
   getstructure/getstructure
   loopdb_builder/loopdb_builder
   du2pdb/du2pdb
   du2mmcif/du2mmcif
   releasenotes/index
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt





.. _spruce_introduction:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


************
Introduction
************

==============
Overview
==============
The SPRUCE application provides the facilities to prepare biomolecules (that is, proteins and nucleic acids) for modeling tasks.

==============
Applications
==============

The **SPRUCE** distribution comprises these applications:

   :ref:`SPRUCE <chapter_spruce>`

   The :ref:`SPRUCE <chapter_spruce>` program is used for biomolecule preparation, from experimental or modeled structures.
   The process involves, 1) expansion of the :term:`asymmetric unit` to the :term:`biological unit` (if structure is from an X-ray crystallography
   experiment and it is necessary), 2) enumeration (default) or collapse of alternate locations, 3) building missing pieces, for example, partial
   sidechains, capping chain breaks, and modeling missing loops, 4) placement and optimization of hydrogen atoms including tautomer enumeration of ligands and cofactors,
   as well as evaluation of those tautomer states in the biomolecule structure.

   :ref:`Superposition <chapter_superposition>`

   The :ref:`Superposition <chapter_superposition>` program is used to superpose biomolecule structures onto a reference structure. Several different
   superposition methods are included, that are either based on sequence or secondary structure.

==================
Utility Programs
==================

The following utility programs are also included in this distribution:

   :ref:`LoopDB_Builder <chapter_loopdb_builder>`

   The :ref:`LoopDB_Builder <chapter_loopdb_builder>` program is used to build a database of known loops from a set of protein structures. This
   database can then be passed as an option to :ref:`SPRUCE <chapter_spruce>` to enable loop modeling of gaps in protein structures.

   :ref:`GetStructure <chapter_getstructure>`

   The :ref:`GetStructure <chapter_getstructure>` utility program can be used to download biomolecular structure files (PDB, mmCIF, structure factor CIF) for downstream prepping with :ref:`SPRUCE <chapter_spruce>`.

   :ref:`Du2pdb <chapter_du2pdb>`

   The :ref:`Du2pdb <chapter_du2pdb>` utility program can be used to convert DesignUnit oedu files to PDB file format.

   :ref:`EnumSites <chapter_enumsites>`

   The :ref:`EnumSites <chapter_enumsites>` program can be used to enumerate sites from prior bio-design units produced by :ref:`SPRUCE <chapter_spruce>`.
   This is particularly useful when enumerating potentially allosteric apo sites, that where not known when the structure was
   prepared the first time - enumeration ensures that the structure is not re-prepared but just focused into a site of interest.

====================================
Utilizing a Loop Template Database
====================================

Included in the SPRUCE product is a large database of loop templates, described further in the :ref:`Spruce theory <sprucetk_theory>` section.

To use it during prep:

   -loop_db_filename rcsb_spruce.loop_db

The database can be appended to (updated) using the :ref:`LoopDB_Builder <chapter_loopdb_builder>` utility. This would be in the event that the user has
a collection of internal/proprietary structures, or if specific structures are released to the public PDB between OpenEye updates of the database that are
crucial for a given target that is less well described by the existing templates. 

Loop building will only be done when a loop template database is provided.

For more information, see the :ref:`theory explanation for the Spruce toolkit <sprucetk_theory>` and
the :ref:`Iridium chapter of that toolkit <chapter_sprucetk_iridium>`.

.. previous .. include directives did not do the right thing with oe:source display

.. .. include:: ../../../toolkits/sprucetk/theory/theory.rst

.. .. include:: ../../../toolkits/sprucetk/theory/iridium.rst


.. _chapter_spruce:

*********************************
SPRUCE
*********************************

.. toctree::
   :maxdepth: 2

   spruce_overview
   spruce_outputnaming
   spruce_example
   spruce_help
   spruce_req_params
   spruce_opt_params


.. _spruce_overview:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: spruce

======================
Overview
======================

:ref:`SPRUCE <chapter_spruce>` is an application that prepares biomolecular structure files (PDB, mmCIF, oeb, etc.) for downstream modeling applications, such as running a :ref:`BROOD <chapter_brood>` query, docking a ligand with :ref:`FRED <chapter_fred>` or :ref:`HYBRID <chapter_hybrid>`, predicting poses with :ref:`POSIT <chapter_posit>`, or for running :ref:`SZMAP <chapter_szmap>` to analyze active-site hydration thermodynamics.
SPRUCE first runs a standardization and filter check to determine the quality of the input structure (see :ref:`OESpruceFilter <chapter_sprucetk_sprucefilter>`). The filter will fail the workflow if the structure did not pass the checks. The -allow_filter_error flag will alow one to continue to the preparation workflow even when the structure did not pass the filter.
The preparation workflow from an experimental or modeled structure involves, 1) expansion of the asymmetric unit to the biological unit (if structure is from an X-ray crystallography
experiment and it is necessary), 2) enumeration (default) or collapse of alternate locations, 3) building missing pieces e.g. partial
sidechains, capping chain breaks, and modeling missing loops, 4) placement and optimization of hydrogen atoms including tautomer enumeration of ligands and cofactors,
as well as evaluation of those tautomer states in the biomolecule structure. OEReceptors are added to the design units by default so they are ready for docking applications.
The generated DU will be checked by a design unit validation function. Parts that are not successfully built in spruce preparation will be logged and styled differently.
 
.. note::
  
  Included in the Spruce product is a loop building database which can be used to build missing loops. This database is available for 
  `download <http://www.eyesopen.com/db-downloads>`_ in a platform-independent format.

.. seealso::

   * The :ref:`ReceptorInDU` section



.. _spruce_output_naming:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: spruce

================================
Spruce Output Naming Conventions
================================

Output files generated from Spruce follows a general naming scheme.

{StructureID}_{ChainIDs}[alt{AltCode}]__DU__{LigandCode}_{ChainID}-{ResidueNumber}.oedu

The scheme can be prefixed by the user using the :option:`-prefix` input parameter. The user can also control
the output to a single file using the :option:`-out`, and additionally, set :option:`-warts` to append "_#" 
to the user specified output name.

Example of a structure without an alternate location, 2 files generate due to two ligand sites detected:

:file:`4ICL_AB__DU__T27_A-601.oedu`

:file:`4ICL_AB__DU__14N_A-607.oedu`

Example with an alternate location code:

:file:`1XDN_AaltA__DU__ATP_A-501.oedu`

For apo structures, the residue named is the one closest to the center of the marked binding site. That is unless the 
user has provided a binding site residue to indicate the binding site, in which case that is used in the title and filename.
Apo pocket example:

:file:`1HHP_AB__DU__apo_ASP_A-25.oedu`

Peptidic ligand example, where the ligand section is named slightly differently following the scheme
chainID-StartingResidueNumber-1LetterCodes-EndingResidueNumber. Only standard residue get 1 letter codes,
whereas nonstandard residue will have 3 letter codes separated by dashes.

:file:`4OBD_AB__DU__E-2-PGNFFQNRP-10.oedu`


.. _spruce_example:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: spruce

======================
Example Commands
======================

The simplest way to run **SPRUCE** is by passing in an input biomolecular structure file (PDB or mmCIF) as the only argument.

.. code-block:: bash

   prompt> spruce -in 3fly.cif.gz

Here, **SPRUCE** will correctly split and prepare :file:`3fly.cif.gz` with the :option:`-in` parameter and the standard set of default options. The output will generally be a set of OEDesignUnit (.oedu) files,
depending on the number of ligands and biological units in the asymmetric unit. In this case a single design unit file is produced (:file:`3FLY_A__DU__FLY_A-361.oedu`).

There are also many options that can be invoked from **SPRUCE** on the command line. For instance, several options are available to help **SPRUCE** determine the ligand based on molecular features like the number of residues in a peptidic ligand:

So for example:

.. code-block:: bash

   prompt> spruce -in 4obd.cif.gz -max_lig_residues 20

will correctly split and prepare :file:`4obd.cif.gz`, based on the :option:`-max_lig_residues` which sets the maximum number of residues that can still be considered a ligand (required for larger, peptidic ligands like those in 4OBD).

Alternatively, one may want to prepare a biomolecular structure file based on the structure of a similar reference system. For instance, one may construct an OEDesignUnit with a set of site residues defined using a reference that includes a ligand:

.. code-block:: bash

   prompt> spruce -ref 4OBD.oedu -in 1hhp.cif

Here, an mmCIF file (:file:`1hhp.cif`) is prepared using the site defined in the output OEDesignUnit file prepared using the :option:`-ref` option and an output .oedu file from the example above.

This could also have been done by specifying a site residue, for example (note the blank character for the insert code):

.. code-block:: bash

   prompt> spruce -site_residue "ASP:25: :A" -in 1hhp.cif

To calculate the Iridium classification as a metric of structure quality, one must provide the map file that corresponds to experiment from which the biomolecular structure was derived:

.. code-block:: bash

   prompt> spruce -map 3rox_validation_2fo-fc_map_coef.cif.gz -in 3rox.cif.gz

Here a set of OEDesignUnit files will be produced from :file:`3rox.cif.gz`, where each oedu file will include its own Iridium score taken from a calculation on the density passed in through the :option:`-map` option (:file:`3rox_validation_2fo-fc_map_coef.cif.gz`). The Iridium score can be extracted from any OEDesignUnit file using the **spruce TK** API, but it will also be reported in the **spruce** application's output.

.. note::

   The :option:`-map` option accepts structure factor CIF files (``.cif``, ``.cif.gz``) as provided by
   :ref:`GetStructure <chapter_getstructure>` and the RCSB, as well as legacy MTZ files (``.mtz``).

Several options in **SPRUCE** are available to help control how the system is prepared. For instance by default, **spruce** calculates partial charges and adds any hydrogen atoms missing from the experimental structure. However, if you have a have a downstream application that does not require certain time-consuming computations, like calculating partial charges or adding missing hydrogen atoms, you can tell **SPRUCE** to turn these features off:

.. code-block:: bash

   prompt> spruce -protonate false -charge_radii false -in 3tpp.cif.gz

Here, **SPRUCE** will not add partial charges or hydrogen atoms to the output structures during the preparation process of :file:`3tpp.cif.gz` by using the boolean options :option:`-protonate` and :option:`-charge_radii`, both of which are set to ``true`` by default.

To prevent continually over-writing output files, the :option:`-prefix` input parameter.
allows you to give unique names to these files.

.. code-block:: bash

   prompt> spruce -in 3fly.cif.gz -prefix FOO

will write the output structure into a file named :file:`FOO_3FLY_A__DU__FLY_A-361.oedu`.

Finally, to help **spruce** identify ligands in the biomolecular structure file, use the
:option:`-ligand_names` flag as in this example with :file:`3b3n.cif.gz`.

.. code-block:: bash

   prompt> spruce -ligand_names JI2 -in 3b3n.cif.gz



.. _spruce_help:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: spruce

======================
Command Line Help
======================

A description of the commandline interface can be obtained by executing **SPRUCE**
with the `--help` option.

.. code-block:: bash

   prompt> spruce --help

will generate the following output:

::

   Help functions:
     spruce --help simple      : Get a list of simple parameters
     spruce --help all         : Get a complete list of parameters
     spruce --help defaults    : List the defaults for all parameters
     spruce --help <parameter> : Get detailed help on a parameter
     spruce --help html        : Create an html help file for this program
     spruce --help version     : List the toolkits and versions used in the application



.. _spruce_req_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: spruce

======================
Required Parameters
======================

.. option:: -in <filename>

   File containing one or more 3D biomolecules that will be split into known components and fully prepared for downstream modeling.

   File format for :option:`-in` can be one of:

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   mmCIF        .cif .cif.gz
   ============ ===========================

   [keyless parameter 1]



.. _spruce_opt_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: spruce

=======================
Optional Parameters
=======================

Input Options
--------------

.. option:: -ligand_names <names>

   If multiple ligands are in the structure but only a specific ones are desired,
   they can be specified here. Examples are either the three letter code "LIG", or in
   case of a peptide "VAL-GLU-TYS-PHE-ALA". Multiple different ligands, should be separated by commas,
   "LIG,GIL,INH".

   .. seealso::

      * :ref:`OEStructureMetadata <OESpruce_OEStructureMetadata>` in the **Spruce TK** manual.
      * :ref:`OEHeterogenMetadata <OESpruce_OEHeterogenMetadata>` in the **Spruce TK** manual.

.. option:: -map <filename>

   Input electron density map from X-ray crystallography, to be used for Iridium score calculation.
   Accepted formats are structure factor CIF files (``.cif``, ``.cif.gz``) and legacy MTZ files (``.mtz``).
   Structure factor CIF files are the current format provided by the RCSB; MTZ files are supported for backward compatibility.

.. option:: -metadata <filename>

   Metadata json file containing OEStructureMetadata. Using this can be a way to indicate desired ligands,
   tautomers to use for ligands, structure sequence etc., as well as structure title for output file names.
   The -generate_tautomers option should be set to false and -opt_expt_protons to true to only consider
   the desired ligands. More details along with an example metadata file can be found at :ref:`spruce_examples_make_design_units_using_metadata`.
   The :ref:`OESpruce::OEStructureMetadataToJson <OESpruce_OEStructureMetadataToJson>` fucntion can be used to create an appropriate json file as well.
   
   .. seealso::

      * :ref:`OEStructureMetadata <OESpruce_OEStructureMetadata>` in the **Spruce TK** manual.
      * :ref:`OESequenceMetadata <OESpruce_OESequenceMetadata>` in the **Spruce TK** manual.
      * :ref:`OEHeterogenMetadata <OESpruce_OEHeterogenMetadata>` in the **Spruce TK** manual.

.. option:: -ref <filename>

   Reference OEDesignUnit indicating the proper biological unit and relevant binding site.

.. option:: -site_residue <residue identifier>

   Input option to specify a binding site using a single residue specification if apo (or holo).
   The format is "name:num:insert code:chainid", e.g. "ASP:25: :A" indicating Aspartic acid 25 in chain A. Note: A blank/whitespace
   character is used for the insert code, which is a typical use case.

   .. seealso::

      * :ref:`OEMakeDesignUnits <OESpruce_OEMakeDesignUnits>` in the **Spruce TK** manual. This API exposes the ``siteResidue`` argument.
      * :ref:`OEMakeBioDesignUnits <OESpruce_OEMakeBioDesignUnits>` in the **Spruce TK** manual.

.. option:: -add_receptors

   Option to add OEReceptors onto the design units

   [Default=true]

   .. seealso::

      * :ref:`OEDocking::OEMakeReceptor <OEDocking_OEMakeReceptor>` in the **OEDocking TK** manual. This API takes an :ref:`OEDesignUnit <OEBio_OEDesignUnit>` argument.

Output Options
--------------

.. option:: -out <out>

   Write to a user specified file. Enforces \*.oedu format. Can be used with :option:`-warts`
   to write multiple files, one per design unit.

.. option:: -warts

   Option to add warts "_#" to the user supplied filename, when writing multiple design units.

   [Default=false]

.. option:: -prefix <prefix>

   Prefix used to name output files, default is blank

.. option:: -log <logfile>

   The argument for this flag specifies the name of
   the log file. This overrides any specified prefix.
   The default will be spruce_output.log, if no prefix is specified.

.. option:: -settings_file <settingsfile>

   (Alias: -settings)

   The argument for this flag specifies the name of
   the settings file. This overrides any specified prefix.
   The default will be spruce_settings.param, if no prefix is specified.

.. option:: -verbose

   Triggers copious logging output.

   [Default=false]

.. option:: -write_biounits

   Option to write intermediate Bio-DesignUnits, which can be used with *enumsites* to site to potential allosteric sites later.

   [Default=false]

Split Parameters
--------------------------

.. option:: -altloc <method>

   Parameter determining how alternate locations are handled. The *primary* option, collapses alternate locations,
   whereas the *enumerate* option attempts to set detected alternate locations, A, B, etc.

   [Default=enumerate]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitSplitOptions::SetAlternateLocationHandling <OESpruce_OEDesignUnitSplitOptions_SetAlternateLocationHandling>` in the **Spruce TK** manual.

.. option:: -cofactor_codes <codes>

   Mechanism to define 3 letter codes that should be recognized as co-factors if not done automatically, e.g. "ATP",
   or "ATP,NAD"

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitSplitOptions::SetCofactorCodes <OESpruce_OEDesignUnitSplitOptions_SetCofactorCodes>` in the **Spruce TK** manual.

.. option:: -excipient_codes

   Mechanism to define 3 letter codes that should be recognized as excipients if not done automatically, e.g. "GOL",
   or "GOL,DMS"

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitSplitOptions::SetExcipientCodes <OESpruce_OEDesignUnitSplitOptions_SetExcipientCodes>` in the **Spruce TK** manual.

.. option:: -lipid_codes <codes>

   Mechanism to define 3 letter codes that should be recognized as lipids if not done automatically, e.g. "PGR",
   or "PGR,CHL"

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitSplitOptions::SetLipidCodes <OESpruce_OEDesignUnitSplitOptions_SetLipidCodes>` in the **Spruce TK** manual.

.. option:: -make_packing_residues

   Option to generate packing residues, both for visualization, but also for Iridium classification

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitSplitOptions::SetMakePackingResidues <OESpruce_OEDesignUnitSplitOptions_SetMakePackingResidues>` in the **Spruce TK** manual.

.. option:: -min_lig_atoms

   Parameter determining the min number of atoms a ligand molecule can have.
   A reason to lower this number would be for small fragments that need to be classified as ligands

   [Default=8]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitSplitOptions::SetMinLigAtoms <OESpruce_OEDesignUnitSplitOptions_SetMinLigAtoms>` in the **Spruce TK** manual.

.. option:: -max_lig_atoms

   Parameter determining the max number of atoms a ligand molecule can have.
   A reasons to increase this number could be for peptidic ligands

   [Default=100]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitSplitOptions::SetMaxLigAtoms <OESpruce_OEDesignUnitSplitOptions_SetMaxLigAtoms>` in the **Spruce TK** manual.

.. option:: -max_lig_residues

   Parameter determining the max number of residues a ligand molecule can have.
   A reasons to increase this number could be for peptidic ligands

   [Default=5]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitSplitOptions::SetMaxLigResidues <OESpruce_OEDesignUnitSplitOptions_SetMaxLigResidues>` in the **Spruce TK** manual.

.. option:: -max_sys_atoms

   Parameter limiting the max number of atoms in the entire system that spruce will allow for processing.
   If this limit is reached e.g. due to a large systems or symmetry expansion resulting in a larger than expected
   system, spruce will stop processing and return false.

   [Default=50,000]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitSplitOptions::SetMaxSystemAtoms <OESpruce_OEDesignUnitSplitOptions_SetMaxSystemAtoms>` in the **Spruce TK** manual.

.. option:: -target

   Parameter telling the system what the "target" is. This is particularly helpful for systems containing
   both protein and nucleic acids, where the automated system does not correctly identify the nucleic acid as the target
   of interest. Allowed values are protein or nucleic.

   [Default=protein]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitSplitOptions::SetTargetComponentID <OESpruce_OEDesignUnitSplitOptions_SetTargetComponentID>` in the **Spruce TK** manual.

Enumerate Sites Parameters
--------------------------

.. option:: -add_interactions

   Option to add OEInteractionHints to the design unit(s)

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetAddInteractionHints <OESpruce_OEDesignUnitEnumerateSitesOptions_SetAddInteractionHints>` in the **Spruce TK** manual.

.. option:: -add_style

   Option to add visualization style to the design unit(s)

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetAddStyle <OESpruce_OEDesignUnitEnumerateSitesOptions_SetAddStyle>` in the **Spruce TK** manual.

.. option:: -collapse_nonsite_alts

   Option to deduplicate structures with different alternate locations if those alternate locations
   are far from the binding site

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetCollapseNonSiteAlts <OESpruce_OEDesignUnitEnumerateSitesOptions_SetCollapseNonSiteAlts>` in the **Spruce TK** manual.

.. option:: -duplicate_removal

   Option to deduplicate identical structures resulting from symmetry operations

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetDuplicateRemoval <OESpruce_OEDesignUnitEnumerateSitesOptions_SetDuplicateRemoval>` in the **Spruce TK** manual.

.. option:: -enum_cofactors_sites

   Option to generate design units with sites based on components classified as co-factors

   [Default=false]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetEnumerateCofactorSites <OESpruce_OEDesignUnitEnumerateSitesOptions_SetEnumerateCofactorSites>` in the **Spruce TK** manual.

.. option:: -restrict_to_refsite

   Option to skip generating design units for sites identified, that do not match a provided reference design unit

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetRestrictToRefSite <OESpruce_OEDesignUnitEnumerateSitesOptions_SetRestrictToRefSite>` in the **Spruce TK** manual.

.. option:: -site_size <value>

   Distance from the ligand used to determine the size of the site

   [Default=5.0 (angstroms)]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetSiteSize <OESpruce_OEDesignUnitEnumerateSitesOptions_SetSiteSize>` in the **Spruce TK** manual.

.. option:: -superpose

   Option to superpose generated design units, if multiple. If a reference is provided, the first generated
   design unit will be superposed onto the reference structure, and subsequent structures onto that one.

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEMakeDesignUnitOptions::SetSuperpose <OESpruce_OEMakeDesignUnitOptions_SetSuperpose>` in the **Spruce TK** manual.

.. option:: -superpose_method <method>

   The method to use for superposition

   ==============  ======================================================================================
   Method          Description
   ==============  ======================================================================================
   global          Global Sequence Alignment to identify CA pairs
   --------------  --------------------------------------------------------------------------------------
   site            Global Sequence Alignment to identity CA pairs - focusing on the subset in active site
   --------------  --------------------------------------------------------------------------------------
   ddm             Superposition using the Distance Difference Matrix method (DDM)
   --------------  --------------------------------------------------------------------------------------
   sse             Superposition using an overlap of Secondary Structure Elements (SSE)
   --------------  --------------------------------------------------------------------------------------
   weighted        Superposition weighting residues by B-factor or occupancy
   --------------  --------------------------------------------------------------------------------------
   sitehopper      Superposition based on binding site similarities (sitehopper)
   --------------  --------------------------------------------------------------------------------------
   GlobalSequence  Alias for global — Global Sequence Alignment to identify CA pairs
   --------------  --------------------------------------------------------------------------------------
   DDMatrix        Alias for ddm — Superposition using the Distance Difference Matrix method
   --------------  --------------------------------------------------------------------------------------
   SiteSequence    Alias for site — Global Sequence Alignment focusing on the active site
   ==============  ======================================================================================

   .. seealso::

      * :ref:`OESpruce::OEMakeDesignUnitOptions::SetSuperpositionMethod <OESpruce_OEMakeDesignUnitOptions_SetSuperpositionMethod>` in the **Spruce TK** manual.

Build Parameters
----------------

.. option:: -build_cterm_caps

   Option to cap broken c-termini in protein chains

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitBuildOptions::SetCapCTermini <OESpruce_OEDesignUnitBuildOptions_SetCapCTermini>` in the **Spruce TK** manual.

.. option:: -build_nterm_caps

   Option to cap broken n-termini in protein chains

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitBuildOptions::SetCapNTermini <OESpruce_OEDesignUnitBuildOptions_SetCapNTermini>` in the **Spruce TK** manual.

.. option:: -build_loops

   Option to build loops for gaps in the protein structure

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitBuildOptions::SetBuildLoops <OESpruce_OEDesignUnitBuildOptions_SetBuildLoops>` in the **Spruce TK** manual.

.. option:: -build_sidechains

   Option to build missing or partial protein sidechains

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitBuildOptions::SetBuildSidechains <OESpruce_OEDesignUnitBuildOptions_SetBuildSidechains>` in the **Spruce TK** manual.

.. option:: -enum_pockets

   Option to detect pockets and generate design units from them

   [Default=false]

Sidechain Build Parameters
--------------------------

.. option:: -sc_delete_clashing_solvent

   Option to allow build steps to remove clashing solvent

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OESidechainBuilderOptions::SetDeleteClashingSolvent <OESpruce_OESidechainBuilderOptions_SetDeleteClashingSolvent>` in the **Spruce TK** manual.

.. option:: -rot_coverage <value>

   Coverage of rotamer libraries to use, a lower number can be used to speed up
   side chain re-building skipping lower probability side-chain rotamers.

   [Default=100.0]

   .. seealso::

      * :ref:`OESpruce::OESidechainBuilderOptions::SetRotamerCoverage <OESpruce_OESidechainBuilderOptions_SetRotamerCoverage>` in the **Spruce TK** manual.

.. option:: -rot_library <value>

   Rotamer library used for building sidechains and loops. Allowed values are 'richardson2016',
   'dunbrack', 'richardson'.

   [Default=richardson2016]

   .. seealso::

      * :ref:`OESpruce::OESidechainBuilderOptions::SetRotamerLibrary <OESpruce_OESidechainBuilderOptions_SetRotamerLibrary>` in the **Spruce TK** manual.

Loop Build Parameters
---------------------

.. option:: -build_with_crystalpacking

   Include packing residues when building loops

   [Default=false]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetUsePackingResidues <OESpruce_OELoopBuilderOptions_SetUsePackingResidues>` in the **Spruce TK** manual.

.. option:: -loop_db_filename <filename>

   Database containing loop templates

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetLoopDBFilename <OESpruce_OELoopBuilderOptions_SetLoopDBFilename>` in the **Spruce TK** manual.

.. option:: -crop_length <value>

   Anchor residues on the protein to crop back for a better fit, results in longer loops being built

   [Default=1]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetCropLength <OESpruce_OELoopBuilderOptions_SetCropLength>` in the **Spruce TK** manual.

.. option:: -transform_threshold <value>

   Number of loops to allow through the sidechain clash checker. No matter this number, will process all with an identical sequence to target.

   [Default=25]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetTransformThreshold <OESpruce_OELoopBuilderOptions_SetTransformThreshold>` in the **Spruce TK** manual.

.. option:: -strict_proline_match

   Fuzzy matches in the loop database have to have proline in exact locations of sequence.

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetStrictProlineMatch <OESpruce_OELoopBuilderOptions_SetStrictProlineMatch>` in the **Spruce TK** manual.

.. option:: -loop_distance_buffer <value>

   Fuzzy matches in the loop database has to have distance between anchor atoms correct, +/- buffer distance

   [Default=1.0]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetConnectBufferDistance <OESpruce_OELoopBuilderOptions_SetConnectBufferDistance>` in the **Spruce TK** manual.

.. option:: -bb_clash_threshold <value>

   Loops from the database where more than the threshold fraction of the backbone atoms clash, are rejected

   [Default=0.25]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetBackboneClashRejectThreshold <OESpruce_OELoopBuilderOptions_SetBackboneClashRejectThreshold>` in the **Spruce TK** manual.

.. option:: -loop_clash_threshold <value>

   Loops from the database where more than the threshold fraction of the loops atoms in addition to the backbone clashing ones clash, are rejected

   [Default=0.2]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetLoopClashRejectThreshold <OESpruce_OELoopBuilderOptions_SetLoopClashRejectThreshold>` in the **Spruce TK** manual.

.. option:: -opt_shell <value>

   Include atoms within this distance in the loop optimization, larger distance results in slower optimization

   [Default=15.0]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetOptimizationShell <OESpruce_OELoopBuilderOptions_SetOptimizationShell>` in the **Spruce TK** manual.

.. option:: -opt_tolerance <value>

   Tolerance for the loop optimization, smaller numbers result in slower optimization

   [Default=0.001]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetOptimizationTolerance <OESpruce_OELoopBuilderOptions_SetOptimizationTolerance>` in the **Spruce TK** manual.

.. option:: -opt_stage1_iter_multiplier <value>

   Number of steps per number of residues in the loop for the first stage optimizer

   [Default=5]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetOptimizationStage1IterMultiplier <OESpruce_OELoopBuilderOptions_SetOptimizationStage1IterMultiplier>` in the **Spruce TK** manual.

.. option:: -opt_stage2_iter_multiplier <value>

   Number of steps per number of residues in the loop for the second stage optimizer

   [Default=10]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetOptimizationStage2IterMultiplier <OESpruce_OELoopBuilderOptions_SetOptimizationStage2IterMultiplier>` in the **Spruce TK** manual.

.. option:: -incl_solvation <value>

   Include simple solvation model when building loops

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetOptimizationUseSolventModel <OESpruce_OELoopBuilderOptions_SetOptimizationUseSolventModel>` in the **Spruce TK** manual.

.. option:: -incl_SA_term <value>

   Include solvent accessible surface area term when ranking the loops

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetOptimizationInclSurfaceAreaTerm <OESpruce_OELoopBuilderOptions_SetOptimizationInclSurfaceAreaTerm>` in the **Spruce TK** manual.

.. option:: -max_eval_loops <value>

   Maximum number of loops to connect and minimize

   [Default=5]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetOptimizationMaxLoops <OESpruce_OELoopBuilderOptions_SetOptimizationMaxLoops>` in the **Spruce TK** manual.

.. option:: -build_disulfidebridges <value>

   Allow the loop builder to build disulfide brides during loop modeling (if possible)

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetAllowBuildDisulfideBridges <OESpruce_OELoopBuilderOptions_SetAllowBuildDisulfideBridges>` in the **Spruce TK** manual.

.. option:: -build_tails

   Option to build missing terminal residues from sequence database

   [Default=false]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetBuildTails <OESpruce_OELoopBuilderOptions_SetBuildTails>` in the **Spruce TK** manual.

.. option:: -seqalign_gap_penalty <value>

   Gap penalty for sequence alignment during loop building

   [Default=-10]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetSeqAlignGapPenalty <OESpruce_OELoopBuilderOptions_SetSeqAlignGapPenalty>` in the **Spruce TK** manual.

.. option:: -seqalign_extend_penalty <value>

   Gap extension penalty for sequence alignment during loop building

   [Default=-2]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetSeqAlignExtendPenalty <OESpruce_OELoopBuilderOptions_SetSeqAlignExtendPenalty>` in the **Spruce TK** manual.

.. option:: -reject_clashing_loops_postminimization

   Reject loops that clash after minimization

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetRejectClashingLoopsPostMinimization <OESpruce_OELoopBuilderOptions_SetRejectClashingLoopsPostMinimization>` in the **Spruce TK** manual.

.. option:: -delete_existing_residues

   Delete existing residues in the loop region before building

   [Default=false]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetDeleteExistingResidues <OESpruce_OELoopBuilderOptions_SetDeleteExistingResidues>` in the **Spruce TK** manual.

Cap Build Parameters
--------------------

.. option:: -cap_delete_clashing_solvent

   Option to allow build steps to remove clashing solvent

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OECapBuilderOptions::SetDeleteClashingSolvent <OESpruce_OECapBuilderOptions_SetDeleteClashingSolvent>` in the **Spruce TK** manual.

.. option:: -allow_truncate

   Option to allow terminal residue to converted to cap, if cap will otherwise clash

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OECapBuilderOptions::SetAllowTruncate <OESpruce_OECapBuilderOptions_SetAllowTruncate>` in the **Spruce TK** manual.

Prep Parameters
---------------

.. option:: -charge_radii

   Option to assign partial charge and radii

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitPrepOptions::SetAssignPartialChargesAndRadii <OESpruce_OEDesignUnitPrepOptions_SetAssignPartialChargesAndRadii>` in the **Spruce TK** manual.

.. option:: -protonate

   Option add and optimize protons in the system

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitPrepOptions::SetProtonate <OESpruce_OEDesignUnitPrepOptions_SetProtonate>` in the **Spruce TK** manual.

.. option:: -strict_protonate

   Option to use strict protonation, disabling tautomer generation for heterogens

   [Default=false]

Protonation Parameters
----------------------

.. option:: -generate_tautomers

   Option to generate and use tautomers in the hydrogen network optimization

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEProtonateDesignUnitOptions::SetGenerateTautomers <OESpruce_OEProtonateDesignUnitOptions_SetGenerateTautomers>` in the **Spruce TK** manual.

.. option:: -het_group_nbr_dist <value>

   Distance between heterogens used to determine optimization clusters for protonation

   [Default=3.5 (angstroms)]

   .. seealso::

      * :ref:`OESpruce::OEProtonateDesignUnitOptions::SetHetGroupNbrDist <OESpruce_OEProtonateDesignUnitOptions_SetHetGroupNbrDist>` in the **Spruce TK** manual.

.. option:: -opt_expt_protons

   Option to optimize hydrogens assigned in the experiment.

   [Default=false]

   .. seealso::

      * :ref:`OESpruce::OEProtonateDesignUnitOptions::SetOptimizeExpProtons <OESpruce_OEProtonateDesignUnitOptions_SetOptimizeExpProtons>` in the **Spruce TK** manual.

.. option:: -flip_bias_scale

   Bias scale for flippable groups (e.g. HIS/ASN/GLN) during hydrogen placement

   [Default=1.0]

   .. seealso::

      * :ref:`OESpruce::OEProtonateDesignUnitOptions::SetPlaceHydrogensOptions <OESpruce_OEProtonateDesignUnitOptions_SetPlaceHydrogensOptions>` in the **Spruce TK** manual.

Biological Unit Extraction Parameters
-------------------------------------

.. option:: -bu_superpose

   Option to superpose the biological units

   [Default=false]

   .. seealso::

      * :ref:`OESpruce::OEBioUnitExtractionOptions::SetSuperpose <OESpruce_OEBioUnitExtractionOptions_SetSuperpose>` in the **Spruce TK** manual.

.. option:: -max_bu_atoms

   Option to limit the size of BUs processed based on number of atoms

   [Default=50,000]

   .. seealso::

      * :ref:`OESpruce::OEBioUnitExtractionOptions::SetMaxAtoms <OESpruce_OEBioUnitExtractionOptions_SetMaxAtoms>` in the **Spruce TK** manual.

.. option:: -max_bu_parts

   Option to limit the size of BUs processed based on number of parts

   [Default=24]

   .. seealso::

      * :ref:`OESpruce::OEBioUnitExtractionOptions::SetMaxParts <OESpruce_OEBioUnitExtractionOptions_SetMaxParts>` in the **Spruce TK** manual.

.. option:: -min_align_score

   Option to specify minimum sequence alignment score

   [Default=200]

   .. seealso::

      * :ref:`OESpruce::OEBioUnitExtractionOptions::SetMinScore <OESpruce_OEBioUnitExtractionOptions_SetMinScore>` in the **Spruce TK** manual.

.. option:: -pref_author_record

   Option where the author BIOMT record is preferred over the software generated one

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEBioUnitExtractionOptions::SetPreferAuthorRecord <OESpruce_OEBioUnitExtractionOptions_SetPreferAuthorRecord>` in the **Spruce TK** manual.

Enumerate Pocket Parameters
-----------------------------

.. option:: -pocketMask

   Option to set the subset of design unit components to be used for pocket finding. Multiple components can be combined as a comma separated string to create the input.

   [Default=true]

.. option:: -min_pocket_surf_area

   Option to set minimum surface area of detected pocket.

   [Default=150.0]

   .. seealso::

      * :ref:`OESpruce::OEPocketOptions::SetMinSurfaceArea <OESpruce_OEPocketOptions_SetMinSurfaceArea>` in the **Spruce TK** manual.

.. option:: -max_pocket_surf_area

   Option to set maximum surface area of detected pocket.

   [Default=3000.0]

   .. seealso::

      * :ref:`OESpruce::OEPocketOptions::SetMaxSurfaceArea <OESpruce_OEPocketOptions_SetMaxSurfaceArea>` in the **Spruce TK** manual.

.. option:: -pocket_burial_factor

   Option to set the factor used to distinguish pockets from the general surface.

   [Default=1.4]

   .. seealso::

      * :ref:`OESpruce::OEPocketOptions::SetBurialFactor <OESpruce_OEPocketOptions_SetBurialFactor>` in the **Spruce TK** manual.

OEReceptor Parameters
--------------------------

.. option:: -targetMask

   Subset of design unit components to be used as target for the receptor. Multiple components can be combined as a comma separated string to create the input

   [Default=protein,nucleic,cofactors,metals,lipids,other_proteins,other_nucleics,other_ligands,other_cofactors]

   Please see more details at :ref:`SPRUCE <chapter_spruce>` and :ref:`ReceptorInDU`.

Special Parameters
--------------------------

.. option:: -no_prep

   Option to skip all preparation steps. This will supersede any other optional flags set.

   [Default=false]

Filter Options Parameters
--------------------------

.. option:: -allow_filter_error

   Option to allow running spruce prep even when structure fails spruce filter.

   [Default=false]

.. option:: -fix_res_names

   Option to fix incorrect residue names.

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OESpruceFilterOptions::SetFixNames <OESpruce_OESpruceFilterOptions_SetFixNames>` in the **Spruce TK** manual.

.. option:: -fix_res_states

   Option to fix incorrect residue states.

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OESpruceFilterOptions::SetFixResStates <OESpruce_OESpruceFilterOptions_SetFixResStates>` in the **Spruce TK** manual.

.. option:: -fix_bonds_to_metals

   Option to fix incorrect covalent bonds to metals.

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OESpruceFilterOptions::SetFixBondsToMetals <OESpruce_OESpruceFilterOptions_SetFixBondsToMetals>` in the **Spruce TK** manual.

.. option:: -fix_bb_atoms

   Option to fix protein backbone atom states.

   [Default=true]
   

   .. seealso::

      * :ref:`OESpruce::OESpruceFilterOptions::SetFixBackboneAtoms <OESpruce_OESpruceFilterOptions_SetFixBackboneAtoms>` in the **Spruce TK** manual.

.. option:: -fix_float_res

   Option to delete floating residues

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OESpruceFilterOptions::SetDeleteFloatingRes <OESpruce_OESpruceFilterOptions_SetDeleteFloatingRes>` in the **Spruce TK** manual.

.. option:: -fix_chainID

   Option to fix missing chain ID

   [Default=true]
   

   .. seealso::

      * :ref:`OESpruce::OESpruceFilterOptions::SetFixChainIDs <OESpruce_OESpruceFilterOptions_SetFixChainIDs>` in the **Spruce TK** manual.

.. option:: -fix_covalent_bond

   Option to fix incorrect covalent bonds to halogens

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OESpruceFilterOptions::SetFixInvalidCovalentBonds <OESpruce_OESpruceFilterOptions_SetFixInvalidCovalentBonds>` in the **Spruce TK** manual.

.. option:: -allow_validation_error

   Option to allow writing OEDesignUnits even if they fail validation

   [Default=true]


.. _chapter_superposition:

*********************************
Superposition
*********************************

.. toctree::
   :maxdepth: 2

   superposition_overview
   superposition_example
   superposition_help
   superposition_req_params
   superposition_opt_params


.. _superposition_overview:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: superposition 

======================
Overview
======================

:ref:`Superposition <chapter_superposition>` is an application that structurally superposes a given biomolecular structure file (oedu, PDB, mmCIF, oeb, etc.) onto a reference structure (oedu, PDB, mmCIF, oeb, etc.).


.. _superposition_example:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: superposition

======================
Example Commands
======================

The simplest way to run **Superposition** is by passing in both a reference and a fit input biomolecular structure file:

.. code-block:: bash

   prompt> superposition -ref 4obd.pdb -fit 1hhp.pdb

Here, **Superposition** will fit the protein in :file:`1hhp.pdb` against the reference protein in :file:`4obd.pdb`. The output
will list the RMSD of the superposed result, the order in which the ref and fit chains were superposed, and the sequence alignment score, if the
method is sequence based. The command should generate a PDB file called :file:`superposed_1hhp.pdb` that contains the superposed protein and the 
following message in the log file:

.. code-block:: none

   Superposition - RMSD: 1.16, Ref: ABCDEF, Fit: A, SeqScore: 492

The structural superposition method can be set on the command line with the :option:`-method` option:

For example:

.. code-block:: bash

   prompt> superposition -ref 1a29.pdb -fit 1cll.pdb -method ddm

will superpose :file:`1cll.pdb` onto the reference file :file:`1a29.pdb` using the ``ddm`` (`difference-distance matrix`) method. 
The command should generate a PDB file called :file:`superposed_1cll.pdb` that contains the superposed protein and the following 
message in the log file:

.. code-block:: none

   Superposition - RMSD: 0.60, Ref: A, Fit: A, SeqScore: 642

To prevent continually over-writing output files, the :option:`-prefix` flag
allows you to give unique names to these files.

.. code-block:: bash

   prompt> superposition -ref 1a29.pdb -fit 1cll.pdb -method sse -prefix FOO

will write the output structures into a file named :file:`FOO_1cll.pdb` and following message to the log file:

.. code-block:: bash

   Superposition - Tanimoto: 0.31, Ref: A, Fit: A



.. _superposition_help:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: superposition 

======================
Command Line Help 
======================

A description of the commandline interface can be obtained by executing **Superposition**
with the `--help` option.

.. code-block:: bash
   
   prompt> superposition --help

will generate the following output:

::

   Help functions:
     superposition --help simple      : Get a list of simple parameters
     superposition --help all         : Get a complete list of parameters
     superposition --help <parameter> : Get detailed help on a parameter
     superposition --help html        : Create an html help file for this program


.. _superposition_req_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: superposition

======================
Required Parameters
======================

.. option:: -fit <filename>

   File containing the 3D biomolecules that will be structurally superposed.

   File format for :option:`-fit` can be one of:

   ============= ===========================
   File type     Extension
   ============= ===========================
   OEDesignUnit  .oedu
   ------------- ---------------------------
   OEBinary      .oeb .oeb.gz
   ------------- ---------------------------
   PDB           .pdb .ent .pdb.gz .ent.gz
   ------------- ---------------------------
   mmCIF         .cif .cif.gz
   ============= ===========================

.. option:: -ref <filename>

   File containing the 3D biomolecules that will act as the reference for the structural superposition.

   File format for :option:`-ref` can be one of:

   ============= ===========================
   File type     Extension
   ============= ===========================
   OEDesignUnit  .oedu
   ------------- ---------------------------
   OEBinary      .oeb .oeb.gz
   ------------- ---------------------------
   PDB           .pdb .ent .pdb.gz .ent.gz
   ------------- ---------------------------
   mmCIF         .cif .cif.gz
   ============= ===========================

.. _superposition_opt_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


..  program:: superposition

=================================
Optional Parameters
=================================

Input Options
--------------

.. option:: -fit_lig <filename>

   A file containing a ligand to use as a constraint during the superposition.
   Should only be used if the input is not an OEDesignUnit

   .. seealso::

      * :ref:`OESpruce::OESuperpose::SetupRef <OESpruce_OESuperPose_SetupRef>` and :ref:`OESpruce::OESuperpose::Superpose <OESpruce_OESuperPose_Superpose>` in the **Spruce TK** manual.

.. option:: -ref_lig <filename>

   A file containing a reference ligand to use as a constraint during the superposition.
   Should only be used if the input is not an OEDesignUnit

   .. seealso::

      * :ref:`OESpruce::OESuperpose::SetupRef <OESpruce_OESuperPose_SetupRef>` and :ref:`OESpruce::OESuperpose::Superpose <OESpruce_OESuperPose_Superpose>` in the **Spruce TK** manual.

Output Options
--------------

.. option:: -prefix <prefix>

   Prefix used to name output files, default is blank. To avoid overwriting input files,
   all structure files are automatically using the prefix `superposed_` if no prefix is specified.

.. option:: -log <logfile>

   The argument for this flag specifies the name of
   the log file. This overrides any specified prefix.

.. option:: -settings_file <settingsfile>

   (Alias: -settings)

   The argument for this flag specifies the name of
   the settings file. This overrides any specified prefix.

.. option:: -verbose

   Triggers copious logging output

Parameters
--------------

.. option:: -method <method>

   The method to use for superposition

   ==========  ======================================================================================
   Method      Description
   ==========  ======================================================================================
   global      Global Sequence Alignment to identify CA pairs
   ----------  --------------------------------------------------------------------------------------
   site        Global Sequence Alignment to identity CA pairs - focusing on the subset in active site
   ----------  --------------------------------------------------------------------------------------
   ddm         Superposition using the Distance Difference Matrix method (DDM)
   ----------  --------------------------------------------------------------------------------------
   sse         Superposition using an overlap of Secondary Structure Elements (SSE)
   ----------  --------------------------------------------------------------------------------------
   weighted    Superposition using Weighted DDM method
   ----------  --------------------------------------------------------------------------------------
   sitehopper  Superposition using SiteHopper
   ==========  ======================================================================================

   .. seealso::

      * :ref:`OESpruce::OESuperposeOptions::SetMethod <OESpruce_OESuperposeOptions_SetMethod>` in the **Spruce TK** manual.

.. option:: -valid_seqscore <value>

   Minimum sequence alignment score for the superposition to be considered valid

   [Default=200]

   .. seealso::

      * :ref:`OESpruce::OESuperposeOptions::SetValidSeqScore <OESpruce_OESuperposeOptions_SetValidSeqScore>` in the **Spruce TK** manual.

.. option:: -valid_rmsd <value>

   Maximum RMSD threshold for the superposition to be considered valid

   [Default=10.0]

   .. seealso::

      * :ref:`OESpruce::OESuperposeOptions::SetValidRMSD <OESpruce_OESuperposeOptions_SetValidRMSD>` in the **Spruce TK** manual.

.. option:: -valid_tanimoto <value>

   Minimum Tanimoto similarity threshold for the superposition to be considered valid

   [Default=0.0]

   .. seealso::

      * :ref:`OESpruce::OESuperposeOptions::SetValidTanimoto <OESpruce_OESuperposeOptions_SetValidTanimoto>` in the **Spruce TK** manual.


.. _chapter_enumsites:

*********************************
EnumSites
*********************************

.. toctree::
   :maxdepth: 2

   enumsites_overview
   enumsites_example
   enumsites_help
   enumsites_req_params
   enumsites_opt_params


.. _enumsites_overview:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: enumsites

======================
Overview
======================

:ref:`EnumSites <chapter_enumsites>` is an application that enumerates biounit OEDesignUnit (oedu) files, and it creates individual oedu files for every active site discovered.

.. _enumsites_example:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: enumsites

======================
Example Commands
======================

The simplest way to run **EnumSites** is by passing in an unprepped, biounit OEDesignUnit file (oedu) as the input and a fully prepared OEDesignUnit file as a reference.

.. code-block:: bash

   prompt> enumsites -ref 4OBD_AB__DU__E-2-PGNFFQNRP-10.oedu -in 1HHP_AB__DU__biounit.oedu

Here, **EnumSites** will use the biounit OEDesignUnit :file:`1HHP_AB__DU__biounit.oedu` with the :option:`-in` parameter, along with a reference OEDesignUnit
file :file:`4OBD_AB__DU__E-2-PGNFFQNRP-10.oedu` with the :option:`-ref` option, in order to create an OEDesignUnit from :file:`1HHP_AB__DU__biounit.oedu` using
the site defined in the reference structure. The output is a single OEDesignUnit (.oedu): :file:`1HHP_AB_DU_apo_ASP_B-25.oedu`.

Instead of a fully prepared OEDesignUnit file as a reference, one may simply specify the site residues required to define the new site of interest.

So for example:

.. code-block:: bash

   prompt> enumsites -site_residue "ASP:25: :A" -in 1HHP_AB__DU__biounit.oedu

will construct an OEDesignUnit based on enumeration from the same biounit OEDesignUnit file as before (:file:`1HHP_AB__DU__biounit.oedu`), but here the definition of
the site comes from the :option:`-site_residue` option instead of another fully-prepared OEDesignUnit.

To calculate the Iridium classification as a metric of structure quality with ``enumsites``, one must provide the map file that corresponds to
experiment from which the biomolecular structure was derived:

.. code-block:: bash

   prompt> enumsites -site_residue "MET:124: :A" -map 1a29_validation_2fo-fc_map_coef.cif.gz -in 1A29_A__DU__biounit.oedu

Here two OEDesignUnit files (:file:`1A29_A__DU__TFP_A-153.oedu` and :file:`1A29_A__DU__TFP_A-154.oedu`) will be produced from :file:`1A29_A__DU__biounit.oedu` and the site defined
as ``MET:124: :A``, but the Iridium classification can be made since the structure factor CIF file (:file:`1a29_validation_2fo-fc_map_coef.cif.gz`) was passed in through the :option:`-map` option. The two files are resulting
from the two different ligands binding in that site simultaneously.

.. note::

   The :option:`-map` option accepts structure factor CIF files (``.cif``, ``.cif.gz``) as provided by
   :ref:`GetStructure <chapter_getstructure>` and the RCSB, as well as legacy MTZ files (``.mtz``).

To prevent continually over-writing output files, the :option:`-prefix` flag
allows you to give unique names to these files.

.. code-block:: bash

   prompt> enumsites -site_residue "ASP:25: :A" -in 1HHP_AB__DU__biounit.oedu -prefix FOO

will write the output structure into a file named :file:`FOO_1HHP_AB__DU__apo_ASP_A-25.oedu`.



.. _enumsites_help:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: enumsites

======================
Command Line Help
======================

A description of the commandline interface can be obtained by executing **EnumSites**
with the `--help` option.

.. code-block:: bash

   prompt> enumsites --help

will generate the following output:

::

   Help functions:
     enumsites --help simple      : Get a list of simple parameters
     enumsites --help all         : Get a complete list of parameters
     enumsites --help defaults    : List the defaults for all parameters
     enumsites --help <parameter> : Get detailed help on a parameter
     enumsites --help html        : Create an html help file for this program
     enumsites --help version     : List the toolkits and versions used in the application



.. _enumsites_req_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: enumsites

======================
Required Parameters
======================

.. option:: -in <filename>

   File containing a biounit OEDesignUnit that whose active site will be enumerated based on the input reference or site residues input.

   File format for :option:`-in` can be one of:

   ============= ===========================
   File type     Extension
   ============= ===========================
   OEDesignUnit  .oedu
   ============= ===========================

   [keyless parameter 1]

.. option:: -ref <filename>

   File containing an OEDesignUnit with a site defined that can be used as a reference structure.

   File format for :option:`-ref` can be one of:

   ============= ===========================
   File type     Extension
   ============= ===========================
   OEDesignUnit  .oedu
   ============= ===========================

   **NOTE:** Either :option:`-ref` or :option:`-site_residue` must be set, but not both.

.. option:: -site_residue <filename>

   String containing one or more comma-separated residue strings that have the following format:

   "RESIDUE_NAME:RESIDUE_NUMBER:INSERTION_CODE:CHAIN_ID"

   As an example, this is what the string would look like for an asparagine residue, at position 25, with a blank insertion code, on chain A.
   "ASP:25: :A"

   **NOTE:** Either :option:`-site_residue` or :option:`-ref` must be set, but not both.


.. _enumsites_opt_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: enumsites

=======================
Optional Parameters
=======================

Input Options
--------------

.. option:: -map <filename>

   Input electron density map from X-ray crystallography, to be used for Iridium score calculation.

   Accepted formats are structure factor CIF files (``.cif``, ``.cif.gz``) and
   legacy MTZ files (``.mtz``). See :ref:`OESystem_OEReadMTZ` in the
   **OEChem TK** manual for MTZ map and column conventions.

.. option:: -ref <filename>

   Reference OEDesignUnit indicating the proper biological unit and relevant binding site.

.. option:: -site_residue <residue identifier>

   Input option to specify a binding site using a single residue specification if apo (or holo).
   The format is "name:num:insert code:chainid", e.g. "ASP:25: :A" indicating Aspartic acid 25 in chain A. Note: A blank/whitespace
   character is used for the insert code, which is a typical use case.

Output Options
--------------

.. option:: -prefix <prefix>

   Prefix used to name output files, default is blank

.. option:: -log <logfile>

   The argument for this flag specifies the name of
   the log file. This overrides any specified prefix.
   The default will be enumsites_output.log, if no prefix is specified.

.. option:: -settings_file <settingsfile>

   (Alias: -settings)

   The argument for this flag specifies the name of
   the settings file. This overrides any specified prefix.
   The default will be enumsites_settings.param, if no prefix is specified.

.. option:: -verbose

   Triggers copious logging output

Enumerate Sites Parameters
--------------------------

.. option:: -add_interactions

   Option to add OEInteractionHints to the design unit(s)

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetAddInteractionHints <OESpruce_OEDesignUnitEnumerateSitesOptions_SetAddInteractionHints>` in the **Spruce TK** manual.

.. option:: -add_style

   Option to add visualization style to the design unit(s)

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetAddStyle <OESpruce_OEDesignUnitEnumerateSitesOptions_SetAddStyle>` in the **Spruce TK** manual.

.. option:: -collapse_nonsite_alts

   Option to deduplicate structures with different alternate locations if those alternate locations
   are far from the binding site

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetCollapseNonSiteAlts <OESpruce_OEDesignUnitEnumerateSitesOptions_SetCollapseNonSiteAlts>` in the **Spruce TK** manual.

.. option:: -duplicate_removal

   Option to deduplicate identical structures resulting from symmetry operations

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetDuplicateRemoval <OESpruce_OEDesignUnitEnumerateSitesOptions_SetDuplicateRemoval>` in the **Spruce TK** manual.

.. option:: -enum_cofactors_sites

   Option to generate design units with sites based on components classified as co-factors

   [Default=false]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetEnumerateCofactorSites <OESpruce_OEDesignUnitEnumerateSitesOptions_SetEnumerateCofactorSites>` in the **Spruce TK** manual.

.. option:: -restrict_to_refsite

   Option to skip generating design units for sites identified, that do not match a provided reference design unit

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetRestrictToRefSite <OESpruce_OEDesignUnitEnumerateSitesOptions_SetRestrictToRefSite>` in the **Spruce TK** manual.

.. option:: -site_size <value>

   Distance from the ligand used to determine the size of the site

   [Default=5.0 (angstroms)]

   .. seealso::

      * :ref:`OESpruce::OEDesignUnitEnumerateSitesOptions::SetSiteSize <OESpruce_OEDesignUnitEnumerateSitesOptions_SetSiteSize>` in the **Spruce TK** manual.

.. option:: -superpose

   Option to superpose generated design units, if multiple. If a reference is provided, the first generated
   design unit will be superposed onto the reference structure, and subsequent structures onto that one.

   [Default=true]

   .. seealso::

      * :ref:`OESpruce::OEMakeDesignUnitOptions::SetSuperpose <OESpruce_OEMakeDesignUnitOptions_SetSuperpose>` in the **Spruce TK** manual.

.. option:: -superpose_method <method>

   The method to use for superposition

   ==============  ======================================================================================
   Method          Description
   ==============  ======================================================================================
   global          Global Sequence Alignment to identify CA pairs
   --------------  --------------------------------------------------------------------------------------
   site            Global Sequence Alignment to identity CA pairs - focusing on the subset in active site
   --------------  --------------------------------------------------------------------------------------
   ddm             Superposition using the Distance Difference Matrix method (DDM)
   --------------  --------------------------------------------------------------------------------------
   sse             Superposition using an overlap of Secondary Structure Elements (SSE)
   --------------  --------------------------------------------------------------------------------------
   weighted        Superposition weighting residues by B-factor or occupancy
   --------------  --------------------------------------------------------------------------------------
   sitehopper      Superposition based on binding site similarities (sitehopper)
   --------------  --------------------------------------------------------------------------------------
   GlobalSequence  Alias for global — Global Sequence Alignment to identify CA pairs
   --------------  --------------------------------------------------------------------------------------
   DDMatrix        Alias for ddm — Superposition using the Distance Difference Matrix method
   --------------  --------------------------------------------------------------------------------------
   SiteSequence    Alias for site — Global Sequence Alignment focusing on the active site
   ==============  ======================================================================================

   .. seealso::

      * :ref:`OESpruce::OEMakeDesignUnitOptions::SetSuperpositionMethod <OESpruce_OEMakeDesignUnitOptions_SetSuperpositionMethod>` in the **Spruce TK** manual.


.. _chapter_getstructure:

*********************************
GetStructure
*********************************

.. toctree::
   :maxdepth: 2

   getstructure_overview
   getstructure_example


.. _getstructure_overview:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: getstructure

======================
Overview
======================

:ref:`GetStructure <chapter_getstructure>` is a simple application to download structure files from the RCSB servers for a given PDB code.

Input for the application is the 4-character PDB code identifying the structure. By default, the following files are downloaded if available:

- **MMCIF** (``.cif.gz``): the structure in mmCIF format
- **Structure factor CIF** (``_validation_2fo-fc_map_coef.cif.gz``): 2Fo-Fc map coefficient file for X-ray structures
- **CryoEM map** (``.map.gz``) and **header** (``.xml``): density map and metadata for cryo-EM structures

The legacy PDB format (``.pdb.gz``) can be requested with the ``-pdb`` flag. The Fo-Fc structure factor file (``_validation_fo-fc_map_coef.cif.gz``) can be requested with the ``-fofc`` flag.

.. note::

   GetStructure downloads structure factor **CIF** files, not MTZ files.

.. note::

  On macOS and RHEL 8, the user has to install openSSL 1.1 for the application to work.
  To install openssl on macOS we recommend using HomeBrew (https://brew.sh/), and the command: 
  ``brew install openssl@1.1``

  Or, if you are using a conda environment, specify the openssl version with:

  conda install openssl=1.1 -y

  GetStructure is not supported on RedHat 9 and Windows 11 at this time due to an incompatibility with openSSL 1.1


.. _getstructure_example:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: getstructure

======================
Example Commands
======================

The **getstructure** utility program is run by passing in a 4-letter PDB code:

.. code-block:: bash

   prompt> getstructure 4OBD

Here, **getstructure** will download :file:`4obd.cif.gz` (mmCIF structure) and
:file:`4obd_validation_2fo-fc_map_coef.cif.gz` (2Fo-Fc structure factor CIF) for X-ray structures.

To also download the legacy PDB format and the Fo-Fc structure factor file:

.. code-block:: bash

   prompt> getstructure -pdb -fofc 4OBD

This additionally downloads :file:`4obd.pdb.gz` and :file:`4obd_validation_fo-fc_map_coef.cif.gz`.

For cryo-EM structures, **getstructure** downloads the mmCIF file along with the associated
EMDB density map (``.map.gz``) and header (``.xml``) instead of structure factor CIF files.

.. _chapter_loopdb_builder:

*********************************
LoopDBBuilder
*********************************

.. toctree::
   :maxdepth: 2

   loopdb_builder_overview
   loopdb_builder_example
   loopdb_builder_help
   loopdb_builder_req_params
   loopdb_builder_opt_params


.. _loopdb_builder_overview:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: loopdb_builder

======================
Overview
======================

:ref:`loopdb_builder <chapter_loopdb_builder>` is an application to build a database of loops in known structures, that
can subsequently be used in :ref:`Spruce <chapter_spruce>` to modeling missing loops.

Input for the application is a directory of PDB structures. An existing database can be appended to as new structures become
available. OpenEye ships a pre-built database, which can be added to with internal/proprietary structures.

Loops are extracted from the structures in a sliding window producing loops of length 4, to the maximum length of a loop specified (default 22).
The extracted loops are deduplicated so a loop with an identical sequence, rough distance between the anchor atoms, and similar backbone shape are
only included once. The option to exclude "loops" with a regular secondary structure content (helix,strand) of >75% is on by default but can be turned off.
The crop length removes N number of residues at the different termini of the protein structure before processing, knowing that the terminal residues
are often flexible and poorly resolved in crystal structures, the default value is 1.


.. _getstructure_example:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: loopdb_builder

======================
Example Commands
======================

The **loopdb_builder** utility program is run by specifying a directory containing PDB files and a name of the source of the data

.. code-block:: bash

   prompt> loopdb_builder -in PDB_DIR -source_name RCSB -prefix rcsb

Here, **loopdb_builder** will build a database of the loops in the structures provided in the directory.
The resulting file will be named `rcsb_spruce.loop_db`.



.. _loopdb_builder_help:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: loopdb_builder

======================
Command Line Help
======================

A description of the commandline interface can be obtained by executing **loopdb_builder**
with the `--help` option.

.. code-block:: bash

   prompt> loopdb_builder --help

will generate the following output:

::

   Help functions:
     loopdb_builder --help simple      : Get a list of simple parameters
     loopdb_builder --help all         : Get a complete list of parameters
     loopdb_builder --help defaults    : List the defaults for all parameters
     loopdb_builder --help <parameter> : Get detailed help on a parameter
     loopdb_builder --help html        : Create an html help file for this program
     loopdb_builder --help version     : List the toolkits and versions used in the application



.. _loopdb_builder_req_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: loopdb_builder

======================
Required Parameters
======================

.. option:: -in <directory>

   Directory containing PDB files that will be processed for known loops

.. option:: -source_name <value>

   Source name of the files, e.g. RCSB, EBI, PDBJ, or internal/proprietary sources.



.. _loopdb_builder_opt_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: loopdb_builder

=======================
Optional Parameters
=======================

.. option:: -append <bool>

   Option to append to current loop dictionary with additional structures, otherwise will fail if output DB exists

   [Default=false]

.. option:: -title <title>

   Title of the added structures, e.g. "Loops of aspartic acid protease structures"

   [Default=LoopTemplateDatabase]

.. option:: -source_date <value>

   Date the source was updated in the format MM-DD-YYYY. Defaults to today's date.

.. option:: -ncpu <value>

   Number of processors to run with, 0  means all available.

   [Default=0]

.. option:: -max_length <value>

   Max length of loops to add to the database. Note to add a buffer for necessary crop back in loop modeling

   [Default=22]

.. option:: -crop_length <value>

   Crop back this number of residues at the termini/breaks for each structure being evaluated

   [Default=2]

   .. seealso::

      * :ref:`OESpruce::OELoopBuilderOptions::SetCropLength <OESpruce_OELoopBuilderOptions_SetCropLength>` in the **Spruce TK** manual.

.. option:: -exclude_reg_ss <value>

   Exclude sections with >75% regular secondary structures like helices and strand/sheets.

   [Default=true]

.. option:: -prefix <prefix>

   Prefix used to name output files, default is blank

.. option:: -log <logfile>

   The argument for this flag specifies the name of
   the log file. This overrides any specified prefix.

.. option:: -settings_file <settingsfile>

   The argument for this flag specifies the name of
   the settings file. This overrides any specified prefix.
   [Aliases=**-settings**]

.. option:: -skip_file <filename>

   File containing PDB codes to skip, one code per line

.. option:: -verbose

   Triggers copious logging output


.. _chapter_du2pdb:

*********************************
DU2PDB
*********************************

.. toctree::
   :maxdepth: 2

   du2pdb_overview
   du2pdb_example
   du2pdb_help
   du2pdb_req_params
   du2pdb_opt_params


.. _du2pdb_overview:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: du2pdb

======================
Overview
======================

:ref:`du2pdb <chapter_du2pdb>` is a simple utility application to convert DesignUnit OEDU files to PDB files.


.. _du2pdb_example:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: du2pdb

======================
Example Commands
======================

The **du2pdb** utility program is run by specifying a directory containing PDB files and a name of the source of the data

.. code-block:: bash

   prompt> du2pdb -in 5YE9_B__DU__8U6_B-501.oedu

Here, **du2pdb** will convert the OEDU file to 5YE9_B__DU__8U6_B-501.pdb, by default it will not include packing residues



.. _du2pdb_help:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: du2pdb

======================
Command Line Help
======================

A description of the commandline interface can be obtained by executing **du2pdb**
with the `--help` option.

.. code-block:: bash

   prompt> du2pdb --help

will generate the following output:

::

   Help functions:
     du2pdb --help simple      : Get a list of simple parameters
     du2pdb --help all         : Get a complete list of parameters
     du2pdb --help defaults    : List the defaults for all parameters
     du2pdb --help <parameter> : Get detailed help on a parameter
     du2pdb --help html        : Create an html help file for this program
     du2pdb --help version     : List the toolkits and versions used in the application


.. _du2pdb_req_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: du2pdb

======================
Required Parameters
======================

.. option:: -in <filename>

   Input OEDesignUnit file to be converted

   File format for :option:`-in` can be one of:

   ============= ===========================
   File type     Extension
   ============= ===========================
   OEDesignUnit  .oedu
   ============= ===========================

   [keyless parameter 1]



.. _du2pdb_opt_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: du2pdb

=======================
Optional Parameters
=======================

InputOutput Options
-------------------

.. option:: -includePackingResidues

   Option to add include packing residues in the conversion

   [Default=false]

.. option:: -prefix <prefix>

   Prefix used to name output files, default is blank

.. option:: -log <logfile>

   The argument for this flag specifies the name of
   the log file. This overrides any specified prefix.
   The default will be du2pdb_output.log, if no prefix is specified.

.. option:: -settings_file <settingsfile>

   (Alias: -settings)

   The argument for this flag specifies the name of
   the settings file. This overrides any specified prefix.
   The default will be du2pdb_settings.param, if no prefix is specified.

.. option:: -verbose

   Triggers copious logging output

   [Default=false]


.. _chapter_du2mmcif:

*********************************
du2mmcif
*********************************

.. toctree::
   :maxdepth: 2

   du2mmcif_overview
   du2mmcif_example
   du2mmcif_help
   du2mmcif_req_params
   du2mmcif_opt_params


.. _du2mmcif_overview:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: du2mmcif

======================
Overview
======================

:ref:`du2mmcif <chapter_du2mmcif>` is a simple utility application to convert DesignUnit OEDU files to MMCIF files.


.. _du2mmcif_example:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: du2mmcif

======================
Example Commands
======================

The **du2mmcif** utility program is run by specifying a directory containing MMCIF files and a name of the source of the data

.. code-block:: bash

   prompt> du2mmcif -in 5YE9_B__DU__8U6_B-501.oedu

Here, **du2mmcif** will convert the OEDU file to 5YE9_B__DU__8U6_B-501.cif, by default it will not include packing residues



.. _du2mmcif_help:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: du2mmcif

======================
Command Line Help
======================

A description of the commandline interface can be obtained by executing **du2mmcif**
with the `--help` option.

.. code-block:: bash

   prompt> du2mmcif --help

will generate the following output:

::

   Help functions:
     du2mmcif --help simple      : Get a list of simple parameters
     du2mmcif --help all         : Get a complete list of parameters
     du2mmcif --help defaults    : List the defaults for all parameters
     du2mmcif --help <parameter> : Get detailed help on a parameter
     du2mmcif --help html        : Create an html help file for this program
     du2mmcif --help version     : List the toolkits and versions used in the application


.. _du2mmcif_req_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: du2mmcif

======================
Required Parameters
======================

.. option:: -in <filename>

   Input OEDesignUnit file to be converted

   File format for :option:`-in` can be one of:

   ============= ===========================
   File type     Extension
   ============= ===========================
   OEDesignUnit  .oedu
   ============= ===========================

   [keyless parameter 1]



.. _du2mmcif_opt_params:
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: du2mmcif

=======================
Optional Parameters
=======================

InputOutput Options
-------------------

.. option:: -includePackingResidues

   Option to add include packing residues in the conversion

   [Default=false]

.. option:: -prefix <prefix>

   Prefix used to name output files, default is blank

.. option:: -log <logfile>

   The argument for this flag specifies the name of
   the log file. This overrides any specified prefix.
   The default will be du2mmcif_output.log, if no prefix is specified.

.. option:: -settings_file <settingsfile>

   (Alias: -settings)

   The argument for this flag specifies the name of
   the settings file. This overrides any specified prefix.
   The default will be du2mmcif_settings.param, if no prefix is specified.

.. option:: -verbose

   Triggers copious logging output

   [Default=false]


.. _spruce_releasenotes:

Release History
===============

.. toctree::
   :maxdepth: 3

   version1_9_0
   version1_8_0
   version1_7_0
   version1_6_1
   version1_6_0
   version1_5_3
   version1_5_2
   version1_5_1
   version1_5_0
   version1_4_0      
   version1_3_0
   version1_2_0
   version1_1_0_1
   version1_1_0
   version1_0_0


#################
SPRUCE 1.8.0
#################

****************************************
New Features
****************************************

* The **SPRUCE** application can now read structure factor CIF files for electron
  density maps.

* The **GetStructure** utility application now downloads structure factor CIF files in
  place of MTZ files, which were deprecated by the wwPDB/RCSB.

* The **GetStructure** utility application can now download cryoEM maps and the related XML file,
  which stores the author-recommended contour value.

****************************************
Minor Bug Fixes
****************************************

* An issue has been fixed where some parameters were shown as required that were not required.

****************************************
Related Toolkit Information
****************************************



Spruce TK 1.8.0
================================================================================

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

*  The function :ref:`OEBuildSingleLoop <OESpruce_OEBuildSingleLoop>` now checks for
   loop clashes after minimization. The option can be set using
   :ref:`SetRejectClashingLoopsPostMinimization <OESpruce_OELoopBuilderOptions_SetRejectClashingLoopsPostMinimization>`.

*  The function :ref:`OEBuildSingleLoop <OESpruce_OEBuildSingleLoop>` can now delete
   residues already present at sites where a new loop needs to be built. The option can be set using
   :ref:`SetDeleteExistingResidues <OESpruce_OELoopBuilderOptions_SetDeleteExistingResidues>`.

*  The function :ref:`OEBuildSidechains <OESpruce_OEBuildSidechains>` can now partially
   build target residues in the event that some targets fail.

*  Improved loop modeling has been added involving disulfide bridge creation by adding a bond length check.

*  When running with :ref:`SetFixResStates <OESpruce_OESpruceFilterOptions_SetFixResStates>` set to True, if the input molecule contains
   CIF header data, the filter will utilize the chemical component header section to inform
   a residue's bond order and subsequent formal charge.

*  A new method, :ref:`SetUseSeqScoreChainMatching <OESpruce_OESuperposeOptions_SetUseSeqScoreChainMatching>`, has been
   added to :ref:`OESuperposeOptions <OESpruce_OESuperposeOptions>` which, when enabled, optimizes the sequence score over the
   overall RMSD when matching on multiple protein chains.

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

*  An issue has been fixed where gaps in the protein structure were misidentified due to
   unconventional insert code usage.

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

*  Loop modeling results have been improved by setting
   :ref:`OELoopBuilderOptions StrictProlineMatch <OESpruce_OELoopBuilderOptions_GetStrictProlineMatch>`
   to ``False`` by default. The updated default is due to an improved side chain building routine
   in a prior toolkit release.

*  An issue has been fixed to ensure loops extracted from the loop database had the desired structural properties.

*  When truncating a residue or converting a residue to a capping group,
   if that residue had a crosslink bond, the residue opposite would retain an atom in a bad valence state.
   That issue has been fixed.

*  An issue has been fixed in the routine to reassign ambiguous water and metals
   from packing residues to the protein chain of interest. The issue caused HEME-analogs and connected amino acids
   to be soaked into a given chain ID.

*  An issue has been fixed causing loop-relevant information with insert codes in an mmCIF header to be incorrectly read.

*  The :ref:`OECapCTermini <OESpruce_OECapCTermini>`, :ref:`OECapNTermini <OESpruce_OECapNTermini>`,
   and :ref:`OECapTermini <OESpruce_OECapTermini>`
   functions address an issue that could result in an incorrectly labeled cap residue SequenceID.

*  Several improvements were made to address performance issues in the :ref:`OESpruceFilter <OESpruce_OESpruceFilter>`.

Documentation Changes
--------------------------------------------------------------------------------

* Several examples have been added, and the advanced protein preparation tutorial has been expanded.



######################
SPRUCE 1.7.0
######################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


Spruce TK 1.7.0
================================================================================

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

*  The functions :ref:`OEMakeDesignUnit <OESpruce_OEMakeDesignUnit>` and :ref:`OEMakeBioDesignUnits <OESpruce_OEMakeBioDesignUnits>` will now use provided
   `OEHeterogenMetadata` in `OEStructureMetadata` as information for the splitting 
   of a structure into a design unit, including such details as which parts should be considered cofactors.

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

*  An issue has been fixed that caused charge and radii assignment to not happen, in paths
   where **Spruce** was also not allowed to protonate the structure.

*  An issue has been fixed that caused radii to not be properly assigned to all atoms in the design unit.

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

*  An issue has been fixed which caused some mmCIF files to not be able to be
   prepared due to lack of missing metadata.

*  An issue has been fixed where :ref:`OEMutateResidues <OESpruce_OEMutateResidues>` would crash if the structure contained
   the N-terminal capping group `NME`.





SPRUCE  1.6.1
================================================================================

New features
--------------------------------------------------------------------------------
* Command line arguments have been added to control the gap and extend penalties for the sequence
  alignment used for loop building.

..  _section_sprucetk_releasenotes_1611:

Spruce TK 1.6.1.1
================================================================================

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

*   An issue has been fixed where :ref:`OEExtractBioUnits <OESpruce_OEExtractBioUnits>` function
    would fail if there was a mismatch in author assigned chain names and PDB assigned chain names
    in the case where a molecule was extracted from an mmCIF file.

*   An issue was fixed in :ref:`OEProtonateDesignUnit <OESpruce_OEProtonateDesignUnit>` where a rule to flip clashing
    in-plane hydrogens on double bonded nitrogens was triggering incorrectly in specific instances.
    

Spruce TK 1.6.1
================================================================================

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

*   :ref:`OEBuildSidechains <OESpruce_OEBuildSideChains>` now minimizes target side chains by default. Minimization can
    be controlled by setting :ref:`minimizeSidechains <OESpruce_OESidechainBuilderOptions_SetMinimizeSidechains>` and
    :ref:`minimizeSidechainsShell <OESpruce_OESidechainBuilderOptions_SetMinimizeSidechainsShell>`
    options in the :ref:`OESidechainBuilderOptions <OESpruce_OESidechainBuilderOptions>` class.

*   A feature has been added to support a next generation mmCIF feature, such that when an mmCIF
    file provides a connectivity record for the heterogens, **Spruce** will no longer look
    up the heterogen in the Chemical Component Dictionary but trust the input provided.

*   A feature has been added that allows in-plane flipping of a single hydrogen on a double bonded nitrogen,
    when a clash is detected as part of hydrogen bond network optimization.

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

*   An issue has been fixed related to using the :ref:`OEHeterogenMetadata <OESpruce_OEHeterogenMetadata>` class, where
    the provided SMILES string was
    not respected for tautomer generation; when tautomers were not provided; and when the title (residue name)
    collided with existing residue names in the stored Chemical Component Dictionary.

*   An issue has been fixed related to covalently bound ligands, where the pre-reaction input SMILES and related tautomers
    were not adjusted properly when accounting for the formed covalent bond.

*   An issue has been fixed where the **Spruce** filter deleted single (disconnected) amino acid residues
    when they were marked HETATMs and were not real "floating" residues in part of the regular protein sequence.

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

*   :ref:`OEMutateResidues <OESpruce_OEMutateResidues>`,
    :ref:`OEMutateResidue <OESpruce_OEMutateResidue>`,
    and :ref:`OEBuildSidechains <OESpruce_OEBuildSideChains>` now reduce failures arising from
    clashes by using shell minimization by default.

*   An issue has been fixed that caused HEME-like molecules to be excluded from
    the stored chemical component database.

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

*   Information has been added about setting and getting minimizeSidechains and minimizeSidechainsShell
    options in the :ref:`OESidechainBuilderOptions <OESpruce_OESidechainBuilderOptions>` class.






SPRUCE  1.6.0
================================================================================

Minor internal improvements have been made.



Spruce TK 1.6.0
================================================================================

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

* The chemical components dictionary has been updated with latest structures from
  the wwPDB.

* A feature has been added to :ref:`OEProtonateDesignUnit <OESpruce_OEProtonateDesignUnit>` to detect
  acceptor–acceptor clashes, modify the protonation state of one of the moieties,
  and reoptimize the hydrogen bond network.

* The following preliminary API classes have been made permanent.

  * :ref:`OECapBuilderOptions<OESpruce_OECapBuilderOptions>`
  * :ref:`OELoopBuilderOptions<OESpruce_OELoopBuilderOptions>`
  * :ref:`OEPocket<OESpruce_OEPocket>`
  * :ref:`OEPocketOptions<OESpruce_OEPocketOptions>`
  * :ref:`OESidechainBuilderOptions<OESpruce_OESidechainBuilderOptions>`
  * :ref:`OESpruceFilter<OESpruce_OESpruceFilter>`
  * :ref:`OESpruceFilterOptions<OESpruce_OESpruceFilterOptions>`
  * :ref:`OEValidateDesignUnit<OESpruce_OEValidateDesignUnit>`

* The following preliminary API functions have been made permanent.

  * :ref:`OEBuildLoops<OESpruce_OEBuildLoops>`
  * :ref:`OEBuildSingleLoop<OESpruce_OEBuildSingleLoop>`
  * :ref:`OEFindPockets<OESpruce_OEFindPockets>`
  * :ref:`OEMakeDesignUnitFromPocket<OESpruce_OEMakeDesignUnitFromPocket>`

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

* A crash in :ref:`OESpruceFilter <OESpruce_OESpruceFilter>` has been fixed in relation
  to atoms that were cleaned up during the standardization process.

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

* An issue has been fixed that ensures radii are assigned to all atoms in a design unit.

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

* An example has been added showing how to convert FASTA files to structure metadata
  for structures missing the SEQRES information in the PDB metadata and MMCIF equivalent.






SPRUCE  1.5.3
================================================================================

Minor internal improvements have been made.


Spruce TK 1.5.3
================================================================================

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

* The chemical components dictionary was updated with latest data from the RCSB.

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

* An issue that caused :ref:`OESpruceFilter <OESpruce_OESpruceFilter>` to segfault has been fixed and safeguarded.

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

* An issue  has been fixed that caused incorrectly built loops when the protein structure contains
  nonstandard amino acids, particularly in the gap needing to be built or anchoring to it.

* An issue with sequence mutation for cysteine residues, where an explicit hydrogen was left
  over after the mutation, has been fixed.




.. _section_spruce_releasenotes_1521:

SPRUCE  1.5.2.1
================================================================================

* Legal values for the `targetMask` flag have been added to docs and command-line help.

SPRUCE  1.5.2.0
================================================================================

Minor internal improvements have been made.



Spruce TK 1.5.2
================================================================================

New features
--------------------------------------------------------------------------------
* :ref:`OESpruceFilterOptions <OESpruce_OESpruceFilterOptions>` has an option 
  to automatically assign chain IDs (default is true) when they are missing 
  either completely or partially in the structure for a structure processed 
  by :ref:`OESpruceFilter <OESpruce_OESpruceFilter>`.

* The built-in heterogen database has been updated with the latest structures
  from the ligand-expo at the RCSB.

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

* An issue where tautomers passed using metadata were not respected has been fixed.

* An issue has been fixed where, in a small fraction of cases, an OXT atom was
  not correctly built out when needed at the protein C-terminals.

* An issue has been fixed where the option to fix the state of backbone atoms and bonds
  in :ref:`OESpruceFilterOptions <OESpruce_OESpruceFilterOptions>` was sometimes not respected
  in :ref:`OESpruceFilter <OESpruce_OESpruceFilter>`, which led to issues such as OXT
  atoms being built even if the option was disabled.


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

* An issue was fixed in filter options to not accept the disallowed
  residue names UNL and UNK. Instead, they are renamed to LIG, which is a change
  filter that applies in the structure upon standardization.

* An issue where the maximum number of atoms in the biological unit
  was not being respected has been fixed.

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

* Minor documentation and example improvements have been fixed.



SPRUCE  1.5.1
================================================================================

*Fall 2022*

New features
--------------------------------------------------------------------------------
* When providing a site-residue to Spruce, the output title and output filenames 
  of apo design units will now use that site residue in the name. Previously,  the residue closest to the center of the binding site was used.



Spruce TK 1.5.1
================================================================================

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

* If a site residue is provided to :ref:`OEMakeDesignUnits <OESpruce_OEMakeDesignUnits>`, the
  output design unit title now includes the site residue in the title for apo structures.
  Previously, the residue in the title was the residue closest to the center of the binding site.

* Standardization using :ref:`Spruce Filter <OESpruce_OESpruceFilter>` now checks for metal chelation 
  before forming disulfide bridges.

Major bug fixes
--------------------------------------------------------------------------------
* An issue causing accumulation of generic data on the molecule components stored in
  the design unit object during prep has been fixed. This accumulation led to large memory consumption,
  slow preparation, and larger file size.




SPRUCE  1.5.0
================================================================================

*Spring 2022*

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

* **Spruce** has been enhanced to perform standardization and a filter checks before Spruce preparation.
  
  The following are detected and fixed:
    * invalid component names
    * invalid residue states
    * invalid metal bonds

  The following are detected and fail the structure:
    * invalid CRYST1 from header file
    * low overlap between the electron density map and the structure
    * invalid sequence alignment
    * blank Chain IDs
    * invalid alternate locations

* **Spruce** has been enhanced to perform checks on the generated design unit after running Spruce preparation.

  Issues detected and reported include:
    * partial side chains
    * missing loops
    * implicit hydrogens
    * incorrect partial charges
    * termini that are not capped properly
    * heavy atoms overlapping with each other
    * broken chains

* A new command line option ``-enum_pockets`` has been added.
  When enabled it automatically detects pockets and generates design units from them.    

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

* An issue with the value of the parameter ``-min_align_score`` not being properly
  respected has been fixed.



Spruce TK 1.5.0
================================================================================

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

* The new :ref:`OESpruceFilter <OESpruce_OESpruceFilter>` class has been added to provide checks and corrections on input to **Spruce**.
  For input it can take an :ref:`OEMolBase <OEChem_OEMolBase>`, :ref:`OEStructureMetadata <OESpruce_OEStructureMetadata>`,
  or an options class, :ref:`OESpruceFilterOptions <OESpruce_OESpruceFilterOptions>`, that holds the options to turn on each of the fixing options.

* The new :ref:`OEValidateDesignUnit <OESpruce_OEValidateDesignUnit>` class has been added for validation of **Spruce** produced design units.
  For input it can take an :ref:`OEDesignUnit <OEBio_OEDesignUnit>` or
  :ref:`OEStructureMetadata <OESpruce_OEStructureMetadata>`.


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

* A bug that caused memory leaks in  **OEBio TK** has been fixed.

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

* An issue was fixed in :ref:`OEBuildLoops <OESpruce_OEBuildLoops>` to allow better
  sequence alignment for peptides. 
  
* An issue was fixed in :ref:`OEBuildLoops <OESpruce_OEBuildLoops>` where free amino acids,
  as co-factors or ligands, were incorrectly included in sequence alignments and
  causing mismatched alignments to the SEQRES.

* An issue was fixed in :ref:`OEExtractBioUnits <OESpruce_OEExtractBioUnits>` to be able to lower
  the minimum sequence alignment score threshold.







SPRUCE  1.4.0
================================================================================

*Fall 2021*

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

* The application :ref:`loopdb_builder<chapter_loopdb_builder>` now reads ``MMCIF`` 
  files. If the same structure is available in
  both ``PDB`` and ``MMCIF`` format in the provided directory, the ``PDB`` file is used.

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

* A minor bugfix affecting stability of the :ref:`loopdb_builder<chapter_loopdb_builder>` has been fixed.

Spruce TK 1.4.0
================================================================================

*Fall 2021*

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

* A new method, :ref:`SetForceCapping <OESpruce_OECapBuilderOptions_SetForceCapping>`, has been added
  to enable capping even if it will result in a clash.

* Two new methods, :ref:`SetBuildTails <OESpruce_OELoopBuilderOptions_SetBuildTails>` and
  :ref:`GetBuildTails <OESpruce_OELoopBuilderOptions_GetBuildTails>`, have been added
  to set and get an option that
  controls whether to build tails when there is missing residues at the N- and C- termini.

* :ref:`SiteHopper <OESpruce_OESuperposeMethod_SiteHopper>` is now a supported superposition method in
  :ref:`OESuperpose <OESpruce_OESuperpose>`, and can be set using the SetMethod method of :ref:`OESuperpose <OESpruce_OESuperpose>`.

* All Options classes have been modified to derive from :ref:`OEOptions <OESystem_OEOptions>`. This affects classes:

  * :ref:`OEDesignUnitEnumerateSitesOptions <OESpruce_OEDesignUnitEnumerateSitesOptions>`
  * :ref:`OEProtonateDesignUnitOptions <OESpruce_OEProtonateDesignUnitOptions>`
  * :ref:`OEDesignUnitBuildOptions <OESpruce_OEDesignUnitBuildOptions>`
  * :ref:`OEDesignUnitPrepOptions <OESpruce_OEDesignUnitPrepOptions>`
  * :ref:`OEDesignUnitSplitOptions <OESpruce_OEDesignUnitSplitOptions>`
  * :ref:`OEBioUnitExtractionOptions <OESpruce_OEBioUnitExtractionOptions>`
  * :ref:`OEMakeDesignUnitOptions <OESpruce_OEMakeDesignUnitOptions>`
  * :ref:`OEPlaceHydrogensOptions <OEBio_OEPlaceHydrogensOptions>`

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

* An issue causing capping a nonstandard residue to fail has been fixed.

* An issue causing covalent ligands to have their covalent bond broken when
  there were alternate locations in the structure, has been fixed.

* An issue causing side-chains to either not be built or being built in
  non-optimal configurations has been fixed.

* An issue with pockets identifying liganded sites in
  :ref:`OEMakeDesignUnitFromPocket <OESpruce_oemakedesignunitfrompocket>` not generating a proper
  design unit with a ligand bound in the identified site has been fixed.


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

* An issue causing the warning message 'Truncated cap due to clash' to appear when
  :ref:`SetAllowTruncate <OESpruce_OECapBuilderOptions_SetAllowTruncate>` is `False` has been fixed.

* An issue caused by Heuristic score offset being added before comparing to original 
  structure therefore unable to pick the more energy favorable conformation has been fixed.

* An issue causing the gap finding code to mis-identify gaps in the protein 
  structure due to residues with missing backbone atoms has been fixed.
  The function now removes these residues prior to gap detection inside 
  :ref:`OEBuildLoops <OESpruce_OEBuildLoops>`.

* An issue caused by malformed ``PDB`` Header data, specifically with regards to
  REMARK 300 sections, has been fixed.







SPRUCE  1.3.0
================================================================================

*July 2021*

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

* :ref:`getstructure <chapter_getstructure>` now retrieves structures using a secure HTTPS connection 
  using openSSL.

* A no-prep option has been added to **SPRUCE** to enable conversion of prepared
  structures into the OEDesignUnit format. This option supersedes all other
  options.

* An optional ``-out`` parameter has been added to **SPRUCE**, for specifying the output filename.
  **SPRUCE** can write multiple
  design units per PDB file, and the default option is to write all of them to the
  single specified file. An additional option ``-warts`` has been added that will postfix
  a #n (n being an incrementing number) to the output filename.

* An ``OEReceptor`` is now added by default when using **SPRUCE**. The feature can be turned off
  using the `-add_receptors false` flag. A -`targetMask` can be specified to
  augment the receptor content. Furthermore, these OEDesignUnits with receptors can be
  further edited in the :ref:`Make Receptor <chapter_makereceptor>` GUI application.
  
* Options for setting the RMSD, sequence alignment score, and Tanimoto thresholds
  for validating the superposition result have been added to :ref:`superposition <chapter_superposition>`.

* The names of the available superposition methods for :ref:`SPRUCE <chapter_spruce>`,
  :ref:`enumsites <chapter_enumsites>`, and
  :ref:`superposition <chapter_superposition>` have been unified.


Spruce TK 1.3.0
================================================================================

*July 2021*

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

* A molecule-based API for :ref:`OEMakeDesignUnitFromPocket <OESpruce_OEMakeDesignUnitFromPocket>` has been added.

* New high-level superposition APIs were added that unify the sequence-based
  (:ref:`OEStructuralSuperposition <OESpruce_OEStructuralSuperposition>`) and shape-based
  (:ref:`OESecondaryStructureSuperposition <OESpruce_OESecondaryStructureSuperposition>`) APIs. This includes a new
  :ref:`OESuperpose <OESpruce_OESuperpose>` class that can calculate different types of structural
  superposition, a new :ref:`OESuperposeOptions <OESpruce_OESuperposeOptions>` class that allows the users
  to control various behaviors of the superposition calculation, such as the superposition 
  method, and a new :ref:`OESuperposeResults <OESpruce_OESuperposeResults>` class that holds the transformation
  and scores of the superposition. More detailed changes are as follows:

  * The new :ref:`OESuperpose <OESpruce_OESuperpose>` class can take either :ref:`OEMol <OEChem_OEMol>` or
    :ref:`OEDesignUnit <OEBio_OEDesignUnit>` as the reference for the fit molecule. The reference molecule can be
    set by using the :ref:`SetupRef <OESpruce_OESuperPose_SetupRef>` method, and the superposition can be
    calculated via :ref:`OESuperpose <OESpruce_OESuperpose_Superpose>` with the fit molecule
    supplied as one of its arguments.

  * A new :ref:`OESuperposeMethod <OESpruce_OESuperposeMethod>` namespace was added that contains the constants
    for different superposition methods. Functions :ref:`OEGetSuperposeMethodName <OESpruce_OEGetSuperposeMethodName>`
    and :ref:`OEGetSuperposeMethodFromName <OESpruce_OEGetSuperposeMethodFromName>` were added to obtain the superposition
    method's name (as a string literal) from its designated constant and vice versa.

  * Methods
    :ref:`OESuperposeOptions <OESpruce_OESuperposeOptions_SetValidRMSD>`,
    :ref:`OESuperposeOptions <OESpruce_OESuperposeOptions_SetValidSeqScore>`, and
    :ref:`OESuperposeOptions <OESpruce_OESuperposeOptions_SetValidTanimoto>`
    have been added.  These methods can be used to set score thresholds for validating
    superposition results in the new
    :ref:`OESuperposeOptions <OESpruce_OESuperposeOptions>` class. The validity of the superposition result can be obtained
    by :ref:`OESuperposeResults <OESpruce_OESuperposeResults_IsValid>` from the new :ref:`OESuperposeResults <OESpruce_OESuperposeResults>`
    class.

  * The new :ref:`OESuperpose <OESpruce_OESuperpose>` API returns an :ref:`OESuperposeResults <OESpruce_OESuperposeResults>` object
    that can be used to transform the fit molecule to its superposed position with its 
    :ref:`Transform <OESpruce_OESuperposeResults_Transform>` method. Alternatively, the users can use
    :ref:`GetRotMatrix <OESpruce_OESuperposeResults_GetRotMatrix>` and :ref:`GetTranslation <OESpruce_OESuperposeResults_GetTranslation>`
    to obtain the rotation matrix and translation vector, respectively, for their analyses. The RMSD and 
    sequence alignment score after the superposition can be obtained using :ref:`OESuperposeResults <OESpruce_OESuperposeResults>`'s
    :ref:`GetRMSD <OESpruce_OESuperposeResults_GetRMSD>` and :ref:`GetSeqScore <OESpruce_OESuperposeResults_GetSeqScore>` methods
    for sequence-based superpositions, and the Tanimoto score can be obtained using 
    :ref:`GetTanimoto <OESpruce_OESuperposeResults_GetTanimoto>`.

  Please refer to the documentation for more information on these new superposition APIs.


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

* A bug that caused the loop modeling algorithm to crash in rare instances has been fixed.

* Examples have been modified to use appropriate command-line arguments.

* An issue that caused style on :ref:`OEDesignUnit <OEBio_OEDesignUnit>` objects to disappear when
  calling :ref:`OEProtonateDesignUnit <OESpruce_OEProtonateDesignUnit>` has been fixed.

* An issue with the return value of superposition when two structures cannot be superposed has been fixed.
  It now properly returns a -1.00 RMSD.

* An issue in :ref:`OEMakeDesignUnitFromPocket <OESpruce_OEMakeDesignUnitFromPocket>` that caused style
  to remain on both the previous binding site and the one defined from the pocket
  has been fixed.

* A bug in superposition that resulted in a crash when using site residues
  that were not present on a design unit has been fixed.

* A bug that kept the insert code from its anchor residue when there was an N-terminal cap
  has been fixed.


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

* Documentation has been added for the Iridium classification. :ref:`Iridium. <chapter_sprucetk_iridium>`

* Documentation has been added for the new superposition APIs. Superposition 
  related APIs are now fully supported. :ref:`Superposition. <chapter_sprucetk_superposition>`





.. _section_spruce_app_releasenotes_1202:

SPRUCE  1.2.0.2
================================================================================

*March 2021*

* An issue with  modeled loops having incorrect fragment numbers in their residue
  information has been fixed.

SPRUCE  1.2.0.0
================================================================================

*Fall 2020*

* Minor internal improvements have been made.


Spruce TK 1.2.0
================================================================================

*Fall 2020*

New features
--------------------------------------------------------------------------------
* New methods have been added to :ref:`OEDesignUnitSplitOptions <OESpruce_OEDesignUnitSplitOptions>`
  (:ref:`AddLipidCode  <OESpruce_OEDesignUnitSplitOptions_AddLipidCode>`,
  :ref:`SetLipidCodes  <OESpruce_OEDesignUnitSplitOptions_SetLipidCodes>`,
  :ref:`ClearLipidCodes  <OESpruce_OEDesignUnitSplitOptions_ClearLipidCodes>`, and
  :ref:`GetLipidCodes  <OESpruce_OEDesignUnitSplitOptions_GetLipidCodes>`).
  They allow users to specify the names of molecules to be
  considered as lipids.

* Support has been added for HEME and related cofactors in :ref:`OEMakeDesignUnits  <OESpruce_OEMakeDesignUnits>`. The state of HEME,
  contains two negatively charged nitrogens to balance the +2 Fe formal charge. The nitrogens coordinating
  the iron atom are indicated by zero-order bonds.

* A new function, :ref:`OEFindPockets <OESpruce_OEFindPockets>`, has been added that finds cavities in protein or nucleic acid complexes. The parameters
  for the search can be tuned with :ref:`OEPocketOptions <OESpruce_OEPocketOptions>`. The pockets are output as :ref:`OEPocket <OESpruce_OEPocket>` objects in an iterator.
  The function can take a predicate that will control only outputting pockets with a given set of residues or atoms in it. This function is also used in
  :ref:`OEMakeDesignUnits  <OESpruce_OEMakeDesignUnits>` when a site residue is provided.

* A new function, :ref:`OEMakeDesignUnitFromPocket  <OESpruce_OEMakeDesignUnitFromPocket>`, has been added that takes a prepared biological unit from
  an :ref:`OEMakeDesignUnit  <OESpruce_OEMakeDesignUnit>` and an :ref:`OEPocket <OESpruce_OEPocket>` and coverts it into an :ref:`OEDesignUnit <OEBio_OEDesignUnit>`
  does with a reference structure.

* New methods have been added in :ref:`OELoopBuilderOptions <OESpruce_OELoopBuilderOptions>`,
  :ref:`SetSeqAlignMethod  <OESpruce_OELoopBuilderOptions_SetSeqAlignMethod>`,
  :ref:`SetSeqAlignGapPenalty  <OESpruce_OELoopBuilderOptions_SetSeqAlignGapPenalty>`,
  :ref:`SetSeqAlignExtendPenalty  <OESpruce_OELoopBuilderOptions_SetSeqAlignExtendPenalty>`,
  :ref:`GetSeqAlignMethod  <OESpruce_OELoopBuilderOptions_GetSeqAlignMethod>`,
  :ref:`GetSeqAlignGapPenalty  <OESpruce_OELoopBuilderOptions_GetSeqAlignGapPenalty>`, and
  :ref:`GetSeqAlignExtendPenalty  <OESpruce_OELoopBuilderOptions_GetSeqAlignExtendPenalty>`
  that allow users to control the sequence alignment done to find gaps
  in protein structures related to loop modeling.

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

* A bug that caused some modeled loops to be missing the backbone NH hydrogen where the modeled loops were attached has been fixed.

* Fragment numbers for build loops have been fixed to be consistent with the anchor residues where the loops are inserted.

* A bug in :ref:`OEFixBackbone  <OESpruce_OEFixBackbone>` has been fixed to ensure that OXT atoms are always built on C-terminal residues.

* An issue with atom order for built pieces like loops or caps has been fixed to ensure that these are sequential with the location they are built.

* A bug in :ref:`OEBuildLoops  <OESpruce_OEBuildLoops>` that in specific situations caused incorrect detection of gaps in protein
  structures has been fixed. Additionally, options have been exposed in :ref:`OELoopBuilderOptions <OESpruce_OELoopBuilderOptions>` to allows users
  to control the underlying sequence alignment in the event of a failure.

Minor bug fixes
--------------------------------------------------------------------------------
* Improvements have been made to standard amino acid residue perception when
  preparing structures.

* Site residues in :ref:`OEMakeDesignUnits  <OESpruce_OEMakeDesignUnits>` are now being checked against all
  the biological units so one can serve as a reference for the rest.

* A bug in loop modeling that caused the function to create residues with identical residue numbers
  has been fixed. The function now properly builds using insertion codes.

* A bug in loop modeling that caused problems for the underlying sequence alignment code and incorrect
  loops when a single residue was floating in space between two gaps has been fixed.

* The chemical component dictionary used internally in :ref:`OEMakeDesignUnits  <OESpruce_OEMakeDesignUnits>` has been updated with the
  latest changes from the RCSB, including some fixes for incorrect entries in the source data based on
  rules and literature searches.




SPRUCE 1.1.0
================================================================================

*Spring 2020.1*

* An issue resulting in a floating point exception on MacOS has been fixed.

* Minor errors in the help text have been fixed.


SPRUCE 1.0.0
================================================================================

*Nov 2019*

This version of **SPRUCE** has been built using **OEToolkits 2019.Oct**.

This is first release of the **SPRUCE** application suite. **SPRUCE** takes experimental
biomolecular structure data in either ``PDB`` or ``mmCIF`` formats, and prepares the structures
for use with downstream modeling applications.  The **SPRUCE** application suite consists
of the following applications and utilities:

* **SPRUCE** prepares biomolecular structure files (``PDB``, ``mmCIF``,
  ``OEB``, etc.) for downstream modeling applications such as docking a ligand with **FRED** or
  **HYBRID**, predicting poses with **POSIT**, or for running **SZMAP** to analyze active-site
  hydration thermodynamics.

* **Superposition** structurally superposes a given biomolecular
  structure onto a reference structure.

* **EnumSites** enumerates biounit OEDesignUnit (``OEDU``) files, and
  creates individual ``OEDU`` files for every active site discovered.

* **GetStructure** downloads ``PDB``, ``mmCIF``, and ``MTZ`` files if available
  for a given PDB code. The downloads are from the RCSB website.


SPRUCE 1.1.0
================================================================================

*Spring 2020.0*

This version of **SPRUCE** has been built using **OEToolkits 2020.0**.

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

This release contains two new applications:

* **LoopDB_Builder** uses existing structures to build a dictionary of known loops
  that can be used in loop modeling of unresolved gaps in protein structures.

* **du2pdb** converts the entire content of an ``OEDesignUnit`` to a PDB file.

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

* The **GetStructure** application has been enhanced to prevent partial downloads.
  Retries and timeouts have been improved.

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

* The prefix input behavior has been standardized across all **SPRUCE** applications.

* The input option ``--restrict_to_refsite`` is now being respected for both
  **SPRUCE** and **EnumSites**.

* The ``-site_residue`` input option to **EnumSites** now performs correctly.

* The **GetStructure** application now checks that the input PDB code contains 4 characters.

* **SPRUCE** now fails if an MTZ file is specified but is not present or is unreadable.

* The documentation around the ``-site_residue`` option used for APO structures has been simplified.


.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _spruce_app_citation:

************
Citation
************

.. note:: To cite Spruce please use the following:

    Spruce |spruce_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


.. szmap toolkit documentation master file
.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



#################################
SZMAP |szmap_version|
#################################

.. toctree::
   :maxdepth: 2

   introduction
   sprucebeforeszmap
   szmap/szmap
   gameplan/gameplan
   utilities
   vidaext/extensions
   tutorials/szmap_tutorials
   theory/szmap_theory
   releasenotes/index
   appendix/szmap_appendix
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt






.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_szmap_introduction:

******************************
Introduction
******************************

==============
Overview
==============

The *SZMAP* product uses a semi-continuum solvation theory,
to analyze and understand if presence of water in the binding site
has a stabilizing or destabilizing effect on a protein-ligand complex.

==============
Applications
==============

The **SZMAP** distribution comprises 2 applications:

  :ref:`SZMAP <chapter_szmap>`

  The **SZMAP** program is an application for analyzing sites on the surface of a protein and/or ligand using an explicit
  probe molecule, usually water, and producing 3D grids of estimated thermodynamic properties.  **SZMAP** can also
  evaluate solvent thermodynamics rapidly at specified coordinates.

  :ref:`GamePlan <chapter_gameplan>`

   The **GamePlan** tool identifies interesting coordinates
   near a ligand or in a protein binding site,
   runs :ref:`chapter_szmap`, and analyzes the results,
   comparing ligand properties to the binding site environment,
   generating a set of hypotheses for ligand modification and identifying sites
   where water either stabilizes or destabilizes the complex.

==================
Utility Programs
==================

The following utility programs are also included in this distribution:

* :ref:`chapter_szmap_grid`: This program displays information about
  grids within an OE binary file (*.oeb*) and can split out a particular grid
  into a separate file. It also displays property tags in ``-at_coords``
  results.

* :ref:`chapter_grid_comp`: This program performs various
  mathematical operations on a grid or pair of grids to facilitate grid
  comparisons.

* :ref:`chapter_szmap_report`: This program produces *.pdf* files
  containing 2D renderings of :ref:`chapter_szmap` results using the
  **OEDepict** and **Grapheme** technology.

.. index:: Pronunciation

==============================
A Word About Pronunciation
==============================

Like a number of *OpenEye* product names, *SZMAP* (solvent-zap-map) contains
the letter pair *sz* which sounds similar to *sh*. It is pronounced *'shmăp*.


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_sprucebeforeszmap:

********************
Spruce Before Szmap
********************

Overview
===================

The :ref:`SPRUCE <chapter_spruce>` program for preparing structures into input ready for :ref:`chapter_szmap` or :ref:`chapter_gameplan`.
The input can be in PDB, MMCIF, or any fileformat that includes residue information (e.g. OEB).
The ligand will be autodetected, but can also be specified on the command line if multiple
potential ligands are present.

See more:

   :ref:`SPRUCE <chapter_spruce>`


.. _chapter_szmap:

*********************************
SZMAP
*********************************

.. toctree::
   :maxdepth: 2

   szmap_overview
   szmap_inputs
   szmap_example
   szmap_help
   szmap_req_params
   szmap_opt_params



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _szmap_overview:

=================================
Overview
=================================
.. _figure_szmap_howto:

.. figure:: /_images/szmap-howto.png
   :width: 1000
   :align:  center

   **Semi-continuum Solvation**

The **SZMAP** application analyzes
sites near the surface of a protein or ligand using semi-continuum solvation theory,
which combines a single explicit
probe water with Poisson-Boltzmann continuum theory.
By sampling various probe water orientations as it
interacts with continuum solvent
and with protein and ligand molecules, **SZMAP** can estimate
thermodynamic properties useful in understanding the solvent role in ligand binding.
One of the advantages of this semi-continuum approach is that **SZMAP**
can place the probe anywhere one wishes to analyze, even locations that molecular dynamics
simulations may not be able to sample adequately.
The *Technical Details* section of chapter :ref:`chapter_szmap_theory_details`
describes how these values are computed.

The most important question **SZMAP** can address is whether
displacing water in a given region of a binding site is likely
to increase or decrease binding
affinity. A related question is what to replace a water with once the
decision has been made to displace it.
And finally, there is the question of whether water sites can be made to
contribute to binding affinity *without* being displaced.

The analysis section of the :ref:`szmap_tutorial_intro` goes through how to determine
whether a site is a good candidate for solvent replacement by looking
at *apo*, complex and stabilization results. It also touches
on questions of what to replace water with by looking at
difference free energies, probe water orientations and :ref:`chapter_gameplan`
results.

In addition to being run directly, **SZMAP** is called indirectly
by :ref:`chapter_gameplan`. The **SZMAP** results are analyzed
to produce hypotheses for ways to optimize the ligand, showing specific substituent
geometries based on water energetics.



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _szmap_input_output:

=================================
SZMAP Input and Output
=================================

**SZMAP** takes molecule files as input---usually molecules representing a protein
and a corresponding ligand---and generates an OEBinary file as output.
The molecular input is assumed to have explicit hydrogens and
partial charges. Making sure the input molecules are properly prepared
is *essential* in order to obtain useful results and we recommend using OEDesignUnit
generated with :ref:`chapter_spruce` for this. See the :ref:`szmap_tutorial_intro`
chapter for more information on preparing molecules.

.. note::

   When using OEDesignUnits, note that they potentially include both solvent and
   a bound ligand, depending on the structure. There are two flags that are crucial to keep
   in mind, ``-excludeDUsolvent`` and ``-excludeDUligand``, to control whether those two
   components should be part of the calculation or not.

When **SZMAP** reads input molecules, it checks for missing hydrogens
and missing partial charges and will halt if the protein input does not appear to
be complete; for ligands AM1BCC charges and Zap9 radii are assigned if partial charges are not pre-assigned.
When the ligand(s) are already split out from the protein, :ref:`chapter_molcharge`
may be used to add partial different partial charges to the ligands.
The option :option:`-warn_if_missing_hydrogens` can be used to
prevent halting, but before using it you should analyze the problem to see
if it is due to an error in the input or something else, such as a disagreement with OEChem
as to the proper bond order or charge state for your molecule.
Mistakes in encoding alternate conformation codes can, for example, lead to
very long and very short bonds, with the short ones interpreted as double bonds.
And aromatic or double bonds that are not flat enough can cause OEChem to
interpret them as single bonds.

.. warning::

   If :ref:`chapter_szmap` is given an input *.pdb* file which still contains the
   usual occupancy and B-factor, rather than radii and partial charges,
   any energies it generates will be meaningless.

**SZMAP** output contains
the input molecules along with either one or more computed grids
or with computed values attached to individual atoms. The output file
can be opened in *VIDA* where the results will be displayed in the context of the
input molecules. See the :ref:`szmap_tutorial_intro` and
the chapters describing the :ref:`chapter_watercolor`,
the :ref:`chapter_waterorient` and the :ref:`chapter_colorprops`
for step-by-step information on visualizing the results.

Calculations done at specific coordinates produce a tab-delimited table listing
the results, which can be processed by *Excel* or other programs.

The output file can also be interpreted by the utility programs
:ref:`chapter_szmap_grid`, :ref:`chapter_grid_comp` and :ref:`chapter_szmap_report`.
Although *VIDA* is the best tool for analyzing **SZMAP** results,
:ref:`chapter_szmap_grid` can be used to write out grid data in other formats.



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _szmap_example:

..  program:: szmap

=================================
Example Commands
=================================

Grid Calculations
----------------------------------------------------

.. _figure_szmap_nddG:

.. figure:: /_images/szmap-1dds-apo-nddG.png
   :width: 1000
   :align:  center

   **apo Neutral Difference Free Energy Grid**

If a ligand is provided, either bound in the OEDesignUnit or separately on the command line,
and no other selection criterion are specified, **SZMAP** will perform grid calculations
centered around the ligand. If not using a design unit as input and the structure has multiple
binding sites, it is usually appropriate to focus on only one of these by making
sure only one molecule is in the input ligand file. Other ways to define the calculation
area include a bounding box, the region around a particular protein residue or
small molecule, even the entire surface of the protein.
Beware, surface calculations generate a *very* large number of points and
take a correspondingly long time to compute. It is usually best to focus the
computation on a smaller region.

::

   > szmap -mpi_np 4 -stbl -prefix 1dds_stbl -p 1DDS_AB__DU__MTX_A-201.oedu

   or

   > szmap -mpi_np 4 -stbl -prefix 1dds_stbl -p 1DDS_AB__DU__MTX_A-201_target.oeb.gz -l 1DDS_AB__DU__MTX_A-201_ligand.oeb.gz

Because there are often a great many points to be tested in a grid calculation, the
MPI multiprocessing options ``-mpi_np <num>`` and ``-mpi_hostfile <file>``
can be used to speed calculations by running **SZMAP** on multiple cores
or multiple networked computers.

.. _figure_szmap_mpi_curve:

.. figure:: /_images/4std_stbl_mpi_speedup.png
   :width: 1000
   :align:  center

   **Speed vs Processors**

The figure :ref:`Speed vs Processors<figure_szmap_mpi_curve>` is
from a stabilization grid calculation
run across a wide range of processor numbers. The dashed line
is the diagonal for reference.
With 8 processors, **SZMAP** runs over 6 times faster,
and with 200 processors, about 150 times faster.

By default, grid output consists of four types:

   + **neutral difference free energy**, a hydrophilic/hydrophobic polarity scale described below,

   + **van der Waals energy**, an energy term not included
     in the neutral difference free energy,

   + **order**, the fractional loss of rotational entropy due to electrostatics, indicating
     how much energy can be liberated by displacing water at this site,

   + **mask**, an accurate solvent accessible surface---the region where the calculations
     were performed and the probe did not clash.

Neutral difference free energies compare the water probe with an uncharged or neutral water probe,
a water where all the atoms have a partial charge of 0.0. The uncharged probe is a proxy
for a hydrophobic group of the same size and shape as the standard probe water
and these difference energies map out variations in the hydrophobic/hydrophilic nature of the binding site.
High affinity ligands put nonpolar groups where these energies are positive and
polar groups where these energies are negative, mimicking the donor-acceptor
pattern of the solvent in the *apo* pocket.

Neutral difference free energies do not capture variations in van der Waals energies,
which subtract out in the difference calculation. Van der Waals results are
provided separately and complement the information in the neutral difference free energies.

Many additional grids are produced when the option :option:`-results_set` ``max`` is specified.
The most useful of these extra grids are probably *psolv* and *wsolv*---protein and water desolvation,
respectively. They are always penalties (> 0.0 kcal/mol) and reveal
the extent to which burying a charge costs energy, which needs to be compensated for by
a complementary charge.

For most grid calculations, the :option:`-stabilization` option is recommended. This causes
*complex, ligand* and *apo* calculations all to be performed
(although ligand calculations are by default restricted to solvent regions from the complex).
Stabilization free energy values---computed as *(complex + bulk) - (apo + ligand)*
where bulk-solvent is defined
as 0.0---show how water energies are affected by binding. Negative stabilization free energies
are regions that are stabilized by binding, or looked at another way, regions that
stabilize binding. The simplest thing to do with them is leave them as they are, since they
increase affinity. They *can* be displaced without destroying affinity, however, but only
if they are displaced with a group that makes similar beneficial interactions.
Positive stabilization free energies indicate regions where water
is destabilized on binding. These waters lower affinity and are relatively easy to displace productively.
Note that positive stabilization free energies can be found in regions where the
neutral difference free energies in the complex
are negative, and vice-versa. These two types of energies are not always
correlated.

When comparing a series of ligands, all docked into the same binding site,
the *apo* calculations can be done once separately by dropping the :option:`-stabilization` option and
specifying :option:`-apo_grids`. Then these *apo* grids can be
used in stabilization calculations for a series of ligands with the :option:`-use_apo_from` option.
If the ligands are all concatenated into one file, the :option:`-split_lig` option will split each one
out and perform the *complex* and *ligand* and *stabilization* calculations one-by-one.

::

   > szmap -apo_grids -prefix 1dds_apo -p 1DDS_AB__DU__MTX_A-201.oedu -l 1dds_lig_series.oeb.gz

   > szmap -mpi_hostfile myhosts.txt -stbl -use_apo_from 1dds_apo.oeb.gz -split_lig  \
           -prefix 1dds_stbl -p 1DDS_AB__DU__MTX_A-201.oedu -l 1dds_lig_series.oeb.gz

   or

   > szmap -apo_grids -prefix 1dds_apo -p 1DDS_AB__DU__MTX_A-201_target.oeb.gz -l 1dds_lig_series.oeb.gz

   > szmap -mpi_hostfile myhosts.txt -stbl -use_apo_from 1dds_apo.oeb.gz -split_lig  \
           -prefix 1dds_stbl -p 1DDS_AB__DU__MTX_A-201_target.oeb.gz -l 1dds_lig_series.oeb.gz

.. note::

   The line above with a '\\' as the very last character indicates that the command
   was too long to fit on one line and continues on the following line.

Most grids are masked to show only regions where the minimum *Coulombic interaction + vdw energy* is
at or below :option:`-mask_cutoff` (0.0 kcal/mol by default); anything
above this is considered a *CLASH*. The *mask_grid* represents this solvent-accessible region.
Somewhat surprisingly, errors in coordinates of
atoms in a structure, even small errors, occasionally lead to clashes being indicated in areas where
a crystallographic water is observed. Typically, there will be an adjacent region where
the probe water does not clash.

Grid results can be processed with the utility :ref:`chapter_grid_comp` to break-out
the region of the *apo* grid that has been displaced by the ligand.

::

   > grid_comp -op lig_disp -i 4std_stbl.oeb.gz -o 4std_stbl_disp.oeb.gz

The volume of water displaced by
the ligand plus the volume of water in the complex equals
the volume of water in the full *apo* pocket.
Displacement grids are useful in identifying, for example,
precisely which waters are displaced by each of a series of substituents.

"At Coords" Calculations
----------------------------------------------------

.. _figure_szmap_coords:

.. figure:: /_images/szmap-1dds-coords.png
   :width: 1000
   :align:  center

   **apo Neutral Difference Free Energy at Ligand Coordinates**

When the :option:`-at_coords` option is used, no grid is produced. Instead calculations
are done only at the coordinates of any atoms in the coordinates file and written out attached
to those atoms for use by :ref:`chapter_szmap_report`, the :ref:`chapter_waterorient`
and the :ref:`chapter_colorprops`.
A tab-delimited table of these results is written to a text file, which can easily be
loaded into a spreadsheet program for further analysis.
"At coords" calculations produce many different results values at each point
(see the :ref:`chapter_appendix2`), but the four types of results enumerated
in the grid section above are the most useful.

::

   > szmap -prefix 1dds_coords -p 1DDS_AB__DU__MTX_A-201.oedu -at_coords 1dds_lig.oeb.gz -excludeDUligand
   > szmap -prefix 1dds_coords -p 1DDS_AB__DU__MTX_A-201_target.oeb.gz -at_coords 1dds_lig.oeb.gz

**SZMAP** :option:`-at_coords` calculations are much faster than grid calculations
because they operate over a much more limited set of points. Keep in mind that a region
where there is a large gradient in a property will be undersampled if the coordinates there
are widely spaced. Points labeled "CLASH"
have *Coulombic interaction + vdw energy* greater than the :option:`-mask_cutoff`
(analogously to how the *mask_grid* is determined for a grid calculation).
The "CLASH" label can be displayed in *VIDA* using the generic label function under the
*Aa+* button in the style panel.

If coordinates are taken from the ligand, as above, then stabilization calculations are
not possible. But coordinates at other locations, such as crystallographic waters,
can be used to rapidly produce stabilization results.

::

   > szmap -stbl -at_coords 1dds_waters.oeb.gz -prefix 1dds_xtal_waters \
           -p 1DDS_AB__DU__MTX_A-201.oedu
   > szmap -stbl -at_coords 1dds_waters.oeb.gz -prefix 1dds_xtal_waters \
           -p 1DDS_AB__DU__MTX_A-201_target.oeb.gz -l 1DDS_AB__DU__MTX_A-201_ligand.oeb.gz

:ref:`chapter_gameplan` runs **SZMAP** at specific coordinates around the
binding site and up-to two single bonds away from the ligand, analyzing the results to
provide insight into ways to optimize the ligand.

Probe Orientation Data
----------------------------------------------------

.. _figure_szmap_orient:

.. figure:: /_images/szmap-1dds-orient.png
   :width: 1000
   :align:  center

   **Probe Water Orientations**

In both types of **SZMAP** results, grids and "at coords", information is
stored about the energies and probabilities of the probe for each point. This information
can be processed by the :ref:`chapter_waterorient` to identify regions of local
energy minima and maxima and to display probe order or disorder. The probe geometry
at dominant sites in the region where water is displaced can be compared to that of the ligand.
High affinity ligands mimic both the difference free energy pattern and
the specific geometry of the displaced water. This more "molecular" display
is often easier to understand than continuous grids of data and it contains structural
information that complements the numerical energy values.


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


====================
Command Line Help
====================

A description of the command line interface can be obtained by executing **SZMAP**
with the `--help` option.

.. code-block:: console
   
   > szmap --help

will generate the following output:

::

   Help functions:
     szmap --help simple      : Get a list of simple parameters
     szmap --help all         : Get a complete list of parameters
     szmap --help defaults    : List the defaults for all parameters
     szmap --help <parameter> : Get detailed help on a parameter
     szmap --help html        : Create an html help file for this program
     szmap --help versions    : List the toolkits and versions used in the application


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


..  program:: szmap

=================================
Required Parameters
=================================

.. option:: -target <filename>
   -protein <filename>
   -p <filename>

   [keyless parameter 1]

   The format must be one that retains partial charges: OEBinary, Tripos .mol2, or
   DelPhi flavor PDB (where there is radii in the occupancy field and
   charge in the B-factor field).

   The file format of the input file is automatically determined from
   the file extension. The extensions *.oeb*, *.oeb.gz* can be
   OEBinary; *.oedu for OEDesignUnit; *.mol2* for Tripos Mol2 files;
   *.pdb* for PDB format files.

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEDesignUnit .oedu
   ------------ ---------------------------
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   PDB(DelPhi)  .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ============ ===========================

   .. warning::

      By default, charges and radii are expected to be in this file
      and the results will be meaningless if they are missing. The
      program :ref:`SPRUCE <chapter_spruce>` is provided to prepare the
      biomolecular structure including assigning charges and radii.

   Atoms from waters, metals, ligands, co-factors, modified proteins and nucleic acids
   will be included in the calculation, except when using an OEDesignUnit, in which case only the
   protein and nucleic acid content will be used. *VIDA* can be used to create a new molecule
   where the protein is split from these.


.. _szmap_opt_params:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


..  program:: szmap

=================================
Optional Parameters
=================================

Input File Options
-------------------

.. option:: -ligand <filename>
   -l <filename>

   [keyless parameter 2]

   If an OEDesignUnit was used as input for the protein, and it contained a ligand
   the ligand from this will be used unless otherwise specified.

   The format can be one that retains partial charges: OEBinary, Tripos .mol2, or
   DelPhi flavor PDB (where there is radii in the occupancy field and
   charge in the B-factor field).

   .. note::

      If no charges are present on the read molecule, AM1BCC charges and Zap9 radii
      are assigned to the molecule.

.. option:: -warn_if_missing_hydrogens

   If specified, missing hydrogens will not terminate the program,
   but will instead generate a warning message. Otherwise, missing
   hydrogens on the ligand or on more than 10 percent of the protein
   heavy atoms will cause :program:`szmap` to fail.

.. option:: -split_lig

   Separate ligand file into individual molecules and run each individually.

Output File Options
-------------------

.. option:: -prefix <prefix>

   Prefix used to name output files. Using ``-prefix FOO``
   will create results in an OEBinary file named ``FOO.oeb.gz``
   (see :option:`-output_mol`). The table produced with :option:`-at_coords`
   will be written to ``FOO.txt`` (see :option:`-table`).
   Additionally, a parameter file named ``FOO.param`` (see :option:`-param`)
   and a log file named ``FOO.log`` (see :option:`-log`).

   [Default=szmap]

.. option:: -output_mol <filename>
   -o <filename>

   [keyless parameter 3]

   OEBinary output file (*.oeb* or *.oeb.gz*), with calculated
   results attached to a copy of the input :option:`-protein`
   and any :option:`-ligand`.

   If not specified, :option:`-prefix` will be used to name the output.

.. option:: -table <filename>

   A tab-delimited table of results from :option:`-at_coords` calculations
   is written to this file.
   If specified, this will override the filename created from :option:`-prefix`.
   Specify ``-table -`` to send to *standard-output*.

.. option:: -std_box <filename>

   Write *standard* (complex) grid bounding box to
   output 'box molecule' coordinate file.

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ------------ ---------------------------
   MDL          .mdl .mdl.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ------------ ---------------------------
   MOPAC        .mopac .mopac.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz
   ------------ ---------------------------
   XMol xyz     .xyz .xyz.gz
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges in formats
   that support bonds.
   Use :option:`-box_mol` to select based on
   this file.

.. option:: -lig_box <filename>

   Write *ligand* grid bounding box to
   output 'box molecule' coordinate file.

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ------------ ---------------------------
   MDL          .mdl .mdl.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ------------ ---------------------------
   MOPAC        .mopac .mopac.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz
   ------------ ---------------------------
   XMol xyz     .xyz .xyz.gz
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges in formats
   that support bonds.
   Use :option:`-box_mol` to select based on
   this file.

.. option:: -apo_box <filename>

   Write *apo* grid bounding box to
   output 'box molecule' coordinate file.

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ------------ ---------------------------
   MDL          .mdl .mdl.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ------------ ---------------------------
   MOPAC        .mopac .mopac.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz
   ------------ ---------------------------
   XMol xyz     .xyz .xyz.gz
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges in formats
   that support bonds.
   Use :option:`-box_mol` to select based on
   this file.

Selection Options
-----------------

If the input is an OEDesignUnit, then the following flags
can be used to exclude pieces from the structure before the calculation

.. option:: -excludeDUsolvent

   Excludes structural waters from the input design unit

.. option:: -excludeDUligand

   Excludes the bound ligand from the input design unit

If a :option:`-ligand` is provided but none
of the selection method's options are specified,
points are selected around the ligand when grids
are generated, even for
*apo* grids (see :option:`-distance_cutoff`).

.. option:: -at_coords <filename>
   -coords <filename>

   Perform calculations just at the coordinates
   of atoms in any molecules in the file. Write
   those molecules, with the (masked) results attached
   to the atoms, to the output file.

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ------------ ---------------------------
   MDL          .mdl .mdl.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ------------ ---------------------------
   MOPAC        .mopac .mopac.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz
   ------------ ---------------------------
   XMol xyz     .xyz .xyz.gz
   ============ ===========================

   Text formats such as ``.xyz`` are easily modified in a text editor
   to specify an arbitrary set of coordinates.

   The tags that will be used when assigning values to atoms
   are listed in :ref:`chapter_appendix2`.

   A tab-delimited table of calculation results is printed to
   a text file (see :option:`-table`). In the abbreviated column heading,
   ``n_`` stands for neutral and
   ``v_`` stands for vacuum. A mask value of 0 indicates that the
   *intvdw* value is above :option:`-mask_cutoff` and this row of data
   should not be used.

.. option:: -residue_number <number>
   -res <number>

   Select grid points around the selected residue
   (see :option:`-distance_cutoff`).

.. option:: -residue_chain <letter>
   -chain <letter>

   Protein chain used with :option:`-residue_number`.
   Case sensitive. Underscore ('_') stands for blank.

   [Default='_']

.. option:: -residue_insert <letter>
   -inscode <letter>

   Protein insertion code used with :option:`-residue_number`.
   Case sensitive. Underscore ('_') stands for blank.

   [Default='_']

.. option:: -like_std <filename>

   Select points in the same bounding box as the
   *standard* (complex) grids
   from the specified OEBinary (*.oeb* or *.oeb.gz*) file.

.. option:: -like_lig <filename>

   Select points in the same bounding box as the *ligand* grids
   from the specified OEBinary (*.oeb* or *.oeb.gz*) file.

.. option:: -like_apo <filename>

   Select points in the same bounding box as the *apo* grids
   from the specified OEBinary (*.oeb* or *.oeb.gz*) file.

.. option:: -like_box <filename>

   Select points in the same bounding box as the *box_mol*
   in the specified OEBinary (*.oeb* or *.oeb.gz*) file.

.. option:: -around_mol <filename>
   -around <filename>

   Select points enclosing the atoms in the specified file
   (using :option:`-distance_cutoff` to define how much extra
   space beyond the atoms is include).

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ------------ ---------------------------
   MDL          .mdl .mdl.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ------------ ---------------------------
   MOPAC        .mopac .mopac.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz
   ------------ ---------------------------
   XMol xyz     .xyz .xyz.gz
   ============ ===========================

   Text formats such as ``.xyz`` are easily modified in a text editor
   to adjust the region of interest.

.. option:: -box_mol <filename>

   Select points in bounding box defined by atoms in
   the input 'box molecule' file (without a :option:`-distance_cutoff`).

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ------------ ---------------------------
   MDL          .mdl .mdl.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ------------ ---------------------------
   MOPAC        .mopac .mopac.gz
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   SDF          .sdf .mol .sdf.gz .mol.gz
   ------------ ---------------------------
   XMol xyz     .xyz .xyz.gz
   ============ ===========================

   Text formats such as ``.xyz`` are easily modified in a text editor
   to adjust the region of interest.

.. option:: -bounding_box <xmin> <ymin> <zmin> <xmax> <ymax> <zmax>
   -bbox  <xmin> <ymin> <zmin> <xmax> <ymax> <zmax>

   Select points in the bounding box defined by
   minimum and maximum coordinate values.

.. option:: -surface_points
   -surf

   Select grid points over the entire surface of the input
   molecule(s).

   .. warning::
      This usually results in very long run times.

.. option:: -distance_cutoff <number>
   -dcutoff <number>

   Maximum distance from atoms of selected points, a margin
   around the focus region.

   [Default=4.0 |A|]

.. option:: -value_cutoff <number>
   -vcutoff <number>

   Minimum *FRED* surface shape score value for selected points.

   [Default=0.05]

.. option:: -restrict_calc <level>

   Control which points are used for calculations. Restricting
   calculations makes :program:`szmap` run faster but make the that
   portion of the results less useful. In particular,
   restricting *apo* calculations may not be worth the
   speed increase because it prevents you from being
   able to analyze the full *apo* pocket.

   ====== ============================================
   Level  Meaning
   ====== ============================================
   none   Calculate full grids
   ------ --------------------------------------------
   ligand Restrict ligand calc to region from complex
   ------ --------------------------------------------
   apo    Restrict apo calc to region from complex
   ------ --------------------------------------------
   both   Restrict ligand & apo to region from complex
   ====== ============================================

   [Default=ligand]

Grid/Coord Options
------------------

If a grid or coord request option
is not specified, all *apo* results
will be generated, and if a ligand is supplied,
all *std*  (complex) results as well.

.. option:: -results_set <type>
   -properties <type>
   -grids <type>

   Defines which sets of properties are included in grid or coordinate
   results.

   ============= ==========================================================
   Type          Output
   ============= ==========================================================
   min           Only the standard (complex) results; minimal grid output;
   full coord    output
   ------------- ----------------------------------------------------------
   default       Both standard and *apo* results, if possible; minimal
   grid output;  full coord output
   ------------- ----------------------------------------------------------
   max           Both standard and *apo* results, if possible; Full grid
   and coord     output
   ============= ==========================================================

   *min* or *default* used for a grid calculation produces the following properties:

   + *neut_diff_free_energy_grid* (or the corresponding *lig* or *apo* grid)
   + *vdw_grid*
   + *order_grid*
   + *mask_grid*

   See :ref:`chapter_appendix1` for lists of properties.

   [Default=default]

.. option:: -stabilization
   -stbl

   Generate *(complex - (ligand + apo-pocket))* values that show where water is
   stabilized or destabilized upon ligand binding. This requires extra calculations
   with the ligand alone.

.. option:: -mask_cutoff <number>

   Points where the minimum interaction + van der Waals energy
   above this cutoff will be set to 0.0 in the output grids.

   [Default=0.0 kcal/mol]

.. option:: -grid_spacing <number>
   -space <number>

   Distance between grid points. We recommend this value be above 0.25 |A|.
   :program:`szmap` creates a grid by first building a temporary grid around the protein and/or ligand molecules
   that contains values of a function describing the space near the molecular surface.
   This temporary grid has the same grid spacing as the final grid, so
   using a very fine grid spacing can generate enormous temporary grids that fill memory.

   [Default=0.5 |A|]

.. option:: -standard_grids
   -std_grids
   -cplx_grids
   -std_coords

   Generate all *standard* (holo-complex) grids or coords. The actual
   grids or coord data will depend on :option:`-results_set`.

.. option:: -lig_grids
   -lig_coords

   Generate all *ligand* grids or coords. The actual
   grids or coord data will depend on :option:`-results_set`.

   The *std* and/or *apo* grids will still be generated as usual even if
   this option is specified.

.. option:: -apo_grids
   -apo_coords

   Generate all *apo* grids or coords. The actual
   grids or coord data will depend on :option:`-results_set`.

.. option:: -point_grid

   Generate the grid of test points where the calculation is done
   (1 = test, 0 otherwise).
   If a ligand is provided, values are for the protein/ligand complex.

.. option:: -lig_point_grid

   Generate the grid of test points where the calculation is done
   (1 = test, 0 otherwise).
   Values are for the ligand without the protein.

.. option:: -apo_point_grid

   Generate the grid of test points where the calculation is done
   (1 = test, 0 otherwise).
   If a ligand is provided, values are for the protein without
   the ligand.

Calculation Options
-------------------

.. option:: -num_orientations <number>
   -rot <number>

   Number of probe-molecule orientations to sample at each grid point.
   If this number is set to 24, 60, 216, 360, or 648 then the set of rotations
   will be symmetric. Otherwise, they will be random and may have lopsided
   gaps in coverage. For most purposes, 60 is the minimum required for
   reliable energy calculations and 360 generates robust results.

   [Default=60]

.. option:: -dielectric_model <type>
   -model <type>

   Type of surface defining the boundary between
   :option:`-inner_dielectric`
   and :option:`-outer_dielectric`
   values.

   ============== =========================================
   Type           Meaning
   ============== =========================================
   gaussian       Dielectric value changes smoothly over
   a distance of  approximately 2 |A|.
   -------------- -----------------------------------------
   molecular      Dielectric changes abruptly at molecular
   surface
   ============== =========================================

   [Default=gaussian]

.. option:: -inner_dielectric <number>
   -eps_in <number>

   Dielectric value used inside the protein and ligand atom surface
   (see :option:`-dielectric_model`).

   [Default=1.0]

.. option:: -outer_dielectric <number>
   -eps_out <number>

   Dielectric value used outside the protein and ligand atom surface
   (see :option:`-dielectric_model`). This is the dielectric of bulk solvent.

   [Default=80.0]

.. option:: -salt_conc <number>
   -salt <number>

   Salt concentration in Poisson Boltzmann calculation (units: moles/liter).

   [Default=0.05 M]

.. option:: -zap_spacing <number>

   Distance between grid points within the ZAP calculation.
   To avoid excessive memory requirements
   and ensure stability during
   the PB calculation, it is usually best for ZAP spacing
   to be greater than 0.25 |A|.

   [Default=0.5 |A|]

.. option:: -boundary_spacing <number>
   -boundary <number>

   Extra buffer outside the extents of the selection molecule.

   [Default=4.0 |A|]

.. option:: -boundary_radius <number>

   Size of probe for boundary calculation.

   [Default=1.4 |A|]

.. option:: -water_charge <type>

   Which charges are used on the probe water: *scaled* or *am1bcc*.
   *Scaled* means scale AM1BCC charges to match the water dipole.

   [Default=scaled]

.. option:: -vdw_scale <number>

   Scale for van der Waals between probe atoms and other atoms.

   [Default=1.0]

.. option:: -use_apo_from <filename>

   Use the *apo* grids in the *.oeb* results file from
   a previous :program:`szmap` run rather than calculating them.
   This can speed up calculations for a series of ligands
   docked to a single ligand.

   This option is also useful when the *apo* protein and the
   *complex* adopt slightly different states. For example, a
   key amino acid may have an ionized sidechain in the
   *apo* protein and a neutral sidechain in the *complex*.

MPI Options
-------------

These options control how MPI is used. Unless one of these
options is specified, :program:`szmap` will run in single processor mode.

.. option:: -mpi_np <number>

   Run :program:`szmap` calculations in MPI multiprocessor mode using the
   specified number of processors.  If an MPI hostfile is not specified with
   the -mpi_hostfile option all processor will be launched on the local machine.

.. option:: -mpi_hostfile <filename>

   Run :program:`szmap` calculations in MPI multihost mode using the
   specified MPI hostfile.  If an MPI hostfile is not specified all
   processes will be run on the local machine.  The hostfile format
   is a text file with each line specifying a machine and the number
   of processes to launch on it.

   The following example hostfile specified 3 hosts that can run up to
   4, 2 and 5 processes respectively.

   ::

      host1.mydomain.com slots=4
      host2.mydomain.com slots=2
      host3.mydomain.com slots=5

   This example hostfile would typically be used with -mpi_np 11 to make
   use of all the processors (4+2+5=11).

   Note that multiprocessor is only supported on the local machine under
   Windows, and in homogeneous environments for other architectures (i.e.,
   machines with the same operating system environment).

Other Options
---------------

.. option:: -param <filename>

   Defines the control parameter file. This file can contain a collection
   of parameters which can be used instead of writing each parameter to the command-line.
   In addition, the parameter file written by any :program:`szmap` run (see :option:`-prefix`)
   can be used with the :option:`-param` flag in subsequent :program:`szmap` runs. Any
   command given explicitly on the command line will supersede any command found
   in a file specified with the :option:`-param` flag.

.. option:: -logfile <filename>
   -log <filename>

   If specified, this will override the filename created from :option:`-prefix`.
   Specify "-log - " (dash) to send to *standard-output*.

.. option:: -progress <style>

   How to display progress information:

   ======= =========================================
   Style   Output
   ======= =========================================
   none    no progress shown
   ------- -----------------------------------------
   dots    print a period (.) for every point tested
   ------- -----------------------------------------
   percent print percentage complete every 10 points
   ------- -----------------------------------------
   log     print percentage to log file
   ======= =========================================

   [Default=percent]

.. option:: -verbose
   -v

   Print additional information to log during calculations.


.. _chapter_gameplan:

*********************************
GamePlan
*********************************

.. toctree::
   :maxdepth: 2

   gameplan_overview
   gameplan_example
   gameplan_help
   gameplan_req_params
   gameplan_opt_params


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _gameplan_overview:

=================================
Overview
=================================

The **GamePlan** application analyzes a protein and a bound or docked ligand
to determine points where solvent information may be interesting, runs :ref:`chapter_szmap`
at these points, and then processes the results, formulating various
hypotheses for ligand modification and identifying sites where water is stabilizing
or destabilizing.

.. _figure_hypothesis_4std_polar_attachment:

.. figure:: /_images/4std_polar_attachment.png
   :width: 1000
   :align:  center

   **Gameplan Hypothesis**


.. _gameplan_example:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


==========================
Example Commands
==========================

Running Gameplan
================================================================================

The usual workflow starts with preparing the protein and ligand by adding hydrogens and
assigning partial charges. See the :ref:`szmap_tutorial_intro` for a thorough discussion of preparation.

Next, run **GamePlan** and view the results in VIDA
using the :ref:`chapter_watercolor` to configure the annotations. On average, a **GamePlan**
calculation will take 4 to 8 minutes on Linux using four 2.8GHz processors, for example.

::

   > gameplan -szmap_mpi_np 4 -prefix 2xdl_gameplan -p 2XDL_AB__DU__2DL_A-1225.oedu

   or

   > gameplan -szmap_mpi_np 4 -prefix 2xdl_gameplan -p 2XDL_AB__DU__2DL_A-1225_target.oeb.gz -l 2XDL_AB__DU__2DL_A-1225_ligand.oeb.gz

   > vida 2xdl_gameplan.oeb.gz

In :ref:`Gameplan Hypothesis<figure_hypothesis_4std_polar_attachment>`,
the bonds in hot-pink represent an idea about how to modify the ligand to add a
two-atom hydrogen-bond acceptor group that could interact favorably
with nearby tyrosine residues. The yellow ball indicates that water makes a strong polar interaction
at this site in the *apo*-protein.

When **GamePlan** reads input molecules, it checks for missing hydrogens
and missing partial charges and will halt if the input does not appear to
be complete. The option :option:`-warn_if_missing_hydrogens` can be used to
prevent halting, but before using it you should analyze the problem to see
if it is due to an error in the input or even a disagreement with OEChem
as to the proper bond order and charge state for your molecule.
Mistakes in encoding alternate conformation codes can, for example, lead to
very long and very short bonds, with the short ones interpreted as double bonds.
And aromatic or double bonds that are not flat enough can cause OEChem to
think they are single bonds. See :ref:`Protein and Ligand preparation for SZMAP and GamePlan<szmap_tutorial_prep>` 
for discussion of preparation and how to resolve such pathologies using 
:ref:`SPRUCE <chapter_spruce>`.

By default, **GamePlan** hypotheses respect the hybridization of
aromatic atoms in the input ligand. Specifying the option
:option:`-sp3_aromatic` will permit **GamePlan** to explore the
effect of a change of hybridization of aromatic atoms.
Note that only the local hybridization at the attachment site is altered,
often leading to odd-looking geometry. But the point is to generate fresh ideas
for how you might modify your ligand.

Gameplan Results
================================================================================

Open the results in **VIDA**, highlight any part of the output in the List window,
and run the :ref:`chapter_watercolor` to configure the annotation and focus
the view to the region around the ligand. See the last section
of chapter :ref:`chapter_watercolor` for a step-by-step guide to doing this.

.. _figure_gameplan_list:

.. figure:: /_images/vida_gameplan_list_window.png
   :width: 1000
   :align:  center

   **Gameplan List Window**

**GamePlan** results are organized into three main sections
(see figure :ref:`Gameplan List Window<figure_gameplan_list>`):

#. An analysis of how well the ligand compares to the solvent in the binding site
   with colored annotation around atoms that indicates the type of site
   (figure :ref:`Ligand Compared to apo Binding Site<figure_gameplan_ligand>`).
   The protein is also included here for context.

#. A series of hypotheses for substituents that could be added to the ligand. Each
   attachment is modeled using dummy atoms that show up in hot-pink in *VIDA*,
   with annotation that indicates the type of site: polar, nonpolar and van der Waals
   (see figures :ref:`Hypothesis for a Polar Substituent<figure_gameplan_polar>` and
   :ref:`Hypothesis for a Nonpolar/VDW Substituent<figure_gameplan_nonpolar>`).

#. A (possibly empty) section showing stabilizing and destabilizing water sites
   (figure :ref:`Stabilizing Site<figure_gameplan_stbl>`).

.. _figure_gameplan_ligand:

.. figure:: /_images/vida23-gp-ligand.png
   :width: 1000
   :align:  center

   **Ligand Compared to apo Binding Site**

.. _figure_gameplan_polar:

.. figure:: /_images/vida24-gp-polar.png
   :width: 1000
   :align:  center

   **Hypothesis for a Polar Substituent**

.. _figure_gameplan_nonpolar:

.. figure:: /_images/vida25-gp-nonpolar.png
   :width: 1000
   :align:  center

   **Hypothesis for a Nonpolar/VDW Substituent**

.. _figure_gameplan_stbl:

.. figure:: /_images/vida26-gp-stbl.png
   :width: 1000
   :align:  center

   **Stabilizing Site**

Annotations are:

   + **Yellow mesh sphere:** polar site; the size of the sphere indicates
     the magnitude of the polar interaction.

   + **Green mesh sphere:** van der Waals site; the size of the sphere indicates
     the magnitude of the VDW interaction.

   + **Green translucent sphere:** non-polar site.

   + **Purple top:** mismatch site, where the ligand polarity does not match that of the solvent.

   + **Small green and red spheres:** stabilizing and destabilizing points, respectively.

Based on your results, you may want to modify your ligand to make it more
compatible with the *apo* pocket solvent electrostatics, add a substituent based
on the suggested hypotheses, displace a destabilizing water or carefully replace
a stabilizing water, mimicking the interactions of the water.



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _gameplan_help:

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing **Gameplan**
with the `--help` option.

.. code-block:: console

   > gameplan --help

will generate the following output:

::

   Help functions:
     gameplan --help simple      : Get a list of simple parameters
     gameplan --help all         : Get a complete list of parameters
     gameplan --help defaults    : List the defaults for all parameters
     gameplan --help <parameter> : Get detailed help on a parameter
     gameplan --help html        : Create an html help file for this program
     gameplan --help versions    : List the toolkits and versions used in the application


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _gameplan_req_params:

=================================
Required Parameters
=================================
.. option:: -target <filename>
   -protein <filename>
   -p <filename>

   [keyless parameter 1]

   The format must be one that retains partial charges: OEBinary, Tripos .mol2, or
   DelPhi flavor PDB (where there is radii in the occupancy field and
   charge in the B-factor field).

   The file format of the input file is automatically determined from
   the file extension. The extensions *.oeb*, *.oeb.gz* can be
   OEBinary; *.oedu for OEDesignUnit; *.mol2* for Tripos Mol2 files;
   *.pdb* for PDB format files.

   ============ ===========================
   File type    Extension
   ============ ===========================
   OEDesignUnit .oedu
   ------------ ---------------------------
   OEBinary     .oeb .oeb.gz
   ------------ ---------------------------
   PDB(DelPhi)  .pdb .ent .pdb.gz .ent.gz
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz
   ============ ===========================

   .. warning::

      By default, charges and radii are expected to be in this file
      and the results will be meaningless if they are missing. The
      program :ref:`SPRUCE <chapter_spruce>` is provided to prepare the
      biomolecular structure including assigning charges and radii.

.. _gameplan_opt_params:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


=================================
Optional Parameters
=================================

Input Options
--------------

.. option:: -ligand <filename>
   -l <filename>

   [keyless parameter 2]

   If an OEDesignUnit was used as input for the protein, and it contained a ligand
   the ligand from this will be used unless otherwise specified.

   The format can be one that retains partial charges: OEBinary, Tripos .mol2, or
   DelPhi flavor PDB (where there is radii in the occupancy field and
   charge in the B-factor field).

   .. note::

      If no charges are present on the read molecule, AM1BCC charges and Zap9 radii
      are assigned to the molecule.

Output Options
--------------

.. option:: -prefix <prefix>

   Prefix used to name output files. Using ``-prefix FOO``
   will create results in an OEBinary file named ``FOO.oeb.gz``
   (see :option:`-output`).
   Additionally, a parameter file named ``FOO.param`` (see :option:`-param`)
   and a log file named ``FOO.log`` (see :option:`-log`).

   [Default=gameplan]

.. option:: -output <filename>
   -o <filename>

   [keyless parameter 3]

   OEBinary output file (*.oeb* or *.oeb.gz*), containing calculated
   results.

   If not specified, :option:`-prefix` will be used to name the output.

Parameters
-------------

.. option:: -merge <number>

   [Default=0.35 |A|]

   Distance cutoff for merging two sample points.

.. option:: -sp3_aromatic <bool>
   -sp3aromatic <bool>

   Sample sp3 hybridization at each aromatic ligand atom.

   [Default=false]

.. option:: -stabilization <bool>
   -stbl <bool>

   Search for regions where water is stabilized or destabilized
   by in the protein/ligand complex.

   [Default=true]

.. option:: -clean <bool>

   Remove temporary files written by :ref:`chapter_szmap` during this run of gameplan.

   [Default=true]

.. option:: -light_background
   -light_bkg

   If specified, annotation colors will be adjusted to better match a white background.
   By default, they are chosen to match a dark background.

.. option:: -warn_if_missing_hydrogens

   If specified, missing hydrogens will not terminate the program,
   but will instead generate a warning message. Otherwise, missing hydrogens on the
   ligand or on more than 10 percent of the protein heavy atoms will cause *gameplan* to fail.

.. option:: -num_orientations <number>
   -rot <number>

   Number of orientations for the SZMAP probe.

   [Default=60]

MPI Options
-------------

.. option:: -szmap_mpi_np <number>

   Run :ref:`chapter_gameplan` calculations in MPI multiprocessor mode using the
   specified number of processors.  If an MPI hostfile is not specified with
   the -mpi_hostfile option all processor will be launched on the local machine.

.. option:: -szmap_mpi_hostfile <filename>

   Run :ref:`chapter_gameplan` calculations in MPI multihost mode using the
   specified MPI hostfile.  If an MPI hostfile is not specified all
   processes will be run on the local machine.  The hostfile format
   is a text file with each line specifying a machine and the number
   of processes to launch on it.

   The following example hostfile specified 3 hosts that can run up to
   4, 2 and 5 processes respectively.

   ::

      host1.mydomain.com slots=4
      host2.mydomain.com slots=2
      host3.mydomain.com slots=5

   This example hostfile would typically be used with -szmap_mpi_np 11 to make
   use of all the processors (4+2+5=11).

   Note that multiprocessor is only supported on the local machine under
   Windows, and in homogeneous environments for other architectures (i.e.,
   machines with the same operating system environment).

Other Options
-------------

.. option:: -param <filename>

   Defines the control parameter file. This file can contain a collection
   of parameters which can be used instead of writing each parameter to the command-line.
   In addition, the parameter file written by any gameplan run (see :option:`-prefix`)
   can be used with the :option:`-param` flag in subsequent gameplan runs. Any
   command given explicitly on the command line will supersede any command found
   in a file specified with the :option:`-param` flag.

.. option:: -logfile <filename>
   -log <filename>

   If specified, this will override the filename created from :option:`-prefix`.
   Specify ``-log -`` to send to *standard-output*.

.. option:: -progress <style>

   How to display :ref:`chapter_szmap` progress information:

   ======= =========================================
   Style   Output
   ======= =========================================
   none    no progress shown
   ------- -----------------------------------------
   dots    print a period (.) for every point tested
   ------- -----------------------------------------
   percent print percentage complete every 10 points
   ------- -----------------------------------------
   log     print percentage to log file
   ======= =========================================

   [Default=dots]

.. option:: -verbose
   -v

   Print additional information to log during calculations.


*********************************
Utilities
*********************************

.. toctree::
   :maxdepth: 2

   szmap_grid
   grid_comp
   szmap_report



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_szmap_grid:

*********************************
SzmapGrid
*********************************

=================================
Overview
=================================

The :program:`szmap_grid` utility reads an OEBinary (*.oeb* or *.oeb.gz*) file
generated by :ref:`chapter_szmap` and displays information about the grids within.
If atom property tags from a :ref:`chapter_szmap` ``-at_coords`` calculation are found,
it will list the all property names.

=================================
Example Commands
=================================

::

   > szmap_grid 4std_stbl.oeb.gz 

   szmap-meta-data attached to molecule 1, 'complex: PROTEIN (SCYTALONE DEHYDRATASE) + residue 'BFS''.
   'mask_grid' dimensions: 38 29 33
   'neut_diff_free_energy_grid' dimensions: 38 29 33
   'vdw_grid' dimensions: 38 29 33
   'order_grid' dimensions: 38 29 33

   szmap-meta-data attached to molecule 2, 'ligand: residue 'BFS''.
   'lig_mask_grid' dimensions: 38 29 33
   'neut_diff_lig_free_energy_grid' dimensions: 38 29 33
   'lig_vdw_grid' dimensions: 38 29 33
   'lig_order_grid' dimensions: 38 29 33

   szmap-meta-data attached to molecule 3, 'apo: PROTEIN (SCYTALONE DEHYDRATASE)'.
   'apo_mask_grid' dimensions: 38 29 33
   'neut_diff_apo_free_energy_grid' dimensions: 38 29 33
   'apo_vdw_grid' dimensions: 38 29 33
   'apo_order_grid' dimensions: 38 29 33

   szmap-meta-data attached to molecule 4, 'stabilization'.
   'stbl_mask_grid' dimensions: 38 29 33
   'neut_diff_stbl_free_energy_grid' dimensions: 38 29 33
   'stbl_vdw_grid' dimensions: 38 29 33
   'stbl_order_grid' dimensions: 38 29 33

   Input appears to be the results file from a SZMAP grid calculation.
   SZMAP grids but no -at_coords property tags in input file.

   > szmap_grid 2w3a_coords.oeb.gz 

   szmap-meta-data attached to molecule 1, 'apo: TOP'.
   atom property tags: szmap_mask, szmap_neut_diff_free_energy, szmap_neut_diff_enthalpy,
   szmap_neut_diff_entropy, szmap_vdw, szmap_order, szmap_vac_diff_free_energy,
   szmap_vac_diff_enthalpy, szmap_vac_diff_entropy, szmap_free_energy, szmap_enthalpy,
   szmap_entropy, szmap_neutral_free_energy, szmap_neutral_enthalpy,
   szmap_neutral_entropy, szmap_interaction, szmap_psolv, szmap_wsolv, szmap_intvdw,
   szmap_probe_burial, szmap_clash

   szmap-meta-data attached to molecule 2, 'apo: DIHYDROFOLATE REDUCTASE+ion+cofact'.

   Input appears to be the results file from a SZMAP -at_coords calculation.
   SZMAP -at_coords property tags but no grids in input file.

:program:`szmap_grid` can also split a given grid out into a separate grid file. The
output grid can be in OEBinary, Grasp, CCP4, or ascii format. Since *PyMOL*
can read Grasp *.phi* maps, they provide a way to transfer grids from :ref:`chapter_szmap` to *PyMOL*.

::

   > szmap_grid 4std_stbl.oeb.gz neut_diff_apo_free_energy_grid 4std_nddG.phi

The options ``-output_all_format`` and ``-prefix`` will generate a separate grid file
for all grids in the :ref:`chapter_szmap` results.

::

   > szmap_grid -output_all_format .phi -prefix 4std 4std_stbl.oeb.gz

If the :program:`szmap_grid` option ``-at_coords`` is used,
the specified grid's values will be interpolated
at the coordinates of any atoms in the input coordinates file and written out attached to those atoms
in a file defined by :option:`-mol` for use by other tools.
A tab-delimited table of these results is written to *standard-output*.

::

   > szmap_grid -at_coords coords.sdf -mol out.oeb szmap.oeb.gz vdw_grid >table.txt

.. note::

   A direct calculation at these coordinates using
   :ref:`chapter_szmap` will be superior to these interpolated values.

Meta-data
================================================================================

:ref:`chapter_szmap` attaches meta-data to molecules in the results file that documents run conditions.
This data is displayed when the :program:`szmap_grid` option :option:`-verbose` is used.

::

   szmap-meta-data attached to molecule 1, 'complex: PROTEIN (SCYTALONE DEHYDRATASE) + residue 'BFS''.

   points: grid
   system: complex
   prot-title: PROTEIN (SCYTALONE DEHYDRATASE)
   prot-num-atoms: 2680
   prot-num-bonds: 2720
   lig-title: residue 'BFS'
   lig-num-atoms: 33
   lig-num-bonds: 34
   dielectric-model: gaussian
   eps-outer: 80
   eps-inner: 1
   salt-conc: 0.05M
   probe-type: water
   orientations: 60
   rotation-matrices: symmetrical
   mask-cutoff: 0
   mask: calculation=1.01
   mask: bulk solvent=0.99
   mask: clash=0
   grid-spacing: 0.5A
   zap-spacing: 0.5A
   zap-iters: 5
   run-date: Jan 23 2013
   run-time: 10:48:03
   version: 20130123
   release: 1.1.1
   arch: redhat-RHEL5-x64
   platform: redhat-RHEL5-g++4.1-x64
   licensee: Initech
   site: Austin

The meta-data includes the version and release of :ref:`chapter_szmap` used to generate
the results. Early releases used a different format, ``version: 110`` for version 1.1.0.

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing **SzmapGrid**
with the `--help` option.

.. code-block:: console
   
   > szmap_grid --help

will generate the following output:

::

   Help functions:
     szmap_grid --help simple      : Get a list of simple parameters
     szmap_grid --help all         : Get a complete list of parameters
     szmap_grid --help defaults    : List the defaults for all parameters
     szmap_grid --help <parameter> : Get detailed help on a parameter
     szmap_grid --help html        : Create an html help file for this program
     szmap_grid --help versions    : List the toolkits and versions used in the application

=================================
Required Parameters
=================================

.. option:: -input_mol <filename>
   -i <filename>

   [keyless parameter 1]

   OEBinary input file (*.oeb* or *.oeb.gz*), with calculated
   grids attached to copy input molecule(s).

=================================
Optional Parameters
=================================

Grid Options
==============

.. option:: -grid <name>
   -g <name>

   [keyless parameter 2]

   Grid to extract or display information about. Name must be one of the grid names
   listed in :ref:`chapter_appendix1`.

   If not specified, information will be displayed about all grids.

.. option:: -output_grid <filename>
   -o <filename>

   [keyless parameter 3]

   The file format of the output grid file is automatically determined from
   the file extension.

   ============== ===========================
   File type      Extension                  
   ============== ===========================
   OE grid        .grd .grd.gz               
   -------------- ---------------------------
   Grasp grid     .phi .phi.gz               
   -------------- ---------------------------
   Ascii grid     .agd .agd.gz               
   -------------- ---------------------------
   CCP4 map       .map .map.gz .ccp .ccp.gz  
   .ccp4 .ccp4.gz                            
   ============== ===========================

   Use :option:`-output_all_format` instead to write all grids into separate files.

.. option:: -output_all_format <format>
   -all <format>

   Write out every grid to individual files in the specified format.
   Used in conjunction with :option:`-prefix`.

   ============== ===========================
   File type      Format                     
   ============== ===========================
   OE grid        .grd .grd.gz               
   -------------- ---------------------------
   Grasp grid     .phi .phi.gz               
   -------------- ---------------------------
   Ascii grid     .agd .agd.gz               
   -------------- ---------------------------
   CCP4 map       .map .map.gz .ccp .ccp.gz  
   .ccp4 .ccp4.gz                            
   ============== ===========================

.. option:: -prefix <text>

   Filename prefix for grid files written when :option:`-output_all_format` is specified.
   Can include file path in addition to the beginning portion of the filename.

   [Default=szmap_grid]

.. option:: -slice

   Print grid values to *standard-output* as a series of 2D tabular slices.

.. option:: -std_box <filename>

   Write *standard* (complex) grid bounding box to
   output 'box molecule' coordinate file.

   ============ ===========================
   File type    Extension                  
   ============ ===========================
   SDF          .sdf .mol .sdf.gz .mol.gz  
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz             
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz  
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz             
   ------------ ---------------------------
   OEBinary     .oeb .oeb.gz               
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges.

.. option:: -lig_box <filename>

   Write *ligand* grid bounding box to
   output 'box molecule' coordinate file.

   ============ ===========================
   File type    Extension                  
   ============ ===========================
   SDF          .sdf .mol .sdf.gz .mol.gz  
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz             
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz  
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz             
   ------------ ---------------------------
   OEBinary     .oeb .oeb.gz               
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges.

.. option:: -apo_box <filename>

   Write *apo* grid bounding box to
   output 'box molecule' coordinate file.

   ============ ===========================
   File type    Extension                  
   ============ ===========================
   SDF          .sdf .mol .sdf.gz .mol.gz  
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz             
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz  
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz             
   ------------ ---------------------------
   OEBinary     .oeb .oeb.gz               
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges.

.. option:: -box_mol <filename>

   Write *box_mol* bounding box to
   output 'box molecule' coordinate file,
   if a *box_mol* is found in the input *.oeb*
   file.

   ============ ===========================
   File type    Extension                  
   ============ ===========================
   SDF          .sdf .mol .sdf.gz .mol.gz  
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz             
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz  
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz             
   ------------ ---------------------------
   OEBinary     .oeb .oeb.gz               
   ============ ===========================

   To facilitate visualization,
   box corners are represented by nitrogen
   atoms and bonds define the box edges.

Interpolation Options
=======================

.. option:: -at_coords <filename>
   -coords <filename>

   Interpolate the values of the selected grid
   (and the corresponding mask grid) at the coordinates
   of atoms in any molecules in the file. Write
   those molecules, with the (masked) results attached
   to the atoms, to the output file.

   ============ ===========================
   File type    Extension                  
   ============ ===========================
   SDF          .sdf .mol .sdf.gz .mol.gz  
   ------------ ---------------------------
   MOL2         .mol2 .mol2.gz             
   ------------ ---------------------------
   PDB          .pdb .ent .pdb.gz .ent.gz  
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz             
   ------------ ---------------------------
   OEBinary     .oeb .oeb.gz               
   ============ ===========================

   One of the following tags will be used when assigning
   values to atoms (without any ``apo_`` or ``lig_``):
   
   + *szmap_mask*
   + *szmap_neut_diff_free_energy*
   + *szmap_neut_diff_enthalpy*
   + *szmap_neut_diff_entropy*
   + *szmap_vac_diff_free_energy*
   + *szmap_vac_diff_enthalpy*
   + *szmap_vac_diff_entropy*
   + *szmap_free_energy*
   + *szmap_enthalpy*
   + *szmap_entropy*
   + *szmap_neutral_free_energy*
   + *szmap_neutral_enthalpy*
   + *szmap_neutral_entropy*
   + *szmap_interaction*
   + *szmap_psolv*
   + *szmap_wsolv*
   + *szmap_vdw*
   + *szmap_intvdw*
   + *szmap_probe_burial*

.. option:: -output_mol <filename>
   -mol <filename>

   OEBinary output file (*.oeb* or *.oeb.gz*), with interpolated
   grid values attached to :option:`-at_coords` molecule's atoms.

   [Default=szmap_grid_interp.oeb.gz]

.. option:: -no_table

   Do not print a tab-delimited table of interpolated grid values to
   *standard-output* when :option:`-at_coords` is the selection.

.. option:: -mask_cutoff <number>

   Points where interpolated mask values are less than or equal to this cutoff
   will have values attached to atoms set to 0.0. The default
   value tries to account for the edges of the masked area where
   interpolation can generate distorted results.

   [Default=0.8]

Other Options
===============

.. option:: -verbose
   -v

   Print additional grid details (and *SZMAP* meta-data) to *standard-output*.



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_grid_comp:

*********************************
GridComp
*********************************

=================================
Overview
=================================

The **GridComp** utility reads grids,
from an OEBinary file (*.oeb* or *.oeb.gz*) generated by
:ref:`chapter_szmap`, or from an individual grid file,
and performs an operation, usually producing a grid file
containing the results. It is designed to make it easy to compare
grids and produce new types of grids by combining others. It handles
grids with different shapes or that do not completely overlap and will
interpolate if the grid points are not aligned.

**GridComp** can compute the sum, difference, average and other
mathematical transformations of grids. The operations *set_above*,
*set_below*, *mask*, and *not_mask* are used to truncate grids.

The operations *total* and *integrate* are the only ones that do
not require an output grid. They write summary statistics describing a grid to
standard output.

The operations *lig_disp* and *prot_disp* take a :ref:`chapter_szmap`
results OEBinary file and produce another OEBinary file containing
additional results for the region in the *apo* pocket displaced by the ligand when the complex
if formed or the region around the ligand displaced by the protein in the complex, respectively.

The operations *mask_all* and *stabilization* also processes an OEBinary file to produce another.

=================================
Example Commands
=================================

A common operation is to append data to :ref:`chapter_szmap` output
for the region in the *apo* protein where the ligand
displaces solvent in the complex:

::

   > grid_comp -op lig_disp -i 4std_stbl.oeb.gz -o 4std_stbl_disp.oeb.gz

:ref:`chapter_szmap` output contains masks that can be used, for example, to define
the region that the *integrate* operation sums over:

::

   > grid_comp integrate my.oeb.gz     free_energy_grid same mask_grid > int.txt
   > grid_comp integrate my.oeb.gz apo_free_energy_grid same mask_grid >>int.txt
   > grid_comp integrate my.oeb.gz lig_free_energy_grid same mask_grid >>int.txt

In the example above, the complex *mask_grid* is used for all integrations
so that the results can be combined to yield a solvent correction to *ZAP bind*:
(*complex* + *bulk*) - (*apo* + *ligand*), 
where *bulk* = 0.0. The free energy grids used,
which are not the same as the *difference* free energy grids,
are only available if **SZMAP** is run with the option ``-results_set max``.
Usually, the grid *file* and the grid *name* are specified in pairs.
The keyword ``same`` used in the example above refers to the same file as the
energy grid, *my.oeb.gz*, and is just used for convenience.

The following command creates a mask file defining regions where the
van der Waals energy in the complex is less than or equal to -2 kcal/mol (*low.grd.gz*)
and applies the mask to the complex neutral difference free energy grid to produce
the file *nddG.grd.gz* containing a subset of that grid:

::

   > grid_comp -leq -2.0 make_mask my.oeb.gz vdw_grid same point_grid low.grd.gz
   > grid_comp mask my.oeb.gz neut_diff_free_energy_grid low.grd.gz na nddG.grd.gz

The keyword ``na`` stands for not-applicable and is a convenience used to skip the grid_name field
(which is not needed because the file *low.grd.gz* contains only one grid),
allowing all the parameters to be specified without having to sprinkle the command line
with a large number of -flags.

=================================
Command Line Help
=================================

A description of the command line interface can be obtained by executing **GridComp**
with the `--help` option.

.. code-block:: console
   
   > grid_comp --help

will generate the following output:

::

   Help functions:
     grid_comp --help simple      : Get a list of simple parameters
     grid_comp --help all         : Get a complete list of parameters
     grid_comp --help defaults    : List the defaults for all parameters
     grid_comp --help <parameter> : Get detailed help on a parameter
     grid_comp --help html        : Create an html help file for this program
     grid_comp --help versions    : List the toolkits and versions used in the application

=================================
Required Parameters
=================================

.. option:: -operation <value>
   -op <value>

   [keyless parameter 1]

   Operation to be performed on grid(s). The *scale* operation
   scales by :option:`-scale`. Operations *set_above*
   and *set_below* use cutoff values of :option:`-cutoff`
   and set values to :option:`-new_value`. The *total* and *integrate*
   operations treat :option:`-input_file2` / :option:`-grid2`
   as a mask (mask values above
   :option:`-masked_point_cutoff` are summed) and write the result
   to standard output. If an optional third (point) grid is supplied
   for *total* and *integrate*, the second grid is treated as an energy
   grid and the mask is built on-the-fly.

   ============= ====== ============================================
   Value         Type   Operation                                   
   ============= ====== ============================================
   sum           binary Sum of the two grid values                  
   ------------- ------ --------------------------------------------
   diff          binary Difference of the two grid values           
   ------------- ------ --------------------------------------------
   min           binary Minimum of the two grid values              
   ------------- ------ --------------------------------------------
   max           binary Maximum of the two grid values              
   ------------- ------ --------------------------------------------
   avg           binary Average of the two grid values              
   ------------- ------ --------------------------------------------
   mul           binary Multiply the two grid values                
   ------------- ------ --------------------------------------------
   total         binary Display total of values within mask         
   ------------- ------ --------------------------------------------
   integrate     binary Display integral of values within mask      
   ------------- ------ --------------------------------------------
   make_mask     binary Build a mask from value and point grids     
   ------------- ------ --------------------------------------------
   mask          binary Keep values only in masked regions          
   ------------- ------ --------------------------------------------
   not_mask      binary Keep values only outside of masked regions  
   ------------- ------ --------------------------------------------
   lig_disp      binary Add apo data displaced in complex by ligand 
   ------------- ------ --------------------------------------------
   prot_disp     binary Add lig data displaced in complex by protein
   ------------- ------ --------------------------------------------
   scale         unary  Multiply values by scale factor             
   ------------- ------ --------------------------------------------
   offset        unary  Add an offset to each grid value            
   ------------- ------ --------------------------------------------
   set_above     unary  Modify values that are above cutoff         
   ------------- ------ --------------------------------------------
   set_below     unary  Modify values that are below cutoff         
   ------------- ------ --------------------------------------------
   largest       unary  Grid subset within the largest contour      
   ------------- ------ --------------------------------------------
   stabilization unary  Calculate stabilization grids               
   ------------- ------ --------------------------------------------
   mask_all      unary  Build and apply a mask to all grids         
   ============= ====== ============================================

   Binary operations require two grids and unary operations
   require only one. The *lig_disp*, *prot_disp*, *mask_all*,
   and *stabilization* operations work on the entire
   set of grids in the *.oeb* input file and do not take
   a grid name. They do, however, require the output file to
   be an *.oeb* file.

   The operations *total* and *integrate* send numerical results to
   *standard-out* but can also optionally write an output grid if a
   mask is calculated on-the-fly.

   The operation *largest* makes contour surfaces based on :option:`-cutoff`
   and suppresses values outside of the largest contour region.

.. option:: -input_file1 <filename>
   -in1 <filename>
   -i <filename>

   [keyless parameter 2]

   Grid file to operate on. If an OEBinary file is used,
   :option:`-grid1` must be specified.
   The file format of the grid file is automatically determined from
   the file extension.

   =============== =============================================
   File type       Extension                                    
   =============== =============================================
   OEBinary        .oeb .oeb.gz (requires :option:`-grid1`)     
   --------------- ---------------------------------------------
   OE grid         .grd .grd.gz                                 
   --------------- ---------------------------------------------
   Grasp grid      .phi .phi.gz                                 
   --------------- ---------------------------------------------
   Ascii grid      .agd .agd.gz                                 
   --------------- ---------------------------------------------
   CCP4 map        .map .map.gz .ccp .ccp.gz                    
   .ccp4 .ccp4.gz                                              
   =============== =============================================

=================================
Optional Parameters
=================================

Grid Options
------------

.. option:: -grid1 <name>

   [keyless parameter 3]

   Grid in OEBinary input_file1 to operate on. 
   
   Name must be one of the grid names
   listed in :ref:`chapter_appendix1`.

   A value of *na* is used with keyless options when the grid
   is in a separate grid file and not attached to an OEBinary file.

.. option:: -input_file2 <filename>
   -in2 <filename>

   [keyless parameter 4]

   Grid file to operate on. If an OEBinary file is used,
   :option:`-grid2` must be specified.
   The file format of the grid file is automatically determined from
   the file extension.

   =============== =============================================
   File type       Extension                                    
   =============== =============================================
   OEBinary        .oeb .oeb.gz (requires :option:`-grid2`)     
   --------------- ---------------------------------------------
   OE grid         .grd .grd.gz                                 
   --------------- ---------------------------------------------
   Grasp grid      .phi .phi.gz                                 
   --------------- ---------------------------------------------
   Ascii grid      .agd .agd.gz                                 
   --------------- ---------------------------------------------
   CCP4 map        .map .map.gz .ccp .ccp.gz                    
   .ccp4 .ccp4.gz                                              
   =============== =============================================

   A value of *same* is used to refer to the same file as :option:`-input_file1`.

   A value of *na* is used with keyless options when :option:`-input_file2`
   is not required.

.. option:: -grid2 <name>

   [keyless parameter 5]

   Grid in OEBinary input_file2 to operate on.

   Name must be one of the grid names
   listed in :ref:`chapter_appendix1`.

   A value of *na* is used with keyless options when the grid
   is not an OEBinary file or the grid will not be used.

.. option:: -input_file3 <filename>
   -in3 <filename>

   Grid file to operate on. Contains the (point) grid
   required when :option:`-leq_mask` or :option:`-geq_mask`
   is used with operation ``total`` or ``integrate``
   to create the mask on the fly.

   If an OEBinary file is used,
   :option:`-grid3` must be specified.
   The file format of the grid file is automatically determined from
   the file extension.

   =============== =============================================
   File type       Extension                                    
   =============== =============================================
   OEBinary        .oeb .oeb.gz (requires :option:`-grid3`)     
   --------------- ---------------------------------------------
   OE grid         .grd .grd.gz                                 
   --------------- ---------------------------------------------
   Grasp grid      .phi .phi.gz                                 
   --------------- ---------------------------------------------
   Ascii grid      .agd .agd.gz                                 
   --------------- ---------------------------------------------
   CCP4 map        .map .map.gz .ccp .ccp.gz                    
   .ccp4 .ccp4.gz                                              
   =============== =============================================

   A value of *same* is used to refer to the same file as :option:`-input_file2`.

   A value of *na* is used with keyless options when :option:`-input_file3`
   is not required.

.. option:: -grid3 <name>

   Grid in OEBinary input_file3 to operate on.

   Name must be one of the grid names
   listed in :ref:`chapter_appendix1`.

   A value of *na* is used with keyless options when the grid
   is not an OEBinary file or the grid will not be used.

.. option:: -output_grid <filename>
   -o <filename>

   [keyless parameter 6]

   Not used with the operations: *total* and *integrate*.

   The file format of the output grid file is automatically determined from
   the file extension.

   =============== ===========================
   File type       Extension                  
   =============== ===========================
   OE grid         .grd .grd.gz               
   --------------- ---------------------------
   Grasp grid      .phi .phi.gz               
   --------------- ---------------------------
   Ascii grid      .agd .agd.gz               
   --------------- ---------------------------
   CCP4 map        .map .map.gz .ccp .ccp.gz  
   .ccp4 .ccp4.gz                            
   =============== ===========================

   For ``remask`` operation, the file must be in OEBinary format (with extension .oeb or .oeb.gz).

Parameter Options
-----------------

.. option:: -leq_mask <number>
   -leq <number>

   When generating a mask for the operations ``total`` and
   ``integrate``,
   values in grid2 equal to or less than this are counted as
   in the mask if the value of the corresponding point in grid3 is > 
   :option:`-masked_point_cutoff`.
   Grid2 is often the ``intvdw_grid`` and grid3 is often ``point_grid``.

   When used with the operation ``make_mask``, values of grid1 equal to
   or less than this are counted in the mask if the value of the 
   corresponding point
   in grid2 is > :option:`-masked_point_cutoff`.

   When used with the operation ``mask_all``, values of *intvdw_grid*,
   *apo_intvdw_grid* and *lig_intvdw_grid* equal to
   or less than this are counted in the mask if the value of the corresponding point
   in *point_grid*, *apo_point_grid* or *lig_point_grid* is greater than :option:`-masked_point_cutoff`.

.. option:: -geq_mask <number>
   -geq <number>

   When generating a mask for the operations ``total`` and
   ``integrate``,
   values in grid2 equal to or greater than this are counted as
   in the mask if the value of the corresponding point in grid3 is 
   > :option:`-masked_point_cutoff`.
   Grid2 is often the ``intvdw_grid`` and grid3 is often ``point_grid``.

   When used with the operation ``make_mask``, values of grid1 equal to
   or greater than this are counted in the mask if the value of the 
   corresponding point
   in grid2 is > :option:`-masked_point_cutoff`.

   When used with the operation ``mask_all``, values of *intvdw_grid*,
   *apo_intvdw_grid* and *lig_intvdw_grid* equal to
   or greater than this are counted in the mask if the value of the corresponding point
   in *point_grid*, *apo_point_grid* or *lig_point_grid* is greater than :option:`-masked_point_cutoff`.

.. option:: -cutoff <number>

   Cutoff value for *set_above*, *set_below*, and *largest* operations.

   [Default=0.0]

.. option:: -masked_point_cutoff <number>

   Cutoff value for the mask. Mask values greater than this are selected.
   The (strict) default selects both calculation (1.01) and solvent (0.99) points.

   [Default=0.98]

.. option:: -new_value <number>
   -to <number>

   Value assigned to values beyond the cutoff with the
   *set_above* and *set_below* operations.

   [Default=0.0]

.. option:: -by <number>
   -scale <number>

   Amount grid values are multiplied by with the *scale* operator
   or amount added to grid values with the *offset* operator.

   [Default=1.0]

.. option:: -default_value <number>
   -default <number>

   Value assigned to points where grids do not overlap
   and assigned to unselected points during *mask* and *mask_all*
   operations.

   [Default=0.0]

.. option:: -int_method <value>
   -method <value>

   Method used when performing the integrate operation.

   ========= ========================================================
   Value     Meaning                                                 
   ========= ========================================================
   voxel     Sum masked values and scale by grid voxel/water volume  
   --------- --------------------------------------------------------
   average   Average masked values and scale by excluded/water volume
   --------- --------------------------------------------------------
   grow      Grow edge values into the excluded volume and average   
   ========= ========================================================

   [Default=voxel]

.. option:: -mask_vdw

   Override behavior of ``mask_all`` operation to use *vdw_grid*
   rather than *intvdw_grid*, etc.

Other Options
-------------

.. option:: -verbose
   -v

   Print additional grid details to *standard-error*.



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_szmap_report:

..  program:: szmap_report

*********************************
SzmapReport
*********************************

=================================
Overview
=================================

The :program:`szmap_report` utility reads an OEBinary file (*.oeb* or *.oeb.gz*)
generated by using the ``-at_coords`` flag with :ref:`chapter_szmap` and produces a
*.pdf* file containing one or more 2-dimensional renderings of the results. The calculated
values for a given property are shown as colored patches around each coordinate position.
(You can also visualize these properties in 3D using :ref:`chapter_colorprops`).
Atoms at coordinates with no calculated property, because the probe clashed when placed there,
are grayed out.

.. note::

   Versions of :ref:`chapter_szmap` prior to 1.1.0 attach only a limited number
   of properties to atoms. To display *vdw* or *order*, for example, you may need to rerun
   calculations with the latest :ref:`chapter_szmap` version.

If a concatenated series of molecules are used as input to ``szmap -at_coords``, :program:`szmap_report`
will produce a figure for each molecule. You can control the formatting to either place
the output for each molecule on a separate page, or align the output for different molecules
on the same page.

By default option :option:`-surface` is *true*, meaning a 2D surface boundary for
the molecule is shown with different line types depending on how loose or tight the
binding site is around each atom. Boundary styles are: simple black lines for close contacts,
lines with short radial lines indicate a small gap, and outward reaching fingers indicate a cavity,
a place with enough space to place a water or other atoms. Thin gray lines indicate
a solvent exposed region.

If hydrogens are in the output, they are usually suppressed from the display.
If you want to display data calculated at hydrogen positions, use :option:`-keep_hydrogens`,
but because surfaces are rendered only for heavy atoms, :option:`-surface` must also set to false.

The output is rendered by OpenEye's **OEDepict** and **Grapheme** toolkits (additional licenses not required).
See figure :ref:`SZMAP report output<figure_szmap_report_output>`.

.. _figure_szmap_report_output:

.. figure:: /_images/4std_3up_szmap_report.png
   :width: 1000
   :align:  center

   **SZMAP report output**

=================================
Example Commands
=================================

.. code-block:: bash

   prompt> szmap_report 4std_lig_coords.oeb.gz 4std_lig_coords.pdf

This executes **SzmapReport** with the default parameters.  The file
`4std_lig_coords.oeb.gz` containing **SZMAP** `-at_coords` results
is used as input, and the output is written to the file `4std_lig_coords.pdf`,

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing **SzmapReport**
with the ``--help`` option.

.. code-block:: console

   > szmap_report --help

will generate the following output:

::

   Help functions:
     szmap_report --help simple      : Get a list of simple parameters
     szmap_report --help all         : Get a complete list of parameters
     szmap_report --help defaults    : List the defaults for all parameters
     szmap_report --help <parameter> : Get detailed help on a parameter
     szmap_report --help html        : Create an html help file for this program
     szmap_report --help versions    : List the toolkits and versions used in the application

=================================
Required Parameters
=================================
.. option:: -input <filename>
   -i  <filename>

   [keyless parameter 1]

   OEBinary input file (*.oeb* or *.oeb.gz*), with results calculated
   at specified coordinates.

=================================
Optional Parameters
=================================

.. option:: -output <filename>
   -o   <filename>

   [keyless parameter 2]

   Output .pdf file containing one or more 2D renderings.

   [Default=szmap_report.pdf]

.. option:: -tagname <prop>
   -t <prop>

   [keyless parameter 3]

   Atom property used to generate color patches around each atom:

   Prop must be one of the property names
   listed in :ref:`chapter_appendix2`. The list of tags for
   a given results file can be displayed by :ref:`chapter_szmap_grid`.

   The *szmap_neut_diff_free_energy* property is one of the most
   useful. It describes the hydrophilicity/hydrophobicity at each coordinate.

   If no tag is specified, an array of properties will be displayed for each input molecule.

Molecule Display Options
------------------------

.. option:: -aromstyle <style>
   -astl <style>

   Aromatic ring display style: *Kekule, Circle, Dash*.

   [Default=Kekule]

.. option:: -atomcolor <color>
   -acolor <color>

   Atom coloring style: *WhiteCPK, BlackCPK, WhiteMonochrome, BlackMonochrome, cow, cob, bow, wob*.

   ===== ========================================
   Style Meaning
   ===== ========================================
   cow   (color on white) same as WhiteCPK
   ----- ----------------------------------------
   cob   (color on black) same as BlackCPK
   ----- ----------------------------------------
   bow   (black on white) same as WhiteMonochrome
   ----- ----------------------------------------
   wob   (white on black) same as BlackMonochrome
   ===== ========================================

   [Default=WhiteCPK]

.. option:: -atomstereostyle <style>
   -atomsstl <style>

   Atom stereo display style: *Hidden, AtomStereo, StandardStyle, FancyStyle*.
   Combined expressions: Created by combining primitive tokens with "|".

   [Default=AtomStereo|FancyStyle]

.. option:: -bondcolor <color>
   -bcolor <color>

   Bond coloring style: *ByElement, Monochrome*.

   [Default=ByElement]

.. option:: -bondstereostyle <style>
   -bondsstl <style>

   Bond stereo display style: *Hidden, BondStereo, CIPBondStereo*.
   Combined expressions: Created by combining primitive tokens with "|".

   [Default=BondStereo]

General Options
---------------

.. option:: -title <text>

   Title for each page.

   [Default="SZMAP Report"]

.. option:: -pagesize <size>
   -size <size>

   Output file page size: *US_Letter, A4*.

   [Default=US_Letter]

.. option:: -rows <number>

   Number of rows on a page [1-10].

.. option:: -cols <number>

   Number of columns on a page [1-10].

.. option:: -resolution <level>

   Quality of color maps representing properties.
   The level will influence the size of the output---*high* produces output several times larger than *medium* produces.

   ====== ========================================
   Level  Meaning
   ====== ========================================
   low    chunky (grain size: 5 x 5)
   ------ ----------------------------------------
   medium smooth (grain size: 2 x 2)
   ------ ----------------------------------------
   high   very smooth (grain size: 1 x 1)
   ====== ========================================

   [Default=medium]

.. option:: -separate

   Output separate pages for each at_coords molecule. The default is to concatenate output. Use :option:`-rows` and :option:`-cols` to adjust the formatting.

.. option:: -legend <bool>

   Show property legend.

   [Default=true]

.. option:: -surface <bool>

   Show 2D molecular surface outline.

   [Default=true]

.. option:: -keep_hydrogens

   Show all the explicit hydrogens in depictions. Requires :option:`-surface` to be set to false.

   [Default=false]

.. option:: -tag_set <set>

   Tag set used when no explicit tag is specified. The set 'v1' is provided
   for backwards compatibility with *SZMAP* version 1 results.

   ================== ======================================================
   Set                Meaning
   ================== ======================================================
   min                szmap_neut_diff_free_energy, szmap_vdw, szmap_order
   ------------------ ------------------------------------------------------
   max                szmap_neut_diff_free_energy, szmap_neut_diff_entropy,
   szmap_interaction, szmap_vdw, szmap_psolv, szmap_wsolv
   ------------------ ------------------------------------------------------
   v1                 szmap_neut_diff_free_energy, szmap_probe_burial
   ================== ======================================================

   [Default=min]

Other Options
-------------

.. option:: -verbose
   -v

   Print status information to *standard-error*.



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


*********************************
VIDA Extensions
*********************************

.. _part_extensions:

.. toctree::
   :maxdepth: 2

   vida_intro
   vida_install_ext
   vida_watercolor
   vida_waterorient
   vida_colorprops



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _vida_szmap_intro:

********************************************************************************
Introduction
********************************************************************************

There are three *VIDA* extensions for working with :ref:`chapter_szmap` output:

#. The :ref:`chapter_waterorient` identifies key waters and analyzes their energies and orientational constraints.

#. The :ref:`chapter_watercolor` changes the display styles of :ref:`chapter_szmap` grids and
   :ref:`chapter_gameplan` annotation to facilitate analysis.

#. The :ref:`chapter_colorprops` colors molecules based on properties calculated
   at atomic coordinates.



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_installextensions:

********************************************************************************
Installing VIDA Extensions
********************************************************************************

See the *VIDA* manual (http://www.eyesopen.com/documentation/)
for a complete description of how to use
the program, including installation of the extensions that are 
included in the *SZMAP* distribution. This section
will give a brief description of how to install the extensions.

The *VIDA* extensions are located in
::

   {SZMAP Version Examples}/vida_extensions/{vida-version}/

The extensions are organized by VIDA version number:

   + **4.2.1** - the :ref:`chapter_watercolor` v1.7.7,
     the :ref:`chapter_colorprops` v1.3.0 and the :ref:`chapter_waterorient` v1.1.2.
     These extensions can be used with *VIDA* versions 4.2.1 or higher.

You can check your version of *VIDA* using the *Help >> About...* menu.

.. note::
   If you already have previous versions of any *SZMAP* extensions installed in
   *VIDA's* *Extensions* menu, go to the *Edit >> Extensions...* menu
   and unsubscribe using the *Manage Subscriptions...* button or, if one or more
   *SZMAP* extension has been installed separately, uninstall by clicking the red "X".
   Then restart *VIDA*.

If you have not already installed *SZMAP*, do so before installing the extensions.

.. _figure_subscribe1:

.. figure:: /_images/subscribe1.png
   :width: 1000
   :align:  center

   **Add the Subscription**

To install the *SZMAP* extensions: open *VIDA* and select the *Edit >> Extensions...* menu item,
then click on the small folder icon in the *Get More Extensions* section at the bottom of the window.
Browse to the ``{SZMAP Version Examples}/vida_extensions/{vida-version}/``
directory/folder,
and open the file called ``szmap_extensions.pyxs`` that packages the extensions.
Then click :ref:`Add<figure_subscribe1>` to subscribe to the extensions. Each extension will
show up in the upper part of the window and be added to the *Extensions* menu.

.. Note::
   By mistake, *SZMAP* 1.0.0 installed the extensions in a location without
   a *SZMAP* version number in the directory path and these old extensions
   could be confused with the current versions of the extensions.
   Make sure you load extensions from the path shown above,
   where ``{szmap-version}`` is |release| and ``{vida-version}`` corresponds to the version
   of VIDA you are using or earlier.

You should now be able to select the *SZMAP* extensions in the *Extensions* menu.
You will need to select :ref:`chapter_watercolor` each time you open
:ref:`chapter_szmap` or :ref:`chapter_gameplan` results in *VIDA*, but the other
extensions only need to be selected when the control panel is not visible.



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_watercolor:

********************************************************************************
WaterColor VIDA Extension
********************************************************************************

The *WaterColor* extension is used to set-up :ref:`chapter_szmap`
and :ref:`chapter_gameplan` output in *VIDA*.

For :ref:`chapter_szmap` grids, it alters the contour surface display properties.
It sets up a standard color scheme for grids, sets some grids to solid surfaces
while leaving others wire-mesh,
sets up any difference grids to show both positive (yellow) and negative (purple) contours,
and sets the contour levels to "reasonable" default values. Feel free to change any of
the properties afterwards.
It also restricts the display of protein atoms to just those that surround the ligand
and turns on the display of both the protein and the ligand. And protein molecular surface
is added to the protein, but not displayed by default.

For :ref:`chapter_gameplan` results, the extension makes the annotation visible. It also
restricts the protein and ligand display and generates a molecular surface as described for grids.

This extension is not required to analyze ``-at_coords`` results but if engaged,
will set the protein and ligand display as above, along with the molecular surface.

See :ref:`chapter_installextensions` for information on installing this extension.

Viewing Results Grids
---------------------

   .. _figure_vida1:

   .. figure:: /_images/vida1-browse.png
      :width: 1000
      :align:  center

      **Browse View**

* Step 1
   Open *VIDA* and make sure the 3D viewer, the *list* panel
   and the *style* panel are available. If not, select the *Browsing* view
   (figure :ref:`Browse View<figure_vida1>`) to setup your display.
   You can move the *list* and *style* panels to as needed---here, we
   have stacked them on top of one another to save space.

   .. _figure_vida2:

   .. figure:: /_images/vida2-select-arrow.png
      :width: 1000
      :align:  center

      **List Panel**

* Step 2
   Select *File >> Open* and choose the *.oeb.gz* or *.oeb* file containing
   your :ref:`chapter_szmap` grid results.
   The file should show up in the :ref:`List Panel<figure_vida2>`
   and the structure should show in the 3D viewer.

   .. _figure_vida3:

   .. figure:: /_images/vida3-show+resize.png
      :width: 1000
      :align:  center

      **Showing Grids**

   Click on the > triangle beside the molecule name to show the contents and expand
   the list panel to show the full contents
   (figure :ref:`Showing Grids<figure_vida3>`).

   .. _figure_vida4:

   .. figure:: /_images/vida4-contour1.png
      :width: 1000
      :align:  center

      **Select Grid**

* Step 3
   Clicking on the grid name will show that grid
   (figure :ref:`Select Grid<figure_vida4>`) but
   the molecule is now deselected and just the grid
   contour is shown.

   .. _figure_vida9:

   .. figure:: /_images/vida9-isolevel.png
      :scale:  75
      :align:  center

      **Isolevel**

   You may
   have to change the contour level slider in the style
   panel to see the contour
   (figure :ref:`Isolevel<figure_vida9>`).

   .. _figure_vida4b:

   .. figure:: /_images/vida4b-watercolor.png
      :width: 1000
      :align:  center

      **WaterColor Extension**

* Step 4
   Run the *WaterColor* extension
   (figure :ref:`WaterColor Extension<figure_vida4b>`),
   to set the contour levels to better
   starting values and also change the colors and
   rendering styles so that the various grids are
   easily distinguish.
   These settings can be modified using the style panel.
   It also hides all protein atoms that are not near to the
   binding site.
   Finally, it generates a molecular surface associated with the protein
   that shows the boundary of the binding
   site. This surface can be selected and displayed in the same way as a grid.

   .. _figure_vida5:

   .. figure:: /_images/vida5-contour+mol.png
      :width: 1000
      :align:  center

      **Molecule and Grid**

* Step 5
   After *WaterColor* runs, the ligand and protein should have a green dot in the visibility column.
   If it is not visible, click on the *neut_diff_apo_free_energy* list item to show
   that grid in the context of the input molecules
   (figure :ref:`Molecule and Grid<figure_vida5>`).

* Step 6
   The scene can be scaled (or zoomed) by holding down the
   Middle mouse button by itself, the Left and Right mouse
   buttons together, or by using the mouse wheel. The scene can
   also be scaled using the W and S keys on the keyboard.

   .. _figure_vida6:

   .. figure:: /_images/vida6-center.png
      :scale:  75
      :align:  center

      **Center**

   .. _figure_vida7:

   .. figure:: /_images/vida7-lightning.png
      :scale:  75
      :align:  center

      **Select**

   You may also need to recenter by clicking on the center button
   to the left of the 3D viewer (figure :ref:`Center<figure_vida6>`).

   Click on the lightning bolt to
   get out of centering mode and back to selection mode
   (figure :ref:`Select<figure_vida7>`).

   You can pan by holding down the shift key as you drag the mouse.

   If you need to adjust the clipping planes, use the + and -
   buttons in the Graphics style panel
   (figure :ref:`Clipping<figure_vida11>`).

   .. _figure_vida11:

   .. figure:: /_images/vida11-clipping.png
      :scale:  75
      :align:  center

      **Clipping**

   .. _figure_vida8:

   .. figure:: /_images/vida8-surf-color.png
      :scale:  75
      :align:  center

      **Surface Style**

* Step 7
   You can change the color of the grid and switch between wireframe
   lines, solid surface, and point clouds (select the ^ button above the surface 
   icon at the bottom of the 3D display
   figure :ref:`Surface Style<figure_vida8>`;
   points have jitter added).

   .. _figure_vida10:

   .. figure:: /_images/vida10-transparency.png
      :scale:  75
      :align:  center

      **Transparency**

   When using a solid surface,
   it can be useful to set the surface transparency in the style
   menu to, say, 70% (figure :ref:`Transparency<figure_vida10>`).

   .. _figure_vida13:

   .. figure:: /_images/vida13-add-contours.png
      :scale:  75
      :align:  center

      **Adding Contours**

   You can increase the number of contours for a given grid
   with the + button in the contour style panel
   (figure :ref:`Adding Contours<figure_vida13>`).

   .. _figure_vida12:

   .. figure:: /_images/vida12-multiple-contours.png
      :width: 1000
      :align:  center

      **Multiple Grids**

* Step 8
   Overlapping contours from different grids requires that you select
   all the grids in the list panel (figure :ref:`Multiple Grids<figure_vida12>`).
   This can be a little counter-intuitive;
   play with multiple selections until you get the hang of it.

   .. hint::

      Only select one grid at a time if you are trying to change
      the color or style or transparency to a value different
      from other grids.

   .. _figure_vida14:

   .. figure:: /_images/vida14-diffgrid.png
      :width: 1000
      :align:  center

      **Difference Grid**

* Step 9
   *Difference* grids represent the difference between standard water
   and uncharged water, a proxy for hydrophobic atoms in the ligand.
   The *WaterColor* extension configures them as
   a pair of contours: negative in yellow representing
   areas where standard water has lower values---for :math:`\Delta G` 
   and :math:`\Delta H`
   standard water is more favorable here---and positive in purple
   representing areas where uncharged water has lower values
   (figure :ref:`Difference Grid<figure_vida14>`).
   The hydrophobic/hydrophilic pattern within a site is matched
   by high-affinity ligands.

   .. _figure_vida15:

   .. figure:: /_images/vida15-vdwgrid.png
      :width: 1000
      :align:  center

      **VDW Grid**

   *Van der Waals* grids show a component of the energy
   that is not a part of the difference free energy (because it subtracts out).
   The default VDW (green) contours are -2 kcal/mol, containing the lowest 5% (approx.)
   of the negative VDW waters (figure :ref:`VDW Grid<figure_vida15>`). Low VDW regions
   are found in regions with weak polar interactions. Conversely, regions with
   strong polar interactions have positive VDW energy. The balance between
   Coulombic interactions and VDW interactions defines the masked, or nonclashing,
   region.

   .. _figure_vida16:

   .. figure:: /_images/vida16-ordergrid.png
      :width: 1000
      :align:  center

      **Order Grid**

   *Order* grids (light blue mesh) show the fraction of water entropy lost due to electrostatic
   interactions (figure :ref:`Order Grid<figure_vida16>`).
   A value of 1.0 means the site is highly ordered and displacing water from there will
   liberate almost all this rotational entropy (approximately 2.4 kcal/mol). A value of 0.0 means
   the water orientation is completely degenerate and displacing it will not liberate any
   rotational entropy. The energy gained by displacing water is primarily entropic,
   enthalpy mainly serves as a filter that discriminates between different ligands.

   .. _figure_vida17:

   .. figure:: /_images/vida17-maskgrid.png
      :width: 1000
      :align:  center

      **Mask Grid**

   *Mask* grids (gray mesh) are an accurate description of the *solvent accessible surface*,
   calculated as regions where the minimum *Coulombic interaction* + *VDW* energy is below a threshold
   (figure :ref:`Mask Grid<figure_vida17>`). Examining the mask grid clarifies where water
   fits and where it clashes. The displaced region of the *apo* pocket contains the volume
   of the *apo* mask minus that of the complex mask. To speed up ligand calculations
   during a stabilization run, the ligand analysis is limited to the region within
   the complex mask, by default. In "at_coords" calculations, points that are not
   in the mask are labeled "CLASH".

   .. _figure_vida18:

   .. figure:: /_images/vida18-stblgrid.png
      :width: 1000
      :align:  center

      **Stabilization Grid**

   *Stabilization* grids
   are special kinds of difference grids (*complex - apo - ligand*),
   showing how water is stabilized
   or destabilized upon binding (figure :ref:`Stabilization Grid<figure_vida18>`).
   They provide information about the possible
   effects of modifying the ligand.

   If you have calculated *displacement* grids---with *apo* data in regions where water has
   been displaced---these will be found at the end of the list of items in the results.
   Examining them can clarify how far a ligand's reach extends.

   Other grids can be produced but these capture the main elements required to understand solvation.

* Step 10
   **Explore!**

Viewing Gameplan Results
------------------------

   .. _figure_vida21:

   .. figure:: /_images/vida1-browse.png
      :width: 1000
      :align:  center

      **Browse View**

* Step 1
   Open *VIDA* and make sure the 3D viewer, the list panel
   and the style panel are available. If not, select the *Browsing* view
   (figure :ref:`Browse View<figure_vida21>`) to setup your display.

   .. _figure_vida22:

   .. figure:: /_images/vida_gameplan_list_window.png
      :scale:  75
      :align:  center

      **Gameplan List Window**

* Step 2
   Select *File >> Open* and choose the *.oeb.gz* or *.oeb* file
   containing your :ref:`chapter_gameplan` results.
   The file should show up in the list panel
   (figure :ref:`Gameplan List Window<figure_vida22>`;
   the blue bar identifies the active entry)
   and the ligand structure should show in the 3D viewer.

   .. _figure_vida23a:

   .. figure:: /_images/vida-pref-bkgd.png
      :width: 1000
      :align:  center

      **Changing Background**

.. note::

   The figures shown here have a white background which is recommended for
   presentations and publications. You can change the background color in
   *VIDA* by bringing up the *Edit >> Preferences* window
   (*Vida >> Preferences* on Mac OS X),
   selecting *3D Display* and then clicking on the *OpenGL* tab
   (figure :ref:`Changing Background<figure_vida23a>`).

* Step 3
   Run the *WaterColor* extension to activate the display of annotation
   explaining the various ligand modification hypotheses.
   It also adds a surface that shows the boundary of the binding
   site, and hides all protein atoms that are not near to the
   binding site. These settings can be modified using the style
   panel.

   .. _figure_vida23:

   .. figure:: /_images/vida23-gp-ligand.png
      :width: 1000
      :align:  center

      **Ligand Compared to apo Binding Site**

* Step 4
   The first entry analyzes how the ligand
   (figure :ref:`Ligand Compared to apo Binding Site<figure_vida23>`)
   Yellow mesh spheres show polar sites, green mesh spheres are van der Waals sites,
   translucent green spheres are non-polar sites, and purple diamonds indicate
   a mismatch, where the ligand is either much more or much less polar than the binding site.
   See chapter :ref:`chapter_gameplan` for a complete description of the
   annotation symbols.

   .. _figure_vida24:

   .. figure:: /_images/vida24-gp-polar.png
      :width: 1000
      :align:  center

      **Hypothesis for a Polar Substituent**

   .. _figure_vida25:

   .. figure:: /_images/vida25-gp-nonpolar.png
      :width: 1000
      :align:  center

      **Hypothesis for a Nonpolar/VDW Substituent**

* Step 5
   Next comes the *apo*-protein, then a series of
   hypotheses for ligand modification.

   Scarlet colored bonds indicate a proposed modification
   to the ligand. Gameplan tries to explore a wide
   range of possible ways to improve the ligand, and has an
   option that permits the hybridization to differ from
   that in the original ligand. See the 
   ``-sample_hybridization`` option in chapter :ref:`chapter_gameplan`
   for details.

   Using the arrow keys to step between the different
   hypotheses, you will
   see yellow cages around atoms where water makes good polar
   interactions (figure :ref:`Hypothesis for a Polar Substituent<figure_vida24>`),
   green cages around atoms
   where water has good van der Waals energy,
   and translucent green balls around atoms
   where a fluorine or methyl group may be a good fit
   (figure :ref:`Hypothesis for a Nonpolar/VDW Substituent<figure_vida25>`).

   The same substituent may show up with different
   conformations or under different categories.

   .. _figure_vida26:

   .. figure:: /_images/vida26-gp-stbl.png
      :width: 1000
      :align:  center

      **Stabilizing Site**

* Step 6
   Finally points where
   water is stabilizing (green) or destabilizing (red) the complex are enumerated
   (figure :ref:`Stabilizing Site<figure_vida26>`).
   Destabilizing points may be good candidates for displacement, while
   stabilizing points can be left in place. But if a stabilizing site
   contains highly ordered water in the complex, careful replacement
   of this water with a substituent that makes the same number of interactions
   can liberate as much as 2 kcal/mol of rotational entropy.



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_waterorient:

********************************************************************************
Water Orientation VIDA Extension
********************************************************************************

Using
-----

.. _figure_waterorient_energy:

.. figure:: /_images/waterorient-energy.png
   :width: 1000
   :align:  center

   **Water Orientations With Energy Coloring**

The *Water Orientation* extension provides a means of accessing
the calculated properties of key water sites and orientations stored
within an :ref:`chapter_szmap` results OEBinary file. The figure
:ref:`Water Orientations With Energy Coloring<figure_waterorient_energy>` shows
an example of the display, with dominant points colored and labeled by their
*SZMAP* energy and the highest probability probe orientations indicated
(yellow: negative energies, purple: positive energies). 

See :ref:`chapter_installextensions` for information on installing
the extension.

To get started, load :ref:`chapter_szmap` results into *VIDA*---both grid calculations
or ``-at_coords`` calculations will work. Highlight part of the results in the list window
and run the :ref:`chapter_watercolor`.
Then, if the *Water Orientation* panel is not already open, open it from the extensions menu.
Select the set of orientation data you want
to display with the *Apply to* pop-up in the panel and press the *Update* button.
The *Water Orientation* extension
will analyze the orientations and add a package of points and water orientations to *VIDA's*
list window, colored by the selected color scheme, *by Energy* by default. Points
and water orientations can be displayed or hidden independently.

The numbers by each point
(energies or order parameters) always refer to all orientations collectively,
not any particular orientation, even if only one orientation is visible for a point.
The same is true of the color schemes, except for *by Probability*
where each orientation is colored differently (although the order parameter numbers
still refer to the ensemble).

Changing the filtering controls does not update the display until you press *Update*
again. Pressing the *Duplicate* button makes a duplicate copy of the package of points
and water orientations.

.. _figure_waterorient_interface:

.. figure:: /_images/waterorient-interface.png
   :width: 1000
   :align:  center

   **Grid Point Filtering Panel**

The :ref:`Grid Point Filtering Panel<figure_waterorient_interface>`
controls which points are displayed. It is generally
useful to show only the key points: those with the lowest or highest energies in each
region. The range sliders select which energies are excluded from display---values between
-0.5 and +0.5 kcal/mol are ignored by default. The range control is labeled with the type of
energy used: *neutral difference free energy* for results from *SZMAP* 1.1.0 and later,
*neutral difference enthalpy* for results from earlier versions of *SZMAP*.
*Pruning* is an operation that picks points
with the lowest or highest energies and then excludes nearby points where energies are closer
to 0.0 kcal/mol. The *Min. Order* slider controls the display of degenerate points, locations
where waters have little or no orientational preference. The default of 5% will only skip the
most degenerate points.

.. _figure_waterorient_interface_p2:

.. figure:: /_images/waterorient-interface-p2.png
   :width: 1000
   :align:  center

   **Orientation Filtering Panel**

The :ref:`Orientation Filtering Panel<figure_waterorient_interface_p2>`
controls the number of orientations displayed for each point shown. By
default the most probable orientations are show for each point with
favorable energies (< 0.0 kcal/mol), up-to a cumulative probability
of 50%. Since points with unfavorable energies are mostly degenerate
we usually simplify them, only showing the single most probable orientation.
Occasionally, it is useful to show more unfavorable orientations by
un-checking the *Simplify Unfavorable Points* check-box as was done to make
the figure :ref:`Water Orientations With Energy Coloring<figure_waterorient_energy>`.

.. _figure_waterorient_interface_p3:

.. figure:: /_images/waterorient-interface-p3.png
   :width: 1000
   :align:  center

   **Focus Panel**

The :ref:`Focus Panel<figure_waterorient_interface_p3>` allows you to select
one or more points generated by the *Water Orientation* extension and,
by pressing the *Focus* button, clear the display of all but the selected points.
Pressing *all* shows all the points once again. To select a point, click on the
cross at the center of each position (not the orientations) and to select
multiple points, use shift-click. Turning off the display of the water orientations
(the "probe" sub-section in the *VIDA* List window) can make it easier to click on the points.

.. _figure_waterorient_split1:

.. figure:: /_images/waterorient-split1.png
   :width: 1000
   :align:  center

   **Split One**

.. _figure_waterorient_split2:

.. figure:: /_images/waterorient-split2.png
   :width: 1000
   :align:  center

   **Click on Hydrogen**

.. _figure_waterorient_split3:

.. figure:: /_images/waterorient-split3.png
   :width: 1000
   :align:  center

   **After Split**

The :ref:`Split Panel<figure_waterorient_split1>`
provides a means of converting individual water orientations into
a separate molecule (including :ref:`chapter_szmap` partial charges)
which can be saved by *VIDA* and used in other calculations.
For example, a particularly structured water can be split out and
saved and then added to the protein as part of a :ref:`chapter_szmap`
calculation. To use it, you press the *Split Orientation* button
(figure :ref:`Split One<figure_waterorient_split1>`)
and then click on one of the hydrogens in the orientation you want
to split (figure :ref:`Click on Hydrogen<figure_waterorient_split2>`).
The selected water orientation will be reproduced as an individual
molecule (figure :ref:`After Split<figure_waterorient_split3>`)
which can be written out to a file, if required.

.. _figure_waterorient_order:

.. figure:: /_images/waterorient-order.png
   :width: 1000
   :align:  center

   **Order Coloring**

Changing the color-scheme results in an immediate update of the current
display. Besides the :ref:`Energy Coloring<figure_waterorient_energy>`
shown above, there are three other color-schemes. In figure
:ref:`Order Coloring<figure_waterorient_order>`, each point is colored light-blue with brighter
colors indicating more ordered positions and darker colors indicating more
degenerate positions. Order represents a transformation of the entropy term
to normalize it between 0% and 100%, where a value of 0% represents a degenerate
point where all orientations are equivalent and 100% is a completely ordered point. 

.. _figure_waterorient_prob:

.. figure:: /_images/waterorient-prob.png
   :width: 1000
   :align:  center

   **Probability Coloring**

In figure
:ref:`Probability Coloring<figure_waterorient_prob>`, each orientation is colored green with brighter
colors indicating more probable orientations. This color-scheme is the only one that
will display multiple colors for different orientations a position,
whereas energy and order colors are *ensemble* properties.

.. _figure_waterorient_wat:

.. figure:: /_images/waterorient-wat.png
   :width: 1000
   :align:  center

   **Water Coloring**

Finally, figure
:ref:`Water Coloring<figure_waterorient_wat>` shows the color-scheme where probe orientations
are colored according to the CPK colors for the corresponding atoms, red for oxygen and
white for hydrogen.

Stick Display
-------------

As shown in the figures above, individual orientations are rendered as thin (wireframe) lines.
Numerical energies and orientations are associated with the ensemble at each point and do not
refer to any particular orientation.

For presentations, it is usually better to "fatten-up" these lines by changing the rendering
style.

.. _figure_waterorient_select_probes:

.. figure:: /_images/water-orient-select-probes.png
   :width: 1000
   :align:  center

   **Selecting the Probes**

First, open up the orientation package in the list window and select the probes
(figure :ref:`Selecting the Probes<figure_waterorient_select_probes>`).

.. _figure_waterorient_stick:

.. figure:: /_images/water-orient-stick.png
   :width: 1000
   :align:  center

   **Render as Sticks**

Next, change the display style
(figure :ref:`Render as Sticks<figure_waterorient_stick>`). 

.. _figure_waterorient_stick_display:

.. figure:: /_images/water-orient-stick-display.png
   :width: 1000
   :align:  center

   **Stick Display**

Then, click on the background to unselect the probes
(figure :ref:`Stick Display<figure_waterorient_stick_display>`). 

.. _figure_waterorient_bkground:

.. figure:: /_images/vida-pref-bkgd.png
   :width: 1000
   :align:  center

   **Changing Background**

For presentations and publications, a white background which is recommended.
You can change the background color in
*VIDA's* Preferences/3D Display/OpenGL window
(figure :ref:`Changing Background<figure_waterorient_bkground>`).

   .. _figure_waterorient_label:

   .. figure:: /_images/vida-pref-label.png
      :width: 1000
      :align:  center

      **Changing Text Label Color**

You can also adjust the text label color by choosing
*VIDA's* *File >> Preferences* menu (*Vida >> Preferences* on MacOS X)
selecting *3D Display* and clicking on the *General* tab
(figure :ref:`Changing Text Label Color<figure_waterorient_label>`).

   .. _figure_waterorient_colorscheme1:

   .. figure:: /_images/water-orient-colorscheme1.png
      :width: 1000
      :align:  center

      **White Background**

The result (see
figure :ref:`White Background<figure_waterorient_colorscheme1>`)
is works well for presentations. But most versions of *VIDA*
recolor carbon to green when the background color is white.

   .. _figure_waterorient_colorscheme2:

   .. figure:: /_images/water-orient-colorscheme2.png
      :width: 1000
      :align:  center

      **Gray Carbons**

If necessary, you can change atom colors as follows.
Using *VIDA's* *Edit >> Select >> Query menu item*, selecting carbon
either from the menu or by typing ``C`` (for aliphatic carbons)
or ``c`` (for aromatic carbons) in the query box,
and using the color pop-up at the bottom of the 3D window to
change the carbon color to gray, will usually produce a
more pleasing result
(see figure :ref:`Gray Carbons<figure_waterorient_colorscheme2>`).



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_colorprops:

********************************************************************************
Color By Atom Properties
********************************************************************************

The *Color by Atom Properties* extension provides a method
for displaying the results in an OEBinary file from a :ref:`chapter_szmap` calculation
performed using the ``-at_coords`` option. You can also view properties using
:ref:`chapter_szmap_report`.

.. _figure_colorprops_output:

.. figure:: /_images/colorprops-output.png
   :width: 1000
   :align:  center

   **Color By Atom Properties**

:ref:`chapter_szmap` results generated with ``-at_coords`` contain the molecule specified
by the ``-at_coords`` parameter with :ref:`chapter_szmap` results tagged as properties associated
with each atom. While these property values can be displayed as atom labels using
*VIDA's* generic property labeling function,
the *Color by Atom Properties* extension makes it easy to survey
these values by coloring the atoms of the active molecule
based on a color gradient defined by selected *SZMAP* data as shown in figure
:ref:`Color By Atom Properties<figure_colorprops_output>`. Individual waters split out by the
:ref:`chapter_waterorient` are also tagged with properties that this extension can interpret.

.. _figure_colorprops_interface:

.. figure:: /_images/colorprops-interface.png
   :width: 1000
   :align:  center

   **Color By Atom Properties Interface Panel**

See :ref:`chapter_installextensions` for information on installing
the extension.

Bring up the control panel by selecting the *Extensions >> Color by Atom Properties* pull-down menu.
The extension will only color atoms when the control panel is open.
The extension (see figure :ref:`Color By Atom Properties Interface Panel<figure_colorprops_interface>`)
is composed of several elements:

* **Active molecule**
  is the *at_coords* entry selected in the *VIDA* list window: complex, ligand, *apo,* stabilization, etc.

* **Property**
  drop-down box to select the calculated *SZMAP* property to display.
  Any property in any open molecule will be listed, even if only some properties are associated with the selected molecule.

* **Range Sliders**
  (gray vertical bars in the color gradient) specify the range of
  values over which the three-color gradient will apply. Note atoms with values beyond
  the range selected will still be displayed, and will be colored by the respective high or low color. 

* **Three Color Boxes**
  on the lower left set the low, middle, and high color values
  for the color gradient. Atoms containing values within the range selected by the
  *Min. Value* and *Max. Value* sliders are colored using a linear interpolation between these colors.  

* **Missing Values**
  checkbox explicitly sets the color of atoms for which *SZMAP* values
  were not calculated. Checking this checkbox ensures that atoms determined to be masked out
  during the :ref:`chapter_szmap` calculations are colored a different color (specified by the color box on the lower right)
  to differentiate them from atoms that have a calculated value near zero. Missing values are found where the water probe *clashes*.

* **Symmetric around zero**
  checkbox enforces a symmetric range where the absolute value
  of the *Min. Value* and the *Max Value* are equal. Activating this checkbox ensures that
  the positive and negative color scales are equivalent, and also dictates that the color
  selected as the middle color in the gradient will represent a value of zero.

* **Lock middle color to zero**
  checkbox sets the color of atoms with values close
  to 0.0 to the middle color even if the negative and positive ranges are of different magnitudes.


.. _szmap_tutorials:

*********************************
Tutorials
*********************************

.. toctree::
   :maxdepth: 2

   szmap_tutorial_intro
   szmap_tutorial_prep
   szmap_tutorial_run
   szmap_tutorial_ana
   szmap_tutorial_coords
   szmap_tutorial_gameplan



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _szmap_tutorial_intro:

=======================
SZMAP Workflow
=======================

The sections represent a tutorial, going through
a typical workflow and analysis of the PDB entry 4STD.
Example input and output files and a list of commands for the following workflow
are found in 
``{SZMAP Version Examples}/tutorial_files``
Images are provided to guide the user when visualizing
*SZMAP* results.

The workflow consists of three basic parts:

   + Preparing molecules so that they can be used as
     input to :ref:`chapter_szmap` or :ref:`chapter_gameplan`.

   + Running :ref:`chapter_szmap` or :ref:`chapter_gameplan`.

   + Analyzing the results in *VIDA* with the help of the *SZMAP* extensions.


.. _szmap_tutorial_prep:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. index:: Preparation

=================================
Protein and Ligand Preparation
=================================

In this section :ref:`SPRUCE <chapter_spruce>` is used to prepare the proteins. You are free to
use alternative methods to perform this and other "prep" tasks.

.. note::

   If pre-prepared structures in *.oedu fileformat* from :ref:`SPRUCE <chapter_spruce>` are available, these can
   directly be used as input and the rest of this page can be skipped.
   When using OEDesignUnits, note that they potentially include both solvent and
   a bound ligand, depending on the structure. There are two flags that are crucial to keep
   in mind, ``-excludeDUsolvent`` and ``-excludeDUligand``, to control whether those two
   components should be part of the calculation or not.

Good protein and ligand preparation is vital before running :ref:`chapter_szmap`
or :ref:`chapter_gameplan`. This consists of building partial sidechains, capping chains breaks,
adding hydrogens, and assigning partial charges, and atomic radii.

The commands below are shown in a form appropriate for Linux and macOS.
When you install *SZMAP* on *Windows*, a pre-configured version of the DOS command
prompt is constructed and can be used to run any *SZMAP* program or utility without
any extra setup. This window can be found under the *Start* menu in
*All Apps  >> OpenEye-applications >> OpenEye-applications {version} Command line*.

First, examine your structure in *VIDA*. *VIDA* can read gzipped structure
files as-is and has the *File >> Open Special >> From PDB* menu command to fetch structures from the
Protein Data Bank directly.

.. _figure_vida_split_sel:

.. figure:: /_images/vida-split-selected.png
   :width: 1000
   :align:  center

   **File >> New Molecule >> From Split >> Selected**

The structure for 4STD is a trimer with the ligand some distance from the protein/protein
interface. If you wish to delete detergents or other extraneous molecules, select everything you want to keep
and make sure they are *not* selected. Then go to the menu item and split out the piece desired.
:ref:`File >> New Molecule >> From Split >> Selected<figure_vida_split_sel>`.
Alternatively, you may prefer to edit your molecule by hand as follows.
If your structure file is gzipped PDB file, unzip it. Edit it to delete extra subunits,
detergent, or other extraneous molecules using whichever text editor you prefer.
It is not necessary to remove the waters at this stage, they wil be split out later.
It is also not necessary to prune the connection table---any references to deleted atoms will be ignored

Since :ref:`chapter_szmap` and :ref:`chapter_gameplan` require explicit hydrogen atoms
on the molecules and most PDB structures do not include the hydrogen atoms,
the next steps produce a protein structure with all the hydrogen atoms explicitly represented.
There are many ways to do this. Here, we will use :ref:`SPRUCE <chapter_spruce>`, the application will automatically
generate biologically relevant units from the asymmetric unit (if needed), enumerates alternate locations,
builds partial sidechains, caps chain breaks, places and optimizes protons including tautomer searching
for ligands and co-factors. The alterante location enumeration and biological unit generation, means the application
can output multiple structures based on the input unit.

::

   >  spruce -in 4std.pdb -prefix szmap_

     szmap_4STD_A__DU__BFS_A-173.oedu

In this case the application wrote one structure into three files, the target/receptor structure,
the automatically detected ligand, and a molecule containing the solvent. In these files the molecules
have already had charges and radii assigned. If the ligand molecule is < 100 atoms, it will have AM1BCC charges
assigned along with Zap9 radii, otherwise it will have MMFF charges assigned and Bondi radii.
Protein molecules will have AmberFF94 charges assigned for any standard amino acid residue and AM1BCC
for nonstandard residues. The function will fall back to assign the entire protein MMFF94 charges if there
is a failure. Nucleic acids will have MMFF94 charges assigned. Water molecules are assigned SZMAP water parameters,
described further in the :ref:`chapter_water_model` chapter of the SZMAP toolkit.


.. _szmap_tutorial_run:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


=========================================
Running SZMAP Stabilization Calculations
=========================================

Assuming the input structures have been prepared as described above,
:ref:`chapter_szmap` grids can be calculated
for the region around the ligand as follows:

::

   > szmap -mpi_np 4 -prefix 4std_stbl -stbl -p 4STD_ABC__DU__BFS_A-173.oedu -excludeDUsolvent

   or

   > szmap -mpi_np 4 -prefix 4std_stbl -stbl -p 4STD_A__DU__BFS_A-173_target.oeb.gz -l 4STD_A__DU__BFS_A-173_ligand.oeb.gz

.. note::

   The option ``-excludeDUsolvent`` is needed to exclude structural waters from the stabilization calculation if the input is
   using a design unit.

Stabilization calculations can also be performed with a dataset of pre-posed non-native ligands, using the commands below.

::

   > szmap -mpi_np 4 -prefix 4std_stbl -stbl -p 4STD_ABC__DU__BFS_A-173.oedu -excludeDUsolvent -l posed_ligands.oeb

Calculations for *complex, apo,* and *ligand* grids will be done
(requiring about 40 minutes for this example on Linux using four 2.8GHz processors)
and then further processed to yield
*(complex - apo - ligand)* stabilization
grids, describing where water is stabilizing or destabilizing the
binding reaction. The output consists of the calculated grids in an *.oeb.gz* file, along
with a parameter file and a log file, all with names prefixed with "4std_stbl".

To run on only a single processor, drop the ``-mpi_np #`` option.
More information on options can be found in chapter :ref:`chapter_szmap`.

.. note::

   :ref:`chapter_szmap` (and :ref:`chapter_gameplan`) will check for missing hydrogens
   and missing partial charges and halt if they are missing on the protein, but that will typically
   not be a problem if the input is an OEDesignUnit. It also shouldn't be a problem with the ligand
   read from an OEDesignUnit, however, if a ligand is passed with missing partial charges, they will be assigned
   AM1BCC charges and Zap9 radii. If reading from a PDB, sometimes, OEChem will have a different
   opinion about the charge or bond order than what you expect. For example, if your structure has
   significantly nonterminal geometry around an aromatic or double bond,
   OEChem may try to treat it as a single bond. The option ``-warn_if_missing_hydrogens``
   will allow you to run :ref:`chapter_szmap` and :ref:`chapter_gameplan` despite OEChem
   thinking there are hydrogens that are not explicitly in your structure. But you may
   also need to change the formal charge of a polar group before running pch, either in
   *VIDA's* builder or by modifying the structure file using a text editor.


.. _szmap_tutorial_ana:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


=====================================
Analyzing SZMAP Results
=====================================

Determining the Ligand Displacement Region
------------------------------------------

The results can be processed with :ref:`chapter_grid_comp` to break-out
the region of the *apo* grid that has been displaced by the ligand.

::

   > grid_comp -op lig_disp -i 4std_stbl.oeb.gz -o 4std_stbl_disp.oeb.gz

While not required, these displacement grids can be useful.
For example, they can be used to identify
precisely which waters are displaced by each of a series of substituents.
They also make it easy to determine the volume of water displaced by
the ligand.

Analyzing Grid Results
-------------------------------

:ref:`chapter_szmap` grid results can be visualized in *VIDA* using the
:ref:`chapter_watercolor` (sets grid styles for viewing---the
link leads to information about the extension) and the :ref:`chapter_waterorient`
(shows water orientational preferences). If *VIDA* is in your command search path,
the following command will open *VIDA* and load the file *4std_stbl_disp.oeb.gz*.
*VIDA* can also be launched by clicking on the *VIDA* icon and the file can then
be loaded using the *Open...* command in the *File* menu. You can also drag and
drop molecule files onto a *VIDA* instance.

::

   > vida 4std_stbl_disp.oeb.gz

.. note::

   *VIDA* extensions need to be installed before they can be used. For instructions,
   see :ref:`chapter_installextensions`.

The neutral difference *(water - uncharged)* grids map the polarity throughout the site and
the stabilization grids describe the binding reaction *(complex - apo - ligand)*:
they have negative energies where water enhances binding affinity and positive where
it decreases binding affinity.

.. _figure_lig_disp:

.. figure:: /_images/4std_lig_disp_grid.png
   :width: 1000
   :align:  center

   **Displaced Neutral Difference Free Energy**

The figure
:ref:`Displaced Neutral Difference Free Energy<figure_lig_disp>` 
was generated by selecting *4std_stbl_disp.oeb.gz*
in *VIDA's* list window and running the :ref:`chapter_watercolor`
to setup the contour levels and display styles, then opening the 
*lig_disp:apo:PROTEIN...* item in the list window and displaying
the *neut_diff_apo_free_energy_grid*. You must run :ref:`WaterColor<chapter_watercolor>`
on each new :ref:`chapter_szmap` results file opened in *VIDA*.
See chapter :ref:`chapter_watercolor`
for more detailed instructions.

The figure :ref:`Displaced Neutral Difference Free Energy<figure_lig_disp>`
shows that the ligand displaces regions with both negative (yellow) and positive
(purple) neutral difference free energies. These energies represent a polarity scale:
negative regions favor polar groups while positive regions favor non-polar groups.
Note that the hydroxyl oxygen nicely substitutes for
solvent that acts as an H-bond acceptor. The region in the upper center,
on the other hand, contains solvent interacting with a pair of tyrosine
hydroxyls that is displaced but not replaced with a similar group. This suggests
placing a polar group into this site.

.. _figure_lig_disp_orient:

.. figure:: /_images/4std_lig_disp_orient.png
   :width: 1000
   :align:  center

   **Orientations and Displaced Neutral Difference Free Energy**

The :ref:`chapter_waterorient` will display the most probable water orientations for
each point in the calculation, filtered to show only the dominant points (local minima and maxima).
It makes it easy to determine where waters donate or accept H-bonds and where waters do not
make any significant interactions. Open the control panel by selecting the
*Extensions >> Water Orientation* menu in *VIDA* (it will remain open until you close it).

The figure
:ref:`Orientations and Displaced Neutral Difference Free Energy<figure_lig_disp_orient>`
adds information indicating both the magnitude of the free energies
and the geometry that must be taken into account in positioning a
substituent. To generate the figure, set the ``Apply to:`` popup
in the :ref:`chapter_waterorient`
to ``4std_stbl_disp.oeb.gz/apo(lig_disp)``---the ligand displacement *apo*
results---and press the *Update* button.

.. _figure_cplx_orient:

.. figure:: /_images/4std_cplx_orient.png
   :width: 1000
   :align:  center

   **Complex Neutral Difference Free Energy**

The next stage is to examine the protein-ligand complex grid, illustrated in
:ref:`Complex Neutral Difference Free Energy<figure_cplx_orient>`.
First, undisplay all grids from the *lig_disp:apo:PROTEIN...* entry
in *VIDA's* list window,
along with the *4std_stbl_disp.oeb.gz/apo(lig_disp)* entry from
the previous orientation display. 
Next, open the *complex:PROTEIN...* section of *VIDAs* list window
to reveal the set of grids calculated for the complex.
Select and display the *neut_diff_free_energy_grid*.
Finally, set the :ref:`chapter_waterorient` to applied to ``4std_stbl_disp.oeb.gz/complex``
and press *Update*.
The display shows two regions of negative free energy: a region at the bottom were
solvent interacts with two histidines and the amide NH of the ligand,
and a smaller region at the top, just beyond the displaced region, that
interacts with the previously mentioned tyrosines, along with one region of
positive free energy.

.. _figure_stbl_grid:

.. figure:: /_images/4std_stbl_grid.png
   :width: 1000
   :align:  center

   **Stabilization Neutral Difference Free Energy**

Looking at the 
:ref:`Stabilization Neutral Difference Free Energy<figure_stbl_grid>`
(by undisplaying any other grids or orientations and
then opening the *stabilization:PROTEIN...* item in the *VIDA* list window and
displaying the *neut_diff_stbl_free_energy_grid*),
it is clear that only the lower region is stabilizing the bound ligand,
adding weight to the idea of displacing water in the upper region.


.. _szmap_tutorial_coords:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


==================================
Running SZMAP at Coordinates
==================================

:ref:`chapter_szmap` can be run at arbitrary coordinates,
for example the atom positions in the ligand.
Because this calculation is performed only over the atom coordinates specified in
``-at_coords <mol_file>`` it will run very quickly, around 1 minute for this example.
While not as informative as a full grid calculation, "at coords" calculations
are a rapid way to survey a binding site (about 20 seconds on four 2.8GHz processors).

::

   > szmap -mpi_np 4 -prefix 4std_lig_coords -at_coords 4std_lig.oeb.gz -p 4STD_ABC__DU__BFS_A-173.oedu -excludeDUligand

   or

   > szmap -mpi_np 4 -prefix 4std_lig_coords -at_coords 4std_lig.oeb.gz -p 4STD_A__DU__BFS_A-173_target.oeb.gz

The output for ``-at_coords`` calculations includes a text file containing tab-delimited
tables of results and an *.oeb* file with :ref:`chapter_szmap` results as properties
attached to the atoms used to define the coordinates.

.. warning::

   If the at_coords positions overlap with atoms in the protein or design unit file, the coordinate will be skipped.
   The current clash definition is a near perfect atom overlaps (0.1A)

Analyzing Coordinate Results
-------------------------------

If the calculations were done at specified coordinates (using the ``-at_coords`` parameter)
the results can be visualized with the :ref:`chapter_waterorient`
or the :ref:`chapter_colorprops` (which colors coordinates by calculated values). Open the file
in *VIDA* using the command below or, if *VIDA* is already open, by using the *File >> Open* menu.

::

   > vida 4std_lig_coords.oeb.gz

.. _figure_lig_coords:

.. figure:: /_images/4std_lig_coords.png
   :width: 1000
   :align:  center

   **Apo Neutral Difference Free Energy at Ligand Coordinates**

The figure
:ref:`Apo Neutral Difference Free Energy at Ligand Coordinates<figure_lig_coords>`
shows results similar to the
:ref:`Orientations and Displaced Neutral Difference Free Energy<figure_lig_disp_orient>`.
Calculating at the ligand coordinates is very quick but
produces a coarse sampling and in regions where the gradient is large,
can be somewhat misleading.

To generate this figure, the :ref:`chapter_waterorient` panel was accessed to
``Apply to: 4std_lig_coords.oeb.gz/apo`` and the *Update* button was pressed. Next,
the *apo: at_coords* entry in the list window was selected and
the "H" button in the style panel was used to display all the ligand hydrogens.
With the *apo: at_coords* entry still highlighted in the list window,
the :ref:`chapter_colorprops` was opened and the property *szmap_neut_diff_free_energy*
was selected. Then, if this is the first time the panel has been used, the color tiles
in the center-left were selected one-by-one and changed so that the left one was yellow,
the center one was white, and the right one was purple (the standard *SZMAP* color scheme).
The missing values color tile
was also set to a dark gray color easily distinguished from the others. Finally, the options
"Lock middle color to zero" and "Missing Values" were checked.
The dark gray atoms along outer edges of the ligand are at
positions where a water probe is slightly too large to fit without clashing, but
it is worth noting that this can occasionally be alleviated with a shift of just a fraction
of an |Angstrom|.

Two-dimensional Coordinate Reports
----------------------------------------------------

In addition to the 3D graphics,
you can also produce a printable *.pdf* report of ``-at_coords`` results
with :ref:`chapter_szmap_report`. The molecule is shown in 2D, colored
by their numerical value of the :ref:`chapter_szmap` results.
If multiple ligands were used for the coordinate calculations, :ref:`chapter_szmap_report`
will depict all of them for easy comparison.

::

   > szmap_report 4std_lig_coords.oeb.gz 4std_lig_coords.pdf szmap_neut_diff_free_energy

.. _figure_report_nddG:

.. figure:: /_images/4std_lig_coords_report_nddg.png
   :width: 1000
   :align:  center

   **Neutral Difference Free Energy in 2D**

Figure :ref:`Neutral Difference Free Energy in 2D<figure_report_nddG>`
shows a **SzmapReport** for the neutral difference free energy with a surface representing
how tightly or loosely the ligand fits into the binding site. See chapter
:ref:`chapter_szmap_report` for more information on this surface representation.
In this case, the phenolic ring is held tightly while the methyl group is adjacent
to a cavity. The pocket around the fluorine is so tight that a probe water cannot
fit there, indicated by the gray color of the fluorine atom.

Stabilization at Coordinates
----------------------------------------------------

While calculations at ligand atom coordinates cannot produce stabilization energies,
calculations at coordinates other than the ligand *can*.
They can also be very quick ways to explore properties of the
complex, with the same caveat that they represent a coarse sampling.

In our example, the two
crystallographic waters closest to the ligand are split from the original PDB file
and used to calculate stabilization values at these coordinates.
Although the splitting can also be done with *VIDA* or with a text editor,
here we use the *egrep* command generally available on Linux, Mac OS X or Windows *cygwin*.

::

   > egrep 'HOH A 187' 4std.pdb >  4std_selected_waters.pdb
   > egrep 'HOH A 190' 4std.pdb >> 4std_selected_waters.pdb

   > szmap -prefix 4std_wat_coords -at_coords 4std_selected_waters.pdb \
   >       -mpi_np 4 -stbl -p 4STD_ABC__DU__BFS_A-173.oedu

   or

   > szmap -prefix 4std_wat_coords -at_coords 4std_selected_waters.pdb \
   >       -mpi_np 4 -stbl -p 4STD_A__DU__BFS_A-173_target.oeb.gz

.. tip::

   The line above with a '\\' as the very last character indicates that the command
   was too long to fit on one line and continues on the following line.

Analyzing Coordinate Stabilization Results
------------------------------------------

::

   > vida 4std_wat_coords.oeb.gz

.. _figure_wat_coords:

.. figure:: /_images/4std_wat_coords_orient.png
   :width: 1000
   :align:  center

   **Complex Neutral Difference Free Energy at Water Coordinates**

The :ref:`Complex Neutral Difference Free Energy at Water Coordinates<figure_wat_coords>`
(with orientations and energies from the :ref:`chapter_waterorient`)
shows results similar to the :ref:`Complex Neutral Difference Free Energy<figure_cplx_orient>`
but were produced much more quickly.

.. _figure_wat_coords_stbl:

.. figure:: /_images/4std_wat_coords_stbl_4digits.png
   :width: 1000
   :align:  center

   **Stabilization Neutral Difference Free Energy at Water Coordinates**

In :ref:`Stabilization Neutral Difference Free Energy at Water Coordinates<figure_wat_coords_stbl>`,
the *stabilization: at_coords* waters were highlighted in the list window and colored based on the property
*szmap_neut_diff_stbl_free_energy* using :ref:`chapter_colorprops`. No orientation data is shown
because orientation information is not produced by stabilization calculations,
only complex, ligand, and *apo* calculations.
But using *VIDA's* generic data labeling capabilities, the coordinates
can be labeled by the neutral difference stabilization free energy values.
This is a quick way to visualize energies
from a stabilization grid calculation. Rather than using crystallographic waters in the calculation,
the "at coords" positions can be waters from
a previous grid calculation using the "Split" tool in the :ref:`chapter_waterorient`, or generated
by some other procedure.


.. _szmap_tutorial_gameplan:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


======================
Running Gameplan
======================

The application :ref:`chapter_gameplan` uses :ref:`chapter_szmap` to analyze ways
to modify ligand chemistry based on water structure and energetics in the immediate
environment of the ligand. By testing a limited number of coordinates based on
the structure of the ligand and the binding site, :ref:`chapter_gameplan` quickly
generates: a description of how compatible the ligand is with the binding site,
a series of hypotheses for ligand variants, and stabilizing or destabilizing waters.

Again, assuming the input protein and ligand structures have been prepared as described above,
a :ref:`chapter_gameplan` calculation can be performed as follows:
::

   > gameplan -szmap_mpi_np 4 -prefix 4std_gameplan -p 4STD_ABC__DU__BFS_A-173.oedu

   or

   > gameplan -szmap_mpi_np 4 -prefix 4std_gameplan -p 4STD_A__DU__BFS_A-173_target.oeb.gz -l 4STD_A__DU__BFS_A-173_ligand.oeb.gz

The protein and ligand in the OEDesignUnit are analyzed and the most informative
sample points are identified. :ref:`chapter_szmap` is then run on those points,
and the results are transformed into a set of potential ligand modifications.
All of this takes about 4 minutes on four 2.8GHz processors and
the output is placed in the file "4std_gameplan.oeb.gz", which can be analyzed in *VIDA*
using the :ref:`chapter_watercolor`. The file "4std_gameplan.log" documents the results,
including the energy values for each attachment hypothesis.

The command line option ``-szmap_mpi_np #`` controls how :ref:`chapter_gameplan`
runs :ref:`chapter_szmap` to compute the results. More information on
options can be found in chapter :ref:`chapter_gameplan`.

Analyzing Gameplan Results
-------------------------------

Results from :ref:`chapter_gameplan` contain ideas for ligand modifications and points where water is
stabilizing or destabilizing the protein/ligand complex.

::

   > vida 4std_gameplan.oeb.gz

.. _figure_gameplan_4std_polar_attachment:

.. figure:: /_images/4std_polar_attachment.png
   :width: 1000
   :align:  center

   **Gameplan Hypothesis for a Polar Attachment**

In :ref:`Gameplan Hypothesis for a Polar Attachment<figure_gameplan_4std_polar_attachment>`,
the :ref:`chapter_watercolor` has been used to configure the display of
the :ref:`chapter_gameplan` results by highlighting any part of the gameplan results in the list window
and running :ref:`chapter_watercolor`. Using the up-arrow and down-arrow keys,
you can browse through the different components of the results in the list window. Shown
in pink is a suggestion for a site where a hydrogen-bond acceptor might interact favorably
with nearby tyrosine residues. The yellow ball indicates that water makes a strong polar interaction
at this site in the *apo*-protein. For a complete description,
see chapter :ref:`chapter_gameplan`.


.. _szmap_theory:

*********************************
Theory
*********************************

.. toctree::
   :maxdepth: 2

   szmap_philosophy
   szmap_details



﻿.. include:: ../../apps-substitutions

.. _chapter_szmap_theory_philosophy:

.. index:: Philosophy and Design

========================
Philosophy and Design
========================

We all care about water. It is the one thing we always need to take into account
and it’s also the one thing we have most trouble modeling. A recent historical
review of theories of water lists over thirty different models [Guillot-2002]_,
none of which are comprehensive in their predictive abilities, *i.e.* are able to
reproduce all of water's many properties. However, we really don’t care about the
thermal conductivity or viscosity of water, we just want to know how it interacts
with solutes of interest, typically a drug molecule and a protein. Here,
simple atomistic modeling of water ought to be adequate. And for very simple
molecules, *e.g.* alkanes, mono-functional substituted alkanes, simple aromatics,
all-atom simulations can appear to be capturing interactions between water and
the solute quite well, for instance in predicting the transfer energy from vacuum
to water. However, attempts to predict such energies on more complicated molecules
are much less accurate and, what is worse, appear to be no better than a simplistic
approach such as Poisson-Boltzmann (PB) [Nicholls-2008]_, [Nicholls-2009]_. In PB we
model water not atomistically but as a continuum, as a high dielectric that responds
to the potential produced by the solute. PB cannot account for the van der Waals
interactions between water and the solute other than by some simple area term and
cannot account for discrete water effects, hydrogen-bonding patterns or correlation
between waters. All it can do is to present an effective response, a long-time response
if you will, of a material that macroscopically acts like water in its dielectric
response. Yet PB continues to prove useful and predictive, presumably because the
behavior it does model is the dominant behavior for interaction energetics and
because many of the aspects of water claimed to be important either are not or
cancel each other in some poorly understood manner. An example of this was discovered
early in PB theory, namely that of the results for highly charged ions, where water
structure was presumed to be absolutely necessary for prediction. Closer
study illuminated two effects: electrostriction, causing water density to be
higher near the ion, and dielectric saturation, *i.e.* the field of the ion so
aligns water that it no longer responds linearly to that field. These two effects
act to cancel each other---electrostriction increases the effective dielectric
while saturation decreases it. As a consequence, PB is quite accurate for highly
charged ions.

Despite the fact that all-atom simulations have proven quite poor at predicting the
energies of anything but simple molecules
(*e.g.* RMS error of :math:`\sim \, 2 \, kcal \, mol^{-1}`) they are
routinely applied to the much more complicated task of active site modeling. It is
natural to try such techniques because this is the area of interest for drug discovery
and, to be fair, the solvation of simple amino acids is well understood. It is also
felt that simulations must be more useful than PB for this task because active sites
represent volumes where solvent behavior is, perhaps, much less likely to be like bulk,
*i.e.* how can PB represent the behavior of water that must be more discrete than
continuous? In answer to this, one first has to remember that there is no experimental
proof that all-atom simulations work well in active sites either---other than the
occasional paper claiming to predict binding affinities on a particular system(s) with
particular properties, *i.e.* anecdotal science. However, because simulations allow one
to present images of waters and water behavior it is the more compelling technology.
We are all prone to capture by images. And, to be fair again, the results from simulation
ought to make some qualitative sense, *e.g.* waters in enclosed areas will differ 
from bulk water in their behavior in expected ways. The questions before us are: 
what can PB tell
us in both a faster and simpler way, and can this be captured quantitatively?

To consider these questions, we should first acknowledge the work of Barry Honig and his
group during the early nineties on the hydrophobic effect
[Sharp-1991a]_, [Sharp-1991b]_, [Nicholls-1991]_. Honig is known, of course, for
bringing PB to the field of molecular modeling with the program DelPhi and later, in
a visual sense, with GRASP. Barry once related a story concerning a review of one of
his early grant applications which said that while Honig’s work was clearly competent
on the electrostatics of water the reviewer could not recommend funding because clearly
Honig had never heard of the hydrophobic effect. The printable part of Barry’s
righteous anger over this remark was "one thing at a time," and around 1991
Anthony Nicholls, Kim Sharp and Barry started thinking about hydrophobicity and
how we might account for it by something other than a simple area term,
*e.g.* by multiplying the accessible area, that of the locus of points formed by the
center of a sphere the size of water run over the VDW surface of a molecule. There
were complicated area models for sure, *i.e.* ones where the area belonging to different
atom types were accorded different energies [Eisenberg-1986]_, but these were already
accounting for some of the electrostatic effects that PB included. Instead we
concentrated on non-polar molecules in an attempt to partition out the electrostatics,
the assumption being that the two components, *i.e.* the hydrophobic and the electrostatics,
were relatively orthogonal. The principle puzzle that drove us at this time was the
difference in this area term for small molecules and for the macroscopic. For instance,
for small molecules the transfer energy of an alkane from hydrocarbon to water gave
roughly :math:`32 \, cal \, {Angstrom}^{-2} mol^{-1}` (unfavorable). This comes
from the work of Hermann
[Hermann-1972]_, where the increase in transfer energy from hydrocarbon to water is
:math:`0.88 \, kcal \, mol^{-1}` per methyl group added in going from ethane to decane.
However, the
surface tension at a water/ hydrocarbon interface works out to about
:math:`72 \, cal \, {Angstrom}^{-2} mol^{-1}` (unfavorable). Why was there an
almost three fold difference
in behavior between microscopic and macroscopic areas? We investigated many possibilities,
detailed in our papers from that era, but the most fascinating was the concept of
curvature. There was a formula from Tolman, a giant in the area of statistical mechanics,
for the surface tension of small oil droplets [Tolman-1949]_. This formula showed that
as drops became smaller the surface tension should decrease. This made physical sense in
that water at the boundary to such a highly curved surface would make more interactions
with neighboring waters than when pressed against a flat surface, *i.e.* would be less
perturbed by the hydrocarbon surface. Was there a way in which this formula could
bridge the gap we were looking at between microscopic and macroscopic? 

.. _figure_theory1:

.. figure:: /_images/theory-fig1.png
   :width: 1000
   :align:  center

   **Curvature**

   *The basic curvature model of Nicholls and Honig* [Nicholls-1991]_.

Unfortunately, Tolman’s formula was only a signpost in that it included a parameter that
should be of the order of molecular dimensions but with no clear indications as to what
it should actually be. The seminal insight from our work was to associate this parameter
with the diameter of water. If this association was made then Tolman’s formula actually
described the fractional change of the accessible area of a water molecule at the surface
of the droplet, *i.e.* from :math:`2 \pi` steradians at a flat surface to
:math:`4 \pi` in solution and :math:`0 \pi`
when isolated from other waters (figure :ref:`Curvature<figure_theory1>`).
The neat thing about this translocation of
ideas is that we could calculate a “Tolman”-like correction for any shaped surface, not
just a spherical droplet. All we had to do was to put a sphere the size of water
(radius 1.4 |Angstroms|) up to the surface of a molecule and calculate its loss of
accessible area. If the surface was planar you lost exactly half its accessible area,
if the surface was concave more area was lost and if it was convex less was lost. The
idea was very simple: water likes being in contact with water and its own accessible
area was a measure of how happy (energetically favorable) it was. As described in our
*Science* paper [Sharp-1991b]_, this curvature correction became an integral part in our attempt to
bridge the microscopic/macroscopic gap. What happened next is, perhaps, an illustration
of another gap: that between the simulation world and the continuum world. What was
really needed was someone well versed in the simulation world to test the predictions
of this model---we had proposed a straight linear correspondence between the loss of
area a water might experience and the energy penalty/hydrophobicity at that point
in space. Simulations could have at least tested the form of this concept, for
instance by simulating water around the surface of an uncharged macromolecule. However,
not one simulation group stepped forward because, after all, this is a continuum
theory and was seen as competition, at that time, to the simulation approach
(and for grant money). 

In the end, the majority use of the curvature concept was in graphics; it became
a standard way in GRASP to illuminate the convex and concave parts of a protein
or DNA. In fact, finding large regions of contiguous concavity proved a useful way
to spot areas of functional utility for both. Lost was the concept of this as a
quantitative measure of water's chemical potential. 

Then, in 2006, I revisited the problem from a different angle. I’d heard some
years ago at an ACS meeting that Alex Rashin, a Russian scientist who had worked
with Barry on some of his earliest PB papers, had played around with placing a water,
*i.e.* a molecular representation of water, around a solute and calculating the PB
energy of such a water in an attempt to predict, not the total free energy of hydration,
but the enthalpy and entropy. This seemed very ambitious and I am not sure if Alex
published his results. Barry’s opinion was that perhaps Alex believed a little too
much in PB and was pushing the theory too far. However, by that time I was looking
at our ability to predict the transfer of small molecules from vacuum to water and
it was clear that there were persistent outliers the theory was only just capturing. For
instance, tetrafluoromethane has a very unfavorable transfer energy of
:math:`+3.1 \, kcal \, mol^{-1}`,
yet PB wants to make this molecule almost soluble (predicts around
:math:`0.0 \, kcal \, mol^{-1}`).
Even if you turned off all the charges in this molecule and just assumed it was a waxy
blob you would only get a prediction of about
:math:`+1 \, kcal \, mol^{-1}`. PB just does not have the
facility to correctly predict :math:`+3.1 \, kcal \, mol^{-1}`.
Another example, in the opposite direction,
is bromoform, *i.e.* a methane with three bromines attached. In this case the experimental
result is :math:`-1.98 \, kcal \, mol^{-1}` but PB predicts an unfavorable
:math:`+1 \, kcal \, mol^{-1}` transfer energy (essentially because
there is little polarity in the molecule and it is big and bulky). Now, an all-atom
simulationist would look at this and immediately recognize the problem: *van der Waals*.
Fluorine has very small van der Waals interactions and bromine has large ones---using
a single area term is bound to fail for these molecules. This may well be a part of
the problem, however thinking back to the curvature model I could see another.
Fluorinated compounds are often used by the electronic industry where the goal is to
reduce the cross-talk between circuits; fluorinated materials have a lower dielectric
and hence electrical signals propagate less through them. Similarly, the refractive
index of fluorinated compounds is always lower than that of unfluorinated compounds.
Bromine (and Iodine) force the dielectric in the other direction, both are more
polarizable. Neither observation should be a surprise since VDW interactions themselves
are the result of virtual polarization of electron clouds: fluorine is hard to polarize
and hence has smaller VDW interactions. Could this effect be captured by PB?
Traditionally we think of the solvent as the volume that polarizes in PB, not the
solute, but there is nothing to stop us including a solute dielectric to represent
its polarizability. This will affect the solvation energy and it does so in the
right way, *i.e.* tetrafluoromethane is less soluble in a polarizable model,
bromoform is more soluble. However, it also occurred to me that this will affect
the hydrophobic effect as well. If the root of hydrophobicity is that water would
rather interact with water than hydrocarbon then surely this will depend on how
polarizable that ‘hydrocarbon’ might be. This was the concept I explored before
and presented at CUP 8 in February, 2007 and forms, in many ways, the theoretical
basis for *SZMAP*.

.. _figure_theory2:

.. figure:: /_images/theory-fig2.png
   :width: 1000
   :align:  center

   **CUP8 Model**

   *Basic physical properties of the CUP8 model for dielectric hydrophobicity.*
   **Note:** :ref:`chapter_szmap` currently uses a protein/probe dielectric of 1.0 and the
   probe water dipole is 1.86 Debye.

.. _figure_theory3:

.. figure:: /_images/theory-fig3.png
   :width: 1000
   :align:  center

   **Water Probe**

   *Sampling of contact positions of water against a conformation of a large alkane.*

The basic idea behind what I refer to as a *Dielectric Theory of Hydrophobicity*
is illustrated in figures :ref:`CUP8 Model<figure_theory2>`
and :ref:`Water Probe<figure_theory3>`.
Essentially, one does a lot of PB calculations
where the only charged molecule is a water molecule pressed up against a solute of
interest. The solute 'desolvates' water, *i.e.* produces a small energetic penalty
for water at the surface of a solute. Each such water has many orientations possible
to it, some of which will be more desolvated than others, *e.g.* orientations that
have protons closer to the solute. If you sample enough orientations then the
Boltzmann average of those energies produces a ‘partition function’ for the water
'partitioning' from bulk to the surface of the solute. From the partition function
you can derive any thermodynamic property you like, *e.g.* enthalpy or entropy, with
one caveat. That caveat is that the energies that make up the partition function
are themselves free energies---they are the energies of ‘binding’ a water molecule
to the surface of a solute in a particular orientation. They are free energies
because that is what PB calculates (essentially, the electrostatic energies in PB
are derived from the reorganization of the dielectric, which is a work function,
which therefore produces a free energy). As such, each term in the partition
function is already a free energy and contains a component of enthalpy and entropy
that we cannot separate out. However, we can produce a measure of entropy,
*i.e.* the entropy due to the restriction of orientation of the water (because there
are preferred directions of the water up against the solute). We just have to
remember that this is not the total entropy of binding/hydrophobicity, because
some of that is wrapped up in the PB (free) energy. Similarly, we can calculate
an ‘enthalpy’, which is really the average free energy of binding because it is,
in fact, the Boltzmann average of the free energy of binding. The free energies
are real, the thermodynamic decomposition in *SZMAP* is incomplete.

What was surprising about the exercise described above is what happens if you use
the basic physical properties of water in the model: Bondi radii, dielectrics
derived from refractive indices, charges based on vacuum dipoles and typical
estimates of water density, *i.e.* how many waters are likely to cover a solute
(figure :ref:`CUP8 Model<figure_theory2>`). These basic values for water accurately
reproduce the transfer of energy
from vacuum to water, but surprisingly produce an energetic cost per square |Angstrom|
very close to what is seen experimentally, *e.g.* around
:math:`32 \, cal \, {Angstrom}^{-2} mol^{-1}`.
Furthermore, the flat surfaces of molecules like benzene gave higher than expected
hydrophobicity, unless the higher polarizability of such was also included, in which
case the value fell back into the same range as aliphatic molecules
(figure :ref:`Oil-Water Transfer<figure_theory4>`). For
an unparameterized model the result was surprisingly sensible. Furthermore, from
vacuum-water surface tension you could predict the non-polar term for the vacuum-water
transfer energy term to be right where one would expect,
*i.e.* in the :math:`6 \, to \, 10 \, cal \, {Angstrom}^{-2} mol^{-1}` range,
except that this value would be
dielectric dependent, *i.e.* lower for polarizable molecules and higher
for the unpolarizable. This dependence empirically seems to remove most of
the observed variance from experiment seen in the halide containing molecules
in the Rizzo set [Rizzo-2006]_ we have used for vacuum-water transfer energy
prediction (figures :ref:`AM1BCC<figure_theory5a>` and :ref:`AM1BCC+QM Corrected<figure_theory5b>`).

.. _figure_theory4:

.. figure:: /_images/theory-fig4.png
   :width: 1000
   :align:  center

   **Oil-Water Transfer**

   *The results from the investigation of dielectric hydrophobicity.
   Using only shape, with no regard to the dielectric constant of
   the solute, gives the two peaked curve. Including the solute
   dielectric, which is normally greater than the electronic
   polarization of water (1.76 relative to vacuum),
   shifts the curve to smaller values and also brings flat,
   aromatic molecules into the same distribution as aliphatic molecules.*
   **Note:** :ref:`chapter_szmap` currently uses a protein/probe dielectric of 1.0 and the
   probe water dipole is 1.86 Debye.

.. _figure_theory5a:

.. figure:: /_images/theory-fig5a.png
   :width: 1000
   :align:  center

   **AM1BCC**

   *The subset of molecules from the Rizzo set 
   containing F, Cl, Br or I,
   using AM1BCC charges with Bondi radii.*

.. _figure_theory5b:

.. figure:: /_images/theory-fig5b.png
   :width: 1000
   :align:  center

   **AM1BCC+QM Corrected**

   *The subset of molecules from the Rizzo set 
   containing F, Cl, Br or I,
   using better quality charges
   (correcting the AM1BCC parameter for Iodine, for example)
   and the dielectric version of hydrophobicity outlined here.*

.. _figure_theory6:

.. figure:: /_images/theory-fig6.png
   :width: 1000
   :align:  center

   **Hydrophobicity vs Curvature**

   *Correlation between the net curvature of ~100 small molecules
   from the Rizzo set and the *SZMAP*-type energy function
   (molecules uncharged). Note that curvature here is represented
   as % of area lost, i.e. more area lost means more energy to
   place a water molecule in this position.*

Finally, how did this explicit enumeration of orientations and positions compare
to the very simple Nicholls/Honig curvature model from 1991?
Figure :ref:`Hydrophobicity vs Curvature<figure_theory6>` illustrates
that there was a strong correspondence when both curvature and partition function
were averaged over the entire surface of a subset of small molecules from
the Rizzo set [Rizzo-2006]_. 
More interesting was to look at the point by point comparison of
the free energy approach and curvature. This is shown in
figure :ref:`Curvature vs Hydrophobicity<figure_theory7>`. What this shows
is that there is good correlation between the two models when the curvature is small,
but that when the curvature is large, *i.e.* a water begins to be enclosed by
the solute, this agreement breaks down, *i.e.* it takes more energy to bury a water
than it does to merely make it sit on the surface of a convex solute. The reason
this was good news is that the attempt to bridge the microscopic/macroscopic gap
in 1991 had had to rely on other factors than just curvature because the effect
was just not big enough.  Here the results suggest why, *i.e.* that planar surfaces
are more hydrophobic than the simple curvature model predicts. In fact,
by constructing a planar surface from methyl groups the CUP8 procedure gets
close to the macroscopic value (:math:`62 \, cal \, {Angstrom}^{-2} mol^{-1}`).

.. _figure_theory7:

.. figure:: /_images/theory-fig7.png
   :width: 1000
   :align:  center

   **Curvature vs Hydrophobicity**

   *Correlation over the surface of a single molecule, a cyclic urea.
   Note that in this graph curvature is as traditionally defined,
   i.e. larger means more convex, i.e. less area occluded.
   Note, therefore that in regions of most negative curvature
   the non-polar term from ZAP increases above the trend line.*

All of this leads to *SZMAP* because the next step in this work is to allow the
solute to be charged, *i.e.* to introduce possibly compensating effects for a
surface water due to the electrostatic field produced by the solute. For instance,
the interactions between a water and a charged group will be favorable and will
overcome the desolvation of the water, relative to the rest of the bulk solvent.
And this is essentially what *SZMAP* attempts to estimate, *i.e.* it is the exact
same procedure of estimating the binding energy of water over a set of orientations.
In the initial version of *SZMAP* a discrete set of orientations are used, 
however there are ways
in future versions for this to be made more comprehensive, with little loss in speed.
The other change we introduce is to allow the sampling of water positions that do
not make contact with the solute. The reason to do such was brought home to me
during conversations with Eric Manas of GSK. He pointed out that the model should
suggest water would begin to lose contact with other water before it actually
touched the surface. In fact, based on close packing arguments the distance
two surfaces would have to come before there was an effective surface-surface
force due to dewetting would be :math:`Diameter_{water} + \sqrt{3 \, Diameter_{water}}`,
*i.e.* about 6 |Angstroms|---close to that seen by simulations by the Berne group
at Columbia [Huang-2003]_. As such, *SZMAP* calculates a volume function, not a
surface function such as the curvature function in GRASP. Of course, this may
also mean that the concordance between experimental alkane-water hydrophobic
energies and the CUP8 work was partly fortuitous, *i.e.* there would more formally
be energetic contributions from positions further way from the surface. 

The remaining difference in *SZMAP* is that we decided to take on the VDW interaction
of water to the solute, namely by adding the VDW energy for each orientation of the
water to the solute. We felt this was important for a couple of reasons. For one
thing we know it will move the desolvation energy in the correct direction for
polarizable atoms. We also can prevent anomalous interactions, *e.g.* close contacts
between protons and charged groups that would be compensated for by VDW repulsion.
Finally, in PBSA theory we have the choice of either using a buried area term
(typically :math:`25 \, cal \, {Angstrom}^{-2} mol^{-1}`)
or explicitly calculating the VDW interactions
and using a much smaller area term
(for instance :math:`6 \, cal \, {Angstrom}^{-2} mol^{-1}` when using
AM1BCC charges). As we are aiming at some verisimilitude with reality it seems
a straightforward choice to explicitly include VDW. As a consequence, there should
be a small residual area term that depends on
the buried accessible area of the water. 

A few words on how points are chosen. We use the shape scoring function in *FRED*
to provide positions of water that are making some contact with the protein, removing
points that VDW would clearly disallow [McGann-2003]_. This provides a regular lattice
of points on which the oxygen of water is positioned. The orientations are calculated
for the protons about this center. One of the advantages of using PB technology for
this process is that for each water orientation we get a potential field throughout
the protein. This field can be used to calculate interactions with many different
protein charge states. We have not implemented this at present,
but it will be a feature in future versions of *SZMAP*. 

At present the output from *SZMAP* consists of the thermodynamic quantities calculated
at each grid point, *i.e.* the rotationally averaged free energy of a water in each
position. The breakdown that we can do into entropic and enthalpic contributions
is included, as are the classic curvature values. From our previous work we
anticipate these volume functions will yield interesting and quantitative
numbers, for instance the energy of displacing water, whether relative or
absolute, and the prediction of ‘condensed’ water, *i.e.* what are typically,
but incorrectly, referred to as crystallographic waters. Most such labeled
waters are figments of crystallographer’s desires to reduce their R factor,
but some are real, *i.e.* some waters are undoubtedly bound substrates to
the protein. It may also be possible to build chains of water from
the preferred orientations and positions of single waters, although
the thermodynamics and physics of this process are more dubious.
We can also include more polarization physics, for instance by implementing
the *EPIC* model of Jean-Francois Truchon [Truchon-2009]_. At this point *SZMAP*
is a tool, *an engine for discovery.*

Anthony Nicholls, Santa Fe, 2010.


﻿.. include:: ../../apps-substitutions

.. index:: Technical Details

.. _chapter_szmap_theory_details:

=========================
Technical Details
=========================

Energy Calculations
--------------------------------------------------------------------------------

Energy values are calculated at each grid point as follows. The energy for each
probe water orientation *j* is the sum of the *ZAP*  protein:water Coulombic
interaction energy, the protein and water desolvation penalties and the van der Waals
energy. For speed, the protein desolvation term is not computed for each orientation,
but is instead computed once per grid point
using a spherical united-atom representation of the probe water.

.. math::

   E_j = ZAP_{int}(P:W) + P_{desolv}^* + W_{desolv} + VDW \,\,\, \{ j = 1 \cdots N_{orient} \}

The partition function *Q* is the usual sum:

.. math::

   \displaystyle Q = \sum_{j=1}^{N_{orient}} e^{-\frac{E_j}{kT}}

The probability of each orientation is then:

.. math::

   \displaystyle prob_j = \frac{e^{-\frac{E_j}{kT}}}{Q}

The probe water orientation entropy difference from continuum water is:

.. math::

   \displaystyle T \Delta S = ( -kT \sum_{j=1}^{N_{orient}} prob_j \ln prob_j ) - kT \ln N_{orient}

Likewise, the probe water free energy difference from continuum water is:

.. math::

   \Delta G = - ( kT \ln Q - kT \ln N_{orient})

And of course, the enthalpy difference is the sum:

.. math::

   \Delta H = \Delta G + T \Delta S

The variance in estimated energies varies with the
number of random probe orientations sampled.
See figure :ref:`Variation in Energy Estimates<figure_error8>`.
At 50 random orientations per point,
half of repeated free energy estimates
are within about :math:`0.2 \, kcal \, mol^{-1}`
of one another. This gives us a way to examine the 
balance between precision and calculation speed. 
Symmetrical probe orientations, the default in :ref:`chapter_szmap`, are
completely reproducible and sample positions evenly. Sixty 
symmetrical orientations produce reliable energy estimates, 
but when more precision is required, 360 symmetrical 
orientations are recommended.

.. _figure_error8:

.. figure:: /_images/dGvariation.png
   :width: 1000
   :align:  center

   **Variation in Energy Estimates**

   *Box plots for repeated calculations of free energy
   at a single point using random orientations. The mode is indicated with a 
   heavy line, rectangles enclose 50%
   of data points and the whiskers enclose 90%.*

The probe water *order* parameter represents the fractional loss of entropy due to
electrostatics:

.. math::

   \displaystyle order = 1 - \frac { - \sum_{j=1}^{N_{orient}} prob^*_j \ln prob^*_j } { \ln N_{orient} }

where :math:`prob^*_j` is the probability for orientation *j* based on
the electrostatic energy terms only, without the van der Waals term.
Order calculated in this way is highly correlated with the neutral difference entropy.

Water Geometry, Radii, and Charges
--------------------------------------------------------------------------------

PB calculations require you to know three things for each atom: the position,
the charges and 
the radii. What should we use for water?
The geometry for the probe water in :ref:`chapter_szmap` is the same as for *"TIP"* water:
:math:`r(OH) = 0.9572` |A| and :math:`HOH \, angle = 104.52^{\circ}`.
Work for SAMPL meetings has shown
that Bondi radii are a good starting point for PB calculations, although
some atoms tend to need slight adjustments, for instance carbonyl oxygens
always seem to want to be slightly bigger, nitrogens smaller. Water is an
odd case as no other oxygen behaves chemically in the same way. So by the principle
of maximum indifference we just use Bondi radii (H: 1.20 |A| and O: 1.52 |A|).

What charges should we use?
Most force-field charges give water a dipole of between 2.4 and 3.0 Debye.
This might seem odd because the actual, vacuum dipole of water is 1.86D.
The force field community justify this because water is polarized in solution
with estimates of its polarized dipole in the range of that used in force-fields.
It is typical of this community---charges are over polarized to attempt to
account for the lack of polarization in their models. AM1BCC, for instance,
gives water a dipole of 2.24D, about 20% too large. This has consequences
for the vacuum-water transfer energy---PB predicts an electrostatic component
of transfer for AM1BCC charges and Bondi radii of :math:`-9.95 \, kcal \, mol^{-1}`.
Add to that a typical "hydrophobic" term (yes, for water!) of about
:math:`+0.65 \, kcal \, mol^{-1}`
(surface area of :math:`107 \, {Angstrom}^2`;
:math:`6 \, cal \, {Angstrom}^{-2} mol^{-1}`) this gives us
:math:`-9.3 \, kcal \, mol^{-1}` prediction
for vacuum-water. The only problem is that the experimental value is about
:math:`-6.3 \, kcal \, mol^{-1}`. This is a huge % error for a simple model and would be very
bad news for *SZMAP* since we want to estimate the energy of a water molecule
burying itself into an active site. What happens if instead we use charges
that reproduce the vacuum dipole? The electrostatic component
becomes :math:`-6.9 \, kcal \, mol^{-1}`. Adding the ubiquitous surface term we
get :math:`-6.25 \, kcal \, mol^{-1}`, *i.e.* just right. But what about polarization?
Well, we are using protein charges that are also derived from vacuum potentials
so in some ways this is not an inconsistent description. Overall, at this stage
we feel it is more important to correctly calculate the desolvation of water.
Therefore *SZMAP* uses point charges for hydrogen and oxygen of +0.327 and -0.654, respectively.

The next stage may be to use a simple polarization model presented at CUP7 that
involved a real molecular dielectric (*i.e.* :math:`\epsilon = 2`) and an increased radius for
each atom. In this model water would have charges with a dipole of 2.48D in
line with experimental estimates. Preliminary results from this model suggest
that for many situations the binding energies of molecules is not dissimilar
from unpolarized models. A further step will be to use the *EPIC* model
developed by Jean-Francois Truchon at Merck-Frosst [Truchon-2009]_.

Uncharged Water, Difference Energies, Bubbles, and Stabilization
--------------------------------------------------------------------------------

The values :ref:`chapter_szmap` calculates for :math:`\Delta G`, :math:`\Delta H` and :math:`T \Delta S`
represent differences between the explicit probe water and the continuum water. In
other words, a positive :math:`\Delta G` indicates that the continuum model over-estimates
the cost of displacing water at that position. When trying to decide which modifications
are most likely to increase binding affinity, we would prefer to compare
the water probe to the ligand atom that displaces it, or at least a proxy for the ligand atom.
In :ref:`chapter_szmap`, this proxy is the water probe without any of the energy terms that involve a charge
on the water (leaving only :math:`P_{desolv} + VDW`). Because these energy terms have
already been determined, calculating the properties for this "uncharged" or "neutral" water requires
no additional time, it's free. The difference in free energy between standard and uncharged
water is negative where standard water is more favored and positive where the uncharged water,
our hydrophobic group proxy, is more favored.

:ref:`chapter_szmap` can also calculate the difference between our probe and a vacuum bubble of the
same size (defined as just the :math:`P_{desolv}` term). Because protein desolvation
is treated as constant over all probe orientations only the vacuum free energy and 
enthalpy differences are calculated, not the entropy differences.

Grids are *masked* such that regions where the sum of the van der Waals
and interaction energies is greater than a cutoff (by default
:math:`0 \, kcal \, mol^{-1}`) are set to zero. This is done
so that grids are displayed only in regions where solvent atoms can physically fit.

As to how to interpret these difference grids,
it should be beneficial for a hydrophobic ligand atom to overlap a region where the
neutral free energy difference is positive because this involves displacing water that is less
favorable than the neutral probe. Overlapping a region where the neutral free energy
difference is negative, on the other hand, requires the overlapping
group to be at least as polar as water and making a similar level of interactions.

Finally, :ref:`chapter_szmap` can calculate *stabilization* energies from the neutral difference values as
a reaction energy

.. math::

   (holo\mbox{-}complex + bulk\mbox{-}solvent) - (apo\mbox{-}pocket + free\mbox{-}ligand)

where *bulk-solvent* is defined as :math:`0 \, kcal \, mol^{-1}`.

Negative free energy values indicate
water is stabilized at that location in the complex, over and above the same location in the ligand
and the *apo* pocket. Positive values are found where the water is destabilized in the complex.
The stabilization or destabilization says nothing about the actual level of stability, so these
energies need to be compared to others such as the *apo* or complex neutral difference free energy.


.. _szmap_releasenotes:

Release History
===============

.. toctree::

   version1_7_4
   version1_7_3
   version1_7_2
   version1_7_1
   version1_7_0
   version1_6_7
   version1_6_6
   version1_6_5
   version1_6_4
   version1_6_3
   version1_6_2
   version1_6_1
   version1_6_0
   version1_5_0
   version1_4_1
   version1_4_0
   version1_3_0
   version1_2_1
   version1_2_0
   version1_1_1
   version1_1_0
   version1_0_0


#################
SZMAP 1.7.3
#################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************



Szmap TK 1.7.3
================================================================================

Minor internal improvements have been made.



##################
SZMAP 1.7.2
##################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************


Szmap TK 1.7.2
================================================================================

Minor internal improvements have been made.



SZMAP 1.7.1
================================================================================

Minor internal improvements have been made.



Szmap TK 1.7.1
================================================================================

Minor internal improvements have been made.



SZMAP 1.7.0
================================================================================

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

* The application now properly validates output file formats.



Szmap TK 1.7.0
================================================================================

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

* Examples have been updated to use design units as inputs.




=============
SZMAP 1.6.7
=============


Szmap TK 1.6.7
================================================================================

Minor internal improvements have been made.




=============
SZMAP 1.6.6
=============

Minor internal improvements have been made.



Szmap TK 1.6.6
================================================================================

Minor internal improvements have been made.



=============
SZMAP 1.6.5
=============

*Fall 2022*

Minor internal improvements have been made.

==================
Szmap TK 1.6.5
==================

Minor internal improvements have been made.




SZMAP 1.6.4
================================================================================

*Spring 2022*

* Minor internal improvements have been made.
  



Szmap TK 1.6.4
================================================================================

* Minor internal improvements have been made.



SZMAP 1.6.3
================================================================================

*Fall 2021*

* Minor internal improvements have been made.
  


Szmap TK 1.6.3
================================================================================

*Fall 2021*

* Minor internal improvements have been made.





SZMAP 1.6.2
================================================================================

*July 2021*

* ``Spruce4Szmap`` has been removed. We recommend using :ref:`SPRUCE <chapter_spruce>` instead.


Szmap TK 1.6.2
================================================================================

*July 2021*

Minor internal improvements have been made.



SZMAP 1.6.1.0
================================================================================

*Fall 2020*

* Minor internal improvements have been made.


Szmap TK 1.6.1
================================================================================

*Fall 2020*

* Minor internal improvements have been made.




SZMAP 1.6.0
================================================================================

*Spring 2020*

* This version of **SZMAP** has been built using **OEToolkits 2020.0**.

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

* Using an :ref:`OEDesignUnit <OEBio_OEDesignUnit>` as an input for stabilizing calculations
  now properly performs all 3 calculation stages.

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

* **SzmapReport** warning messages have been cleaned up.


.. _szmap_releasenotes_100:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


SZMAP 1.0.0
======================================================

*June 2011*

First product release of *SZMAP* application, utilities and *VIDA* extensions.

Features
------------

* Calculates solvent energies on a grid and at user specified coordinates.

* Includes VIDA extensions to facilitate visualization of *szmap* results.

* Includes a Grapheme-based report writer that projects *SZMAP* values onto 2D images.

* Includes a tool to integrate grids to quantify *SZMAP* results.

* Includes a tool to add partial charges and radii to protein and ligand atoms preparation for running *szmap*.

* Includes tools to facilitate using *reduce* to add and optimize protons required for running *szmap*.

* Includes a tool to convert output grids to different formats and perform various mathematical operations on grids.


.. _szmap_releasenotes_110:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


SZMAP 1.1.0
======================================================

*August 2012*

Major update to *SZMAP* applications, utilities and *VIDA* extensions.

Improvements
------------

* The *Water Orientation* VIDA extension has been completely rewritten to be more capable and easier to use.
  *szmap* now generates orientation information tagged with the neutral difference free energy rather than
  the neutral difference enthalpy. The *Water Orientation* VIDA extension will recognize this difference between newer
  and older *szmap* results.

* A new command-line program, *gameplan*, identifies interesting coordinates near a ligand or in a protein binding site,
  runs *szmap* and analyzes the results, producing hypotheses of various ways the ligand might be improved based on the solvent
  environment.

* *szmap* can now use *apo* grids and coordinate output from previous runs with the ``-use_apo_from <results.oeb.gz>`` command line option.
  Combined with the new option ``-split_lig``, a series of ligands all bound to the same protein can be easily analyzed with *szmap*.

* The default grid contour levels used in the *Watercolor* VIDA extension for most difference grids have been changed from -0.5/+0.5 kcal/mol
  to -1.5/+0.75 kcal/mol to emphasize regions with the largest energy differences. VDW grids are now contoured at -2.0 kcal/mol to emphasize
  good contacts.Colors are now generated taking into account whether the background is dark or light.

* By default, *szmap* grid calculations will now output van der Waals values and the degree to which the probe is ordered,
  but not the probe burial fraction. Use ``-results_set max`` to get the probe burial. At_coords calculations now produce max results
  by default in order to enable analysis and categorization of points.

* It is now a fatal error in *szmap* and *gameplan* for hydrogens to be missing from the ligand
  or from more than 10 percent protein heavy atoms. The option ``-warn_if_missing_hydrogens`` will cause a warning to be generated, but
  the calculation will proceed despite the missing atoms. Proteins may have missing atoms far from the active site due to mobile side-chains
  or loops without affecting the results significantly. Missing hydrogens on the ligand are more problematic. But the option to override
  the fatal error is provided so that special cases, where there is ambiguity about whether a hydrogen is missing or not, can be handled.

* By default, *szmap* now performs ligand calculations just in the regions available in the complex, speeding up -stabilization runs.
  A new option ``-restrict_calc <level>`` controls this behavior.

* The set of symmetrical probe orientations available to *szmap* users has been expanded to include sets with 216 and 648 orientations.
  Setting the number of orientations higher than a symmetrical set size but less than the next higher set, will take the symmetrical
  orientations and pad out the remainder with random orientations.

* *szmap* now clearly identifies different output categories in the results file: complex, ligand, apo, stabilization. It also now puts the
  molecule plus data package previously known as 'probe-orientation-data' under each of these sections, renaming it 'probe'.

* The *szmap* log information printed when -verbose and -details are specified has been modified to make it easier to parse and
  to include more information.

* *grid_comp* now supports five new operations:
  *lig_disp* and *prot_disp* append grids and orientation data for regions displaced in the complex by the ligand and the protein, respectively.
  *largest* returns a grid containing only the largest connected region of the source grid based on contours at a user specified level.
  *not_mask* returns data in regions that are *not* in the mask.
  *offset* adds a constant to each grid point.
  In addition, *grid_comp* now does a better job of describing the operations it performs.

* *pch* now produces output even if ``-ligand_res <RES>`` was specified but the given residue name was not located in the input molecule.
  It also now supports the options ``-ligand_resnum <num>``, ``-ligand_inscode <char>``, ``-ligand_chain <char>``, and ``-ligand_model <num>``
  allowing you to more specifically identify which residue is to be written to the ligand file. 

* *pch* now supports the ``-fix_elements`` option which instructs the program to attempt to substitute elements that will work in *szmap*
  (such as Zn) for those where MMFF vdw parameters are not defined (such as Hg).

* *pch* now supports the ``-nonsymmetrized_charges`` option to generate AM1BCC partial charges where topologically equivalent
  atoms---think methyl protons---are not required to have the same charge.
  The default charge-symmetrized AM1BCC charges are recommended for any workflows down the road where the ligand conformation is subject to change.

* *pch* now writes out waters in the input if the ``-output_waters <filename>`` option is specified.

* *szmap_report* now supports the option ``-tag_set <set>`` to provide more control over the output when no tags are specified. The tag set ``v1``
  provides backward compatibility with szmap 1.0 output.

* *szmap_report* now supports the option ``-keep_hydrogens`` to force the rendering of all explicit hydrogens.

* Version, release, platform, etc. information for *szmap* and related programs is now written to the display only when the -verbose flag is used
  or when the command is run without arguments. The status of your *SZMAP* license is now included along with the other information.

* On *Windows*, the installer now adds the OpenEye bin directory to the environment path to better support the use of alternative command shells.

Bug Fixes
------------

* *SZMAP* vida_extensions and tutorial_files are now installed inside a version-specific sub-directory: openeye/examples/szmap/{szmap-version}/.

* A bug that caused *pch* to treat reduced cysteine residues (CYS) to be charged as if they were oxidized (CYX) has been fixed.
  De-protonated cysteines (CYM) were not affected.

* A bug that prevented *pch* from adding Amber charges to the C-term capping residue NME.

* The *Watercolor* VIDA extension has been modified so that it can be run multiple times successfully on a given set of *szmap* output.

* The length of the OH bond in *szmap* probe waters has been reduced by 0.001A so that the water probe geometry is identical to that of TIP models.

* *szmap* can now save molecules with the -charged_mol flag to *.oeb* and *.oeb.gz* files.

* A bug that prevented CLASH tags from showing up in *szmap* stabilization results for -at_coords calculations has been fixed.

* The minimum number of orientations in *szmap* is now 2. The previous version allowed 1 orientation but the calculations would fail.
  Note that runs with less than the default of 60 orientations are likely to give poor energies.

* Fixed a minor bug in the calculation of probe fractional buried surface area in *szmap*.

* *szmap_grid* generates a more complete report describing *SZMAP* data in the input.

* *szmap_report* provides clearer error messages when it does not find *SZMAP* data in the input and the -verbose flag now works properly.
  It also renders text at a larger, easier to read size.

* The manual has been updated to fix a large number of typographic errors and oversights.


.. _szmap_releasenotes_111:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


SZMAP 1.1.1
======================================================

*January 2013*

Bug fix to *SZMAP* applications, utilities and *VIDA* extensions.

Improvements
------------

* The *Water Orientation* VIDA extension now identifies ligand or protein
  displacement entries by appending `(lig_disp)` or `(prot_disp)` to the name
  in the selection pop-up.

Bug Fixes
------------

* A rare bug in how *szmap* decides which grid points will be analyzed has
  been fixed. This bug only affected *apo* pocket calculations where part
  of the ligand used to define the pocket extends away from the protein
  more than ~5 Å in the negative *x, y,* or *z* direction, causing some regions
  that should have been analyzed to be skipped, and other regions that should
  have been skipped to be analyzed.

* The metadata added to *szmap* output now includes the correct version number.

* The position of points tested for stabilization by *gameplan* no longer
  differ slightly between architectures.

* Running *gameplan* from a directory containing the word "gameplan" works properly now.

* The *grid_comp* utility now produces the appropriate subset of probe orientations
  when the operations `lig_disp` or `prot_disp` are used.

* The *Watercolor* VIDA extension no longer changes the modification hypothesis
  molecule to wireframe when the user has highlighted a hypothesis in the list window
  before running the extension.


.. _szmap_releasenotes_120:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


SZMAP 1.2.0
======================================================

*July 2013*

Update to *SZMAP* applications.

Improvements
-------------

* *Multiprocessor Support* : Calculations can be performed much faster with 
  :ref:`chapter_szmap` and :ref:`chapter_gameplan` by using multiple processor 
  on a single machine and on different machines with the same operating system
  installed.  Because of this and other improvements to the software,
  numerical results will differ slightly from those produced by previous versions
  and the set of points that are determined to be clashing may vary slightly.
  :ref:`chapter_szmap` is highly parallelizable---big calculations scale
  very well when run on large numbers of processors.

  .. note: Windows multiprocessing support is limited to a single machine.
           

* :ref:`chapter_szmap_grid` will now split out all :ref:`chapter_szmap`
  grids into separate files in one step when the options ``-output_all_format``
  and ``-prefix`` are used.

* :ref:`chapter_szmap_report` now supports a ``-resolution`` option to control
  the quality of the property maps.

* :ref:`chapter_gameplan` now indicates the stabilization magnitude in the log.

* To streamline the :ref:`chapter_szmap` program, the following obscure
  command line options have been eliminated: ``-only_protein``, ``skip_modified``,
  ``-protein_charge``, ``-protein_hydrogen``,
  ``-ligand_charge``, ``-ligand_hydrogen``,
  ``-charged_mol``, ``-no_probe_data``,
  ``-require_explicit``, ``-add_neutral``,
  ``-add_vacuum``, ``-details``. There are more direct
  ways to perform each of the functions that they
  controlled. The simple help for options in each of the *SZMAP* applications
  and utilities has been streamlined. 

* The :ref:`chapter_watercolor` has been updated so that it
  no longer changes the scale of
  :ref:`chapter_gameplan` results in VIDA.

* The *Quick Start* chapter is now called the :ref:`szmap_tutorial_intro` and
  has been reorganized to improve clarity.

Bug Fixes
-------------

* When running from a directory with a space character
  somewhere in the path name,
  :ref:`chapter_gameplan` is now able
  to find the corresponding version of :ref:`chapter_szmap`.

* The naming scheme for temporary files created by
  :ref:`chapter_gameplan` has been changed to avoid a bug that interfered
  with reading :ref:`chapter_szmap` output under certain circumstances.

* The *Coulombic interaction+van der Waals* (intvdw) value produced
  by :ref:`chapter_szmap` is now the minimum of the values
  for each of the different orientations,
  the same value used to determine clashes.

* Single grid :ref:`chapter_szmap` calculations (for example using ``-apo_grids``)
  no longer output all grid types by default.

* To improve consistency, clashes in stabilization results
  are now marked by the text "CLASH" in the atom property
  *szmap_stbl_clash* instead of *szmap_clash*.

* The options section in the :ref:`chapter_szmap` chapter has been modified to
  document additional file formats supported for some operations.

* The minimum legal setting for the :ref:`chapter_szmap` options ``-inner_dielectric``
  and ``-outer_dielectric`` has been increased to 1.0.
  Lower values can lead to problems with ZAP calculations.

* The maximum legal setting for the :ref:`chapter_szmap` option ``-zap_spacing``
  has been lowered to 1.0. Higher values can lead to problems with ZAP calculations.

Other changes
-------------

* This will be the last release to support SuSe 10.

* The :ref:`chapter_szmap` options ``-point_grid``, ``-lig_point_grid``, and
  ``apo_point_grid`` can no longer be used to setup the calculation without
  doing any actual calculations. This will be fixed in a future release.



.. _szmap_releasenotes_121:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


SZMAP 1.2.1
======================================================

*February 2015*

Update to *SZMAP* applications.

Improvements
-------------

* The :ref:`chapter_waterorient` now saves
  orientation probability data and ensemble energy, vdw
  and order data on probe molecules as SDData. When
  probes generated by this extension are written to an
  ``.sdf`` file, these values will be written as well.

Bug Fixes
-------------

* The :ref:`chapter_waterorient` (version ``1.1.2``)
  now displays the correct water orientations for results
  from :ref:`chapter_szmap` version 1.2.0.

* :ref:`chapter_gameplan` no longer crashes when all
  stabilization test sites clash.

* :ref:`The pch applicatoin <chapter_pch>` no longer treats CYS residues
  bonded through the sidechain to a non-CYS as
  anionic.

* :ref:`The pch applicatoin <chapter_pch>` no longer duplicates nonstandard
  groups containing a metal (such as cofactors)
  and groups they are bonded to.

* The hydrogen charge on the standard water probe
  is now correctly listed as +0.327 not +0.237
  in :ref:`szmap_theory`.



.. _szmap_releasenotes_130:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


SZMAP 1.3.0
======================================================

*August 2015*

Update to *SZMAP* applications.

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

* A new :ref:`mkhetdict <chapter_mkhetdict>` option ``-no_pka_adjustment``
  can be used to prevent deleting or renaming ligand hydrogens
  which cause *reduce* to generate too many hydrogens.

Bug Fixes
-------------

* Grids written out in ``.ccp4`` format now contain
  scaling information to make them comparable to
  other grid formats.

* :ref:`mkhetdict <chapter_mkhetdict>` verbose output now shows
  the correct input file name.

Other changes
-------------

* Now checking for legal ranges on :ref:`chapter_szmap`
  options: ``-bounding_box -mask_cutoff -vdw_scale``



SZMAP 1.4.0
================================================================================

*November 2018*

* This version of **SZMAP** has been built using **OEToolkits 2018.Oct**. The previous 
  version was built using **OEToolkits 2013.Oct**.

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

* An issue related to running **GamePlan** in ``MPI`` mode has been fixed.

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

* Finding the location of the **SZMAP** application in **GamePlan** is no longer 
  platform-dependent. 



SZMAP 1.4.1
================================================================================

*May 2019*

* This version of **SZMAP** has been built using **OEToolkits 2019.Apr**. The previous
  version was built using **OEToolkits 2018.Oct**.

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

* Output ligand box are now properly written in a ``.mol`` or ``.sdf`` file.


SZMAP 1.5.0
================================================================================

*Nov 2019*

* This version of **SZMAP** has been built using **OEToolkits 2019.Oct**. The previous
  version was built using **OEToolkits 2019.Apr**.

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

..  _chapter_pch:

..  _chapter_mkhetdict:

* A New utility application, **Spruce4Szmap**, has been added to
  properly prepare a structure for use in **SZMAP** or **GamePlan**.
  **Spruce4Szmap** replaces the three previous utility applications,
  ``Pch``, ``MKHetDict`` and ``FixDupAtomNames``.  With **Spruce4Szmap**, using external program ``reduce``
  as part of structure preparation workflow is no longer necessary.

* The ``-protein`` parameter for both **SZMAP** or **GamePlan** now accepts an ``OEDU``
  files, representing design units generated from **SPRUCE**.

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

* **SZMAP** now generates an output box file if ``-lig_box`` or ``-apo_box`` is set.
  In addition, it performs the same calculations regardless of whether a box (Std, Apo or Lig)
  is output or not.

* **SZMAP** now gives a fatal error if no ligand is specified and ``-stbl`` is set to ``true``.

* **SZMAP** now exits cleanly when an empty ligand or protein file is used as input in MPI mode.

* **SZMAP** now attaches `szmap-meta-data` to protein in an `at_coords` calculation.

* **SZMAP** now only performs `apo grid calc` when ``-apo_grids`` is set to ``true``.

* **SzmapReport**  no longer generates repeated images of stable waters.



SZMAP Appendix

.. toctree::
   :maxdepth: 2
   
   appendix_szmap_grids
   appendix_atom_props



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. index:: Appendix 1

.. _chapter_appendix1:

=============================
Appendix 1: SZMAP Grids
=============================

Here is a list of all the grids that can be produced by :ref:`chapter_szmap`. By default, only
a subset of these are written to the results file. The default output grids are
in **bold**. *Bump* means the point failed a quick bump-check and *clash* means
the intvdw > cutoff.

Protein + Ligand Complex
-------------------------------------------------------------------------------

   ================================== ============================================
   Grid Name (prot + lig complex)     Description                                 
   ================================== ============================================
   **neut_diff_free_energy_grid**     water - neutral probe free energy difference
   ---------------------------------- --------------------------------------------
   neut_diff_enthalpy_grid            water - neutral probe enthalpy difference   
   ---------------------------------- --------------------------------------------
   neut_diff_entropy_grid             water - neutral probe entropy difference    
   ---------------------------------- --------------------------------------------
   **vdw_grid**                       van der Waals energy                        
   ---------------------------------- --------------------------------------------
   **order_grid**                     fractional entropy loss from electrostatics 
   ---------------------------------- --------------------------------------------
   **mask_grid**                      clash: 0, bulk solvent: 0.98, no clash: 1.01
   ---------------------------------- --------------------------------------------
   point_grid                         bump: 0, bulk solvent: 0.98, calc: 1.01     
   ---------------------------------- --------------------------------------------
   vac_diff_free_energy_grid          water - vacuum probe free energy difference 
   ---------------------------------- --------------------------------------------
   vac_diff_enthalpy_grid             water - vacuum probe enthalpy difference    
   ---------------------------------- --------------------------------------------
   free_energy_grid                   free energy of probe water vs continuum     
   ---------------------------------- --------------------------------------------
   enthalpy_grid                      enthalpy of probe water vs continuum        
   ---------------------------------- --------------------------------------------
   entropy_grid                       entropy of probe water vs continuum         
   ---------------------------------- --------------------------------------------
   neutral_free_energy_grid           free energy of neutral probe vs continuum   
   ---------------------------------- --------------------------------------------
   neutral_enthalpy_grid              enthalpy of neutral probe vs continuum      
   ---------------------------------- --------------------------------------------
   neutral_entropy_grid               entropy of neutral probe vs continuum       
   ---------------------------------- --------------------------------------------
   interaction_grid                   Poisson Boltzmann electrostatic interaction 
   ---------------------------------- --------------------------------------------
   psolv_grid                         protein desolvation penalty                 
   ---------------------------------- --------------------------------------------
   wsolv_grid                         water probe desolvation penalty             
   ---------------------------------- --------------------------------------------
   intvdw_grid                        interaction + van der Waals *(for masking)* 
   ---------------------------------- --------------------------------------------
   probe_burial_grid                  fractional amount water probe is buried     
   ================================== ============================================

Ligand Only
-------------------------------------------------------------------------------

   ================================== ============================================
   Grid Name (ligand only)            Description                                 
   ================================== ============================================
   **neut_diff_lig_free_energy_grid** water - neutral probe free energy difference
   ---------------------------------- --------------------------------------------
   neut_diff_lig_enthalpy_grid        water - neutral probe enthalpy difference   
   ---------------------------------- --------------------------------------------
   neut_diff_lig_entropy_grid         water - neutral probe entropy difference    
   ---------------------------------- --------------------------------------------
   **lig_vdw_grid**                   van der Waals energy                        
   ---------------------------------- --------------------------------------------
   **lig_order_grid**                 fractional entropy loss from electrostatics 
   ---------------------------------- --------------------------------------------
   **lig_mask_grid**                  clash: 0, bulk solvent: 0.98, no clash: 1.01
   ---------------------------------- --------------------------------------------
   lig_point_grid                     bump: 0, bulk solvent: 0.98, calc: 1.01     
   ---------------------------------- --------------------------------------------
   vac_diff_lig_free_energy_grid      water - vacuum probe free energy difference 
   ---------------------------------- --------------------------------------------
   vac_diff_lig_enthalpy_grid         water - vacuum probe enthalpy difference    
   ---------------------------------- --------------------------------------------
   lig_free_energy_grid               free energy of probe water vs continuum     
   ---------------------------------- --------------------------------------------
   lig_enthalpy_grid                  enthalpy of probe water vs continuum        
   ---------------------------------- --------------------------------------------
   lig_entropy_grid                   entropy of probe water vs continuum         
   ---------------------------------- --------------------------------------------
   neutral_lig_free_energy_grid       free energy of neutral probe vs continuum   
   ---------------------------------- --------------------------------------------
   neutral_lig_enthalpy_grid          enthalpy of neutral probe vs continuum      
   ---------------------------------- --------------------------------------------
   neutral_lig_entropy_grid           entropy of neutral probe vs continuum       
   ---------------------------------- --------------------------------------------
   lig_interaction_grid               Poisson Boltzmann electrostatic interaction 
   ---------------------------------- --------------------------------------------
   lig_psolv_grid                     protein desolvation penalty                 
   ---------------------------------- --------------------------------------------
   lig_wsolv_grid                     probe desolvation penalty                   
   ---------------------------------- --------------------------------------------
   lig_intvdw_grid                    interaction + van der Waals *(for masking)* 
   ---------------------------------- --------------------------------------------
   lig_probe_burial_grid              fractional amount water probe is buried     
   ================================== ============================================

Protein Only
-------------------------------------------------------------------------------

   ================================== ============================================
   Grid Name (protein only)           Description                                 
   ================================== ============================================
   **neut_diff_apo_free_energy_grid** water - neutral probe free energy difference
   ---------------------------------- --------------------------------------------
   neut_diff_apo_enthalpy_grid        water - neutral probe enthalpy difference   
   ---------------------------------- --------------------------------------------
   neut_diff_apo_entropy_grid         water - neutral probe entropy difference    
   ---------------------------------- --------------------------------------------
   **apo_vdw_grid**                   van der Waals energy                        
   ---------------------------------- --------------------------------------------
   **apo_order_grid**                 fractional entropy loss from electrostatics 
   ---------------------------------- --------------------------------------------
   **apo_mask_grid**                  clash: 0, bulk solvent: 0.98, no clash: 1.01
   ---------------------------------- --------------------------------------------
   apo_point_grid                     bump: 0, bulk solvent: 0.98, calc: 1.01     
   ---------------------------------- --------------------------------------------
   vac_diff_apo_free_energy_grid      water - vacuum probe free energy difference 
   ---------------------------------- --------------------------------------------
   vac_diff_apo_enthalpy_grid         water - vacuum probe enthalpy difference    
   ---------------------------------- --------------------------------------------
   apo_free_energy_grid               free energy of probe water vs continuum     
   ---------------------------------- --------------------------------------------
   apo_enthalpy_grid                  enthalpy of probe water vs continuum        
   ---------------------------------- --------------------------------------------
   apo_entropy_grid                   entropy of probe water vs continuum         
   ---------------------------------- --------------------------------------------
   neutral_apo_free_energy_grid       free energy of neutral probe vs continuum   
   ---------------------------------- --------------------------------------------
   neutral_apo_enthalpy_grid          enthalpy of neutral probe vs continuum      
   ---------------------------------- --------------------------------------------
   neutral_apo_entropy_grid           entropy of neutral probe vs continuum       
   ---------------------------------- --------------------------------------------
   apo_interaction_grid               Poisson Boltzmann electrostatic interaction 
   ---------------------------------- --------------------------------------------
   apo_psolv_grid                     protein desolvation penalty                 
   ---------------------------------- --------------------------------------------
   apo_wsolv_grid                     probe desolvation penalty                   
   ---------------------------------- --------------------------------------------
   apo_vdw_grid                       van der Waals energy                        
   ---------------------------------- --------------------------------------------
   apo_intvdw_grid                    interaction + van der Waals *(for masking)* 
   ---------------------------------- --------------------------------------------
   apo_probe_burial_grid              fractional amount water probe is buried     
   ================================== ============================================

(Complex - Protein - Ligand) Stabilization
-------------------------------------------------------------------------------

   =================================== ============================================
   Grid Name (cplx - prot - lig)       Description                                 
   =================================== ============================================
   **neut_diff_stbl_free_energy_grid** neutral free energy difference stabilization
   ----------------------------------- --------------------------------------------
   neut_diff_stbl_enthalpy_grid        neutral enthalpy difference stabilization   
   ----------------------------------- --------------------------------------------
   neut_diff_stbl_entropy_grid         neutral entropy difference stabilization    
   ----------------------------------- --------------------------------------------
   **stbl_vdw_grid**                   van der Waals stabilization                 
   ----------------------------------- --------------------------------------------
   **stbl_order_grid**                 fractional entropy loss (ES) stabilization  
   ----------------------------------- --------------------------------------------
   **stbl_mask_grid**                  clash: 0, bulk solvent: 0.98, no clash: 1.01
   ----------------------------------- --------------------------------------------
   vac_diff_stbl_free_energy_grid      vacuum free energy difference stabilization 
   ----------------------------------- --------------------------------------------
   vac_diff_stbl_enthalpy_grid         vacuum enthalpy difference stabilization    
   ----------------------------------- --------------------------------------------
   stbl_free_energy_grid               probe water free energy stabilization       
   ----------------------------------- --------------------------------------------
   stbl_enthalpy_grid                  probe water enthalpy stabilization          
   ----------------------------------- --------------------------------------------
   stbl_entropy_grid                   probe water entropy stabilization           
   ----------------------------------- --------------------------------------------
   stbl_neutral_free_energy_grid       neutral probe free energy stabilization     
   ----------------------------------- --------------------------------------------
   stbl_neutral_enthalpy_grid          neutral probe enthalpy stabilization        
   ----------------------------------- --------------------------------------------
   stbl_neutral_entropy_grid           neutral probe entropy stabilization         
   ----------------------------------- --------------------------------------------
   stbl_interaction_grid               Electrostatic interaction stabilization     
   ----------------------------------- --------------------------------------------
   stbl_psolv_grid                     protein desolvation penalty stabilization   
   ----------------------------------- --------------------------------------------
   stbl_wsolv_grid                     water desolvation penalty stabilization     
   ----------------------------------- --------------------------------------------
   stbl_vdw_grid                       van der Waals stabilization                 
   ----------------------------------- --------------------------------------------
   stbl_intvdw_grid                    interaction + van der Waals stabilization   
   ----------------------------------- --------------------------------------------
   stbl_probe_burial_grid              fractional probe burial stabilization       
   =================================== ============================================




.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. index:: Appendix 2

.. _chapter_appendix2:

====================================
Appendix 2: SZMAP Atom Properties
====================================

:ref:`chapter_szmap` calculations at a list of coordinates attach one or more of the following
properties to the atoms that specify the coordinates. Key
properties are in **bold**.

Complex, Apo or Ligand
-------------------------------------------------------------------------------

   ==================================== ============================================
   Property Name (cplx, lig, or apo)    Description                                 
   ==================================== ============================================
   **szmap_neut_diff_free_energy**      water - neutral probe free energy difference
   ------------------------------------ --------------------------------------------
   szmap_neut_diff_enthalpy             water - neutral probe enthalpy difference   
   ------------------------------------ --------------------------------------------
   szmap_neut_diff_entropy              water - neutral probe entropy difference    
   ------------------------------------ --------------------------------------------
   **szmap_vdw**                        van der Waals energy                        
   ------------------------------------ --------------------------------------------
   **szmap_order**                      fractional entropy loss from electrostatics 
   ------------------------------------ --------------------------------------------
   **szmap_clash**                      if point clashes, property = "CLASH"        
   ------------------------------------ --------------------------------------------
   szmap_mask                           clashing: 0, nonclashing: 1
   ------------------------------------ --------------------------------------------
   szmap_vac_diff_free_energy           water - vacuum probe free energy difference 
   ------------------------------------ --------------------------------------------
   szmap_vac_diff_enthalpy              water - vacuum probe enthalpy difference    
   ------------------------------------ --------------------------------------------
   szmap_vac_diff_entropy               water - vacuum probe entropy difference     
   ------------------------------------ --------------------------------------------
   szmap_free_energy                    free energy of probe water vs continuum     
   ------------------------------------ --------------------------------------------
   szmap_enthalpy                       enthalpy of probe water vs continuum        
   ------------------------------------ --------------------------------------------
   szmap_entropy                        entropy of probe water vs continuum         
   ------------------------------------ --------------------------------------------
   szmap_neutral_free_energy            free energy of neutral probe vs continuum   
   ------------------------------------ --------------------------------------------
   szmap_neutral_enthalpy               enthalpy of neutral probe vs continuum      
   ------------------------------------ --------------------------------------------
   szmap_neutral_entropy                entropy of neutral probe vs continuum       
   ------------------------------------ --------------------------------------------
   szmap_interaction                    Poisson Boltzmann electrostatic interaction 
   ------------------------------------ --------------------------------------------
   szmap_psolv                          protein desolvation penalty                 
   ------------------------------------ --------------------------------------------
   szmap_wsolv                          water probe desolvation penalty             
   ------------------------------------ --------------------------------------------
   szmap_intvdw                         interaction + van der Waals *(for masking)* 
   ------------------------------------ --------------------------------------------
   szmap_probe_burial                   fractional amount water probe is buried     
   ==================================== ============================================

(Complex - Protein - Ligand) Stabilization
-------------------------------------------------------------------------------

   ====================================   ============================================
   Property Name (cplx - prot - lig)      Description
   ====================================   ============================================
   **szmap_neut_diff_stbl_free_energy**   neutral free energy difference stabilization
   ------------------------------------   --------------------------------------------
   szmap_neut_diff_stbl_enthalpy          neutral enthalpy difference stabilization
   ------------------------------------   --------------------------------------------
   szmap_neut_diff_stbl_entropy           neutral entropy difference stabilization
   ------------------------------------   --------------------------------------------
   **szmap_stbl_vdw**                     van der Waals energy stabilization
   ------------------------------------   --------------------------------------------
   **szmap_stbl_order**                   fractional entropy loss (ES) stabilization
   ------------------------------------   --------------------------------------------
   **szmap_stbl_clash**                   if point clashes, property = "CLASH"
   ------------------------------------   --------------------------------------------
   szmap_stbl_mask                        clashing: 0, nonclashing: 1
   ------------------------------------   --------------------------------------------
   szmap_vac_diff_stbl_free_energy        vacuum free energy difference stabilization
   ------------------------------------   --------------------------------------------
   szmap_vac_diff_stbl_enthalpy           vacuum enthalpy difference stabilization
   ------------------------------------   --------------------------------------------
   szmap_vac_diff_stbl_entropy            vacuum entropy difference stabilization
   ------------------------------------   --------------------------------------------
   szmap_stbl_free_energy                 probe water free energy stabilization
   ------------------------------------   --------------------------------------------
   szmap_stbl_enthalpy                    probe water enthalpy stabilization
   ------------------------------------   --------------------------------------------
   szmap_stbl_entropy                     probe water entropy stabilization
   ------------------------------------   --------------------------------------------
   szmap_stbl_neutral_free_energy         neutral probe free energy stabilization
   ------------------------------------   --------------------------------------------
   szmap_stbl_neutral_enthalpy            neutral probe enthalpy stabilization
   ------------------------------------   --------------------------------------------
   szmap_stbl_neutral_entropy             neutral probe enthalpy stabilization
   ------------------------------------   --------------------------------------------
   szmap_stbl_interaction                 Poisson Boltzmann electrostatic interaction
   ------------------------------------   --------------------------------------------
   szmap_stbl_psolv                       protein desolvation stabilization
   ------------------------------------   --------------------------------------------
   szmap_stbl_wsolv                       water probe desolvation stabilization
   ------------------------------------   --------------------------------------------
   szmap_stbl_intvdw                      interaction + van der Waals stabilization
   ------------------------------------   --------------------------------------------
   szmap_stbl_probe_burial                fractional probe burial stabilization
   ====================================   ============================================


.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _szmap_citation:

************
Citation
************

.. note:: To cite SZMAP please use the following:

    SZMAP |szmap_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com. (2013)


.. SZYBKI documentation master file
.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



#################################
SZYBKI |szybki_version|
#################################

.. toctree::
   :maxdepth: 3

   introduction
   szybki/szybki
   freeform/freeform
   theory/theory
   utilities
   releasenotes/index
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt





.. _szybki_introduction:

.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


================
Overview
================

**SZYBKI** consists of four applications that carry out force field calculations on
small molecule ligands or protein-ligand complexes with small molecule ligands.
The main program, **SZYBKI**, is a general purpose program with a wide spectrum of
force field functionalities. Input for **SZYBKI** is all-atom molecular structures
for the ligands (and, if desired, a protein) with plausible 3-dimensional atomic
coordinates. The other program, **Freeform**, calculates some thermodynamic properties for small molecules
that are useful for drug discovery. Input for **Freeform** is a file of
molecular structures for the ligands in a variety of formats ranging from SMILES
strings to all-atom multiconformer formats. The output from both programs is
all-atom molecular structures with associated information in the log output
on the details of the calculations.

.. note::

 Units of energy in various **SZYBKI** outputs are in kcal/mol.

==============
Applications
==============

The **SZYBKI** distribution comprises two applications:

:ref:`SZYBKI <chapter_szybki>`

  * Performs force field energy evaluations or geometry optimizations
  * Operates on ligands alone or ligands posed in a protein active site
  * Can include the effects of solvation within two continuum dielectric approximations
  * Has multiprocessor capability using MPI

:ref:`Freeform <chapter_freeform>`

  * Calculates important minima in the unbound aqueous ensemble of a ligand
  * Provides the free energy of going from an ensemble of solution phase conformers to a single, bioactive conformation
  * Calculates the hydration free energy of unbound ligands
  * Calculates the strain free energy of any conformation of a ligand

As input, **SZYBKI** and **Freeform** will often take ligand conformer databases generated by **OMEGA**. 
For protein-ligand calculations, output from **OEDocking**
is also often used as input for **SZYBKI** and **Freeform**. The output from these two programs
is often directly actionable, or it can be used as input for further physics-based
modeling such as **SZMAP**.

==================
Utility Programs
==================

The following utility programs are also included in this distribution:

* :ref:`OptLigandInDU`: Optimizes a ligand in a rigid protein active site, making it suitable for large scale screening.

* :ref:`OptimizeDU`: Optimizes a protein-ligand complex in a design unit, allowing the protein to be partially flexible,
  making it suitable for lead optimization.


.. _chapter_szybki:

*********************************
SZYBKI
*********************************

.. toctree::
   :maxdepth: 2

   szybki_overview
   szybki_example
   szybki_help
   szybki_req_params
   szybki_opt_params


.. _szybki_overview:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


================
Overview
================

**SZYBKI** is a general purpose program with a wide spectrum of
force field functionalities including, but not limited to, ligand, protein, and
protein-ligand complex optimization in gas and solvent phases.


.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: szybki

.. _szybki_example:

======================
Example Commands
======================

This section has several examples of typical **SZYBKI** command line executions.

Protein Preparation
--------------------
X-ray protein structures rarely contain all hydrogen atoms coordinates. It is therefore necessary
to prepare the protein structure before any protein-bound ligand calculations are done.

.. code-block:: bash

   prompt> szybki -optGeometry Honly -prefix ex1 -neglect_frozen protein.pdb proteinH.mol2

In this command, the input protein file ``protein.pdb`` is assumed to contain all heavy
atoms. Option :option:`-optGeometry` followed by the string ``Honly`` fixes all heavy
atoms at their positions given in the input file. For larger proteins, it is recommended
to increase the total number of optimizer iterations beyond the default value of 1000
using the option :option:`-max_iter`. It might be particularly important if a tight convergence
of 1e-6 or smaller is required (see :option:`-grad_conv`). The output protein file is
``proteinH.mol2``. Note: All ionizable residues are assumed to be in their standard ionization states.
If other than standard ionization states are needed, the input file has to be edited accordingly
before the **SZYBKI** run is done.

Ligand Optimization in Solution
--------------------------------
The equilibrium geometry of a molecule in solution is sometimes drastically different than in vacuum.
This is because of solvent forces. The most efficient way to optimize a large set of ligands in
solution is the usage of the :option:`-sheffield` option.

.. code-block:: bash

   prompt> szybki -sheffield -am1bcc -prefix ex2 ligands.sdf ligands_optimized.sdf

In the run above, a set of molecules from the input file ``ligands.sdf`` is optimized with the
MMFF94 force field in solution. AM1BCC charges are optionally used for the Sheffield solvation model.
Skipping the :option:`-am1bcc` would result in the usage of MMFF94 atomic charges. Optimized structures
are written to the ``ligands_optimized.sdf`` file. One can also optimize the ligand in solution using
a physically more rigorous model by solving the Poisson-Boltzmann equation at every step. The command line
below is equivalent to using the widely known PBSA model:

.. code-block:: bash

   prompt> szybki -solvent` ``PB`` -solventCA 0.005 -prefix ex3 ligands.sdf ligands_optimizedPB.sdf

Optimization with Fixed Atoms
------------------------------
This example illustrates the use of the option :option:`-fix_file`.

.. code-block:: bash

   prompt> szybki -fix_file f.txt -prefix ex4 mymolecule.mol2 molecule_opt.sdf

Text file ``f.txt`` contains molecules names followed by atom numbers in the (0,1...N-1) numbering
convention. For example, the ``f.txt`` file contains the following six lines:

|
| Molecule1
| 0
| 15
| Molecule2
| 5
| 9

This informs **SZYBKI** that atoms 0 and 15 for molecule ``Molecule1`` and atoms 5 and 21 for molecule
``Molecule2`` should be fixed during optimization. This flag is useful when the user wants to
fix atoms which are not directly bonded; for example, they belong to different functional groups
in the optimized molecule. In the case a common substructure has to be fixed, an option
:option:`-fix_smarts` is more convenient to use:

.. code-block:: bash

   prompt> szybki -fix_smarts fix_smarts.txt -prefix ex4a mymolecule.mol2 molecule_opt1.sdf

where file ``fix_smarts.txt`` contains a single line with the SMARTS pattern ``c1ccccc1``
that defines the substructure to be fixed.

Ligand Entropy Calculation in Solution
--------------------------------------
Assuming that the molecule conformations are given in the ``molecule.oeb`` file, the command line execution:

.. code-block:: bash

   prompt> szybki -entropy AN -sheffield -prefix ex8  molecule.oeb

will result in the standard molar entropy estimation of the input molecule in solution. The
meaning of the parameter value ``AN`` is explained in the description of the option
:option:`-entropy`. Option :option:`-sheffield` informs **SZYBKI** that the calculation will be done in
solution with the use of the Sheffield Solvation Model.
The entropy results will be written in the  ``ex8.log`` file. If the input file ``molecule.oeb``
does not contain the complete ensemble of conformations, the resultant entropy value may not be
accurate. We recommend therefore that the input conformations are generated with the OpenEye tool **OMEGA**,
with the :option:`omega -rms` option set at 0.1 value, and :option:`omega -maxconfs` set to at least 1000.

Protein-bound Ligand Entropy Calculation
----------------------------------------
Run:

.. code-block:: bash

   prompt> szybki -p protein.mol2 -entropy AN -prefix ex9 ligand.mol2

will generate the estimation of ligand entropy in the active site of the protein. Input file
``ligand.mol2`` might be a docked structure or preferentially the X-ray structure.

Binding Entropy Calculation
---------------------------
A workflow for estimating binding entropy is shown in the figure below.

.. _binding_entropy_workflow1:

.. figure:: /_images/Entropy_workflowA.png
   :scale: 60
   :align: center
   :alt: Binding Entropy

   **Figure 1.** A basic workflow for binding entropy estimation.

As Figure 1 shows, estimating binding entropy, :math:`\Delta S_b`, requires two separate
**SZYBKI** runs: one for the estimation of ligand entropy in solution (:math:`S_{sol}`) and another
one to calculate protein-bound ligand entropy (:math:`S_{bnd}`).
It is possible to calculate binding entropy (:math:`\Delta S_b`) in a single **SZYBKI** run

.. code-block:: bash

   prompt> szybki -complex complex.oeb -entropy AN  -prefix ex10 -sheffield -in ligand.oeb

where ``complex.oeb`` is a molecular file of the protein-ligand complex and ``ligand.oeb`` contains
an ensemble of conformations of the ligand in solution. Note: The docked
ligand in the ``complex.oeb`` file must represent a single pose and must be the same molecule as in
the ``ligand.oeb`` input file. In the case where two or more docked poses are used, calculation of
binding entropy requires two separate runs as shown in Figure 1.




.. _szybki_help:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*

.. program:: szybki

======================
Command Line Help
======================

A description of the command line interface can be obtained by executing **SZYBKI**
with the `--help` option.

.. code-block:: console
   
   prompt> szybki --help

will generate the following output:

::

  Simple parameter list

    Execute Options
       -param : A parameter file

    Input Molecules
      Input Files Option 1 : Input molecule and optional protein
        -in : Name of the input molecule file. Aliases are -in and -i
        -protein : Name of the input protein file (not required)

    Input Files Option 2 : Ligand-protein complex
        -complex : Name of the input protein file with ligand(s)

    Output
      Output File Options
        -prefix : Replaces the default prefix for log, status, param and rpt
                  files

      Explicitly specify individual file names
        -out : Name of the output molecular file

    Potential Function
      -ff : Force field to be used. Overwrites selection made with "-MMFF94S"   
         

    Optimization
      -optGeometry : Specification of degrees of freedom used for optimization

  Additional help functions:
    szybki --help simple      : Get a list of simple parameters (as seen above)
    szybki --help all         : Get a complete list of parameters
    szybki --help defaults    : List the defaults for all parameters
    szybki --help <parameter> : Get detailed help on a parameter
    szybki --help html        : Create an html help file for this program
    szybki --help versions    : List the toolkits and versions used in the application


.. _szybki_req_params:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: szybki 

======================
Required Parameters
======================

Input Files Option
^^^^^^^^^^^^^^^^^^^^^

Either option :option:`-in` or option :option:`-complex` must be used to
perform a **SZYBKI** run.

.. option:: -in <filename>

   Molecular input file name containing 3D coordinates in any format
   supported by **OEChem**. In order to comply with previous **SZYBKI**
   releases, an alias :option:`-i` can be used instead of :option:`-in`. This
   option might be used as a keyless parameter without the ``-in`` or ``-i`` keys but
   only when used last or next to last when the last option on the
   command line is :option:`-out`. Warning: The file name ``szybki_out.oeb``
   is used as the default output file name, so it should be avoided as an
   input file name.

.. option:: -i <filename>

   An alias to :option:`-in`.

.. option:: -ligands <filename>

   An alias to :option:`-in`.

.. option:: -protein <filename>

   Protein input file with 3D coordinates in any format supported by
   **OEChem**. This works in combination with the :option:`-in`
   option. No removal of preexisting ligands in the file ``filename`` will be done
   as in the case of the :option:`-complex` option. This option can be
   aliased with :option:`-p` for compatibility with previous **SZYBKI** releases.

.. option:: -p <filename>

   An alias to :option:`-protein`.

.. option:: -complex <filename>

   Input file with 3D coordinates of a protein-ligand complex in
   any format listed in the table above. All ligands contained in the
   molecule file ``filename`` will be optimized one by one in the
   presence of all others. 

Input File Formats
^^^^^^^^^^^^^^^^^^^^^^

**SZYBKI** can handle molecular files in the following formats.

.. list-table:: *SZYBKI File Format Support*
   :widths: 20 25
   :header-rows: 1

   * - File extension
     - Description
   * - mol
     - MDL Mol File
   * - mmd, mmod
     - Macromodel
   * - mol2
     - Tripos Sybyl mol2 file
   * - oeb
     - New Style OEBinary
   * - pdb
     - Protein Databank PDB file
   * - sd, sdf
     - MDL SD File
   * - xyz
     - XMol XYZ format



.. _szybki_opt_params:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: szybki

======================
Optional Parameters
======================

Execute Options
^^^^^^^^^^^^^^^^^^^

.. option:: -param <filename>

   Command line options will be read from the specified file. This
   file may have been generated from a previous run or may be
   constructed de novo. The default name of the file is
   ``szybki.param``. Any parameter in the parameter setup file is superseded by
   the parameter on the command line. For example, running ``szybki
   -param szybki.param -i my.pdb`` will perform calculations for the
   molecule ``my.pdb`` while using all other parameters taken from
   ``szybki.param``.

.. option:: -mpi_np <n>

   Specifies the number of processors ``n`` when **SZYBKI** is run in MPI mode.

.. option:: -mpi_hostfile <filename>

   Specifies the name of the file containing processors configuration. For every host,
   this file should contain a line ``host_name n`` where ``n`` is the number of 
   processors on the host.  

Molecule Preparation Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -strip_water

   Causes removal of water molecules from the input protein when
   options :option:`-protein` or :option:`-complex` are used.

.. option:: -largest_part

   Calculations are performed only for the largest fragment of the
   noncovalent input complex. For example, when the input file contains
   coordinates for the salt, :math:`[Large\_cation^+]\cdot[Cl^-]`, the
   use of the :option:`-largest_part` will cause the :math:`Cl^-` anion to be
   ignored. By default, calculations are done for the entire complex.

Output Options
^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -silent

   By default, the names of the processed molecules are displayed. The
   use of the option :option:`-silent` will suppress this output.

.. option:: -verbose

   An extensive general output will be generated containing initial and
   final energy and gradient data, as well as an optimization report.

.. option:: -prefix <pn>

   Replaces the ``szybki`` prefix in .log, .rpt (report), .status , .param,
   and _out.oeb files, with the input string ``pn``.

.. option:: -report

   An output file in tabular form of final energy components for every
   molecule/conformer will be generated. The name of the file is fixed
   as ``prefix.rpt``, where ``prefix`` is ``szybki`` by default or
   determined by the :option:`-prefix` option.

.. option:: -sdtag <string>

   In the case when the output file is in the SD format, an energy tag can
   be added. For single molecules, by default all energy terms (MMFF, solvation, and
   constraint) plus ``Total energy`` are added, so the option has no effect.
   "Total energy" always contains the constraint terms. In the case of protein-ligand
   systems, only the relevant terms (``Ligand-Protein Energy`` and all of its components)
   are attached as SD tags by default. The option can be used therefore to add one of the
   remaining terms from the list below. If ``string`` is set to ``all``, all energy terms
   are tagged as SD tags.

   1.  ``VdW``
   2.  ``Coulomb``
   3.  ``Bond``
   4.  ``Bend``
   5.  ``StretchBend``
   6.  ``Torsion``
   7.  ``Improper Torsion``
   8.  ``L VdW``
   9.  ``L Coulomb``
   10. ``L Bond``
   11. ``L Bend``
   12. ``L StretchBend``
   13. ``L Torsion``
   14. ``L Improper Torsion``
   15. ``P VdW``
   16. ``P Coulomb``
   17. ``P Bond``
   18. ``P Bend``
   19. ``P StretchBend``
   20. ``P Torsion``
   21. ``P Improper Torsion``
   22. ``PL VdW``
   23. ``PL Coulomb``
   24. ``Ligand-Protein Energy``
   25. ``Sheffield Solvation``
   26. ``Constraint Potential``
   27. ``PB Solvent``
   28. ``Area Solvent``
   29. ``__VdW``
   30. ``__Coulomb``
   31. ``__Protein desolv``
   32. ``__Ligand desolv``
   33. ``__Solvent screening``
   34. ``__Grid Coulomb``
   35. ``__Exact Coulomb``
   36.  ``P/L energy``
   37. ``__AMBER VdW``
   38. ``__AMBER Coulomb``
   39. ``Torsion Constraint``
   40. ``IEFF Interaction``
   41. ``InterLigand IEFF``

   If the parameter ``string`` does not correspond to one of the available
   energy terms, no tag will be written. Tags starting with L, P, PL
   and ``__`` are:

   * L: ligand intramolecular terms only
   * P: protein intramolecular terms only
   * PL: protein-ligand intermolecular terms only
   * ``__``: protein-ligand interaction terms

.. option:: -keepFailures

   By default, molecules which failed during processing are store in the file
   ``prefix.FAIL.input_format`` where ``input_format`` is that of the input molecule
   used in option :option:`-ligands`. If the flag is set to ``true``, those failed
   molecules are written to the molecule output file.

.. option:: -heavy_rms

   By default, the RMSD of all atoms after optimization is reported in the log file.
   This option replaces the default with the heavy atoms RMSD.

.. option:: -l <filename>

   An alias to :option:`-log`.

.. option:: -log <prefix>

   Prefix of the log file name, ``prefix.log``. If omitted, the prefix
   ``szybki`` is used by default. This option is aliased to :option:`-l`.

.. option:: -o <filename>

   An alias to :option:`-out`.

.. option:: -out <filename>

   Output file name, in any format supported by **OEChem**, for an
   optimized ligand. If not specified, ``szybki_out.oeb`` or
   ``prefix_out.oeb`` (when :option:`-prefix` is used) will be
   generated. Alias ``-o`` can be used instead of ``-out``. This can be used as
   a keyless parameter without the ``-out`` key when it is last on the command
   line just after the :option:`-in` (or :option:`-i` or :option:`-ligands`)
   option.

.. option:: -out_protein <filename>

   Partially optimized protein will be saved in a file named ``filename``. By default, this option is
   not used; however, modified coordinates of a protein are still saved in the form of a generic data
   attached to the optimized ligand when it is output in the oeb format, under the tag ``saveprot``.
   One can easily extract coordinates of the optimized protein using **OEChem TK** or **VIDA**.

.. option:: -out_complex <filename>

   Protein-ligand complex for partially optimized protein will be saved in a file named ``filename``.

.. option:: -reportFile <filename>

   Sets user-selected file name, ``filename``, for the tab file. Supersedes the
   :option:`-report` option described above.

Force Field Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -ff

   Force field to be used. Valid options are: ``mmff94``, ``mmff94s``, ``amber_mmff94``, ``amber_mmff94s``,
   ``ieff_mmff94``, ``ieff_mmff94s``, ``smirnoff99frosst``, ``parsley_openff``, ``sage_openff``,
   ``ff14sb_parsley``, and ``ff14sb_sage``.

   Upper case options are also accepted.
   In addition to the above, this command also accepts any SMIRNOFF force field parameter file in XML format.

   This option overwrites the deprecated option
   ``-MMFF94s`` when both are used simultaneously. The combined potential AMBER-MMFF94
   (or AMBER-MMFF94s) can be applied only for protein-ligand interactions using a rigid protein model.
   All intramolecular ligand interactions are described by the MMFF94 (or MMFF94s) force field while
   intermolecular protein-ligand interactions are handled by the Amber force field. ``ieff_mmff94``
   and ``ieff_mmff94s`` potentials can be used only for intermolecular interactions provided that 
   electrostatic multipoles are assigned to the molecules.
   Combined potential ``ff14sb_parsley`` or ``ff14sb_sage`` can be applied for optimization of a protein
   system which might contain cofactors and ligands. In such a case, the protein part is handled with the ff14SB
   version of AMBER while ligands and cofactors by the latest ``parsley`` or ``sage`` force field.
   Currently selecting ``ff14sb_parsley`` or ``ff14sb_sage`` cannot be combined with :option:`-protein`
   option. In order to optimize a part of a protein-ligand complex (e.g., the ligand), with the ``ff14sb_parsley``
   or ``ff14sb_sage`` potential, one can specify a list of flexible atoms using :option:`-flex_file`.

.. option:: -exact_vdw

   By default, the van der Waals protein-ligand interaction is calculated with the use of lookup tables in order
   to speed up the calculations. This option allows using the exact analytical van der Waals potential for the
   optimization of a ligand in the protein binding site.

.. option:: -mod_vdw

   Regular MMFF :ref:`sub-section_VdW` equation will be replaced with:

   :math:`V_{vdw} = \left\{ \begin{array}{cc} \epsilon_{ij} \left(
   \frac{1.07R_{ij}}{r_{ij}+0.07R_{ij}} \right) ^7 \left(
   \frac{1.12R_{ij}^7}{r_{ij}^7 +0.12R_{ij}} -2 \right) & \mbox{for
   $r_{ij} < R_{ij}$} \\ -\epsilon_{ij} & \mbox{for $r_{ij} \geq R_{ij}$}
   \end{array} \right.`

   in which no attractive van der Waals forces are present. This type of van der Waals
   potential prevents a so-called "hydrophobic collapse."

.. option:: -neglect_frozen

   After an optimization with frozen terms, the default behavior calls
   for a full single-point calculation of the whole system.  The
   :option:`-neglect_frozen` option will skip this final calculation of the
   whole system, thus yielding results for only the non-frozen pieces.
   When there is a large frozen section, this can drastically reduce
   memory and CPU usage.

.. option:: -noCoulomb

   Electrostatic terms defined in the :ref:`electrostatic interactions <sub-section_electrostatic>` section will be excluded from
   the force field potential. This option might be useful to prevent
   generation of folded structures.

.. option:: -protein_vdw <r>

   Calculation of van der Waals protein-ligand interaction energy will be
   limited to a sphere of radius ``r``. The default value is
   18.0 |A|. In many applications, a value as small as 10 |A| can be
   used with essentially no effect on the final optimized ligand
   geometry. The legal range is 5–500 |A|.

.. option:: -strict

   Enforces strict atom typing. This is a default behavior. When the value of the flag is selected to
   be ``false``, this enforcement is removed.

.. option:: -vdw_cutoff

   Sets distance for intramolecular van der Waals interactions. By default, all atom pairs in the molecules
   contribute to the molecule's van der Waals energy. The legal range is 5–500 |A|.

Charging Options
^^^^^^^^^^^^^^^^^^^

.. option:: -am1bcc

   AM1BCC charges [Jakalian-2002]_ are calculated for every conformation
   and used for the PB or Sheffield solvation energy only. Those charges are therefore conformation-dependent,
   and reflect changes of molecular density with molecular geometry.
   Note that AM1BCC charges are conventionally calculated for just one conformer or a few conformers
   of a multiconformer molecule, those conformers with electrostatically least-interacting
   functional (ELF) groups, so calculating AM1BCC charges for every conformer with this
   option is unconventional. For conventional behavior, apply AM1BCC ELF charges to the
   molecule separately and then use that as the input structure with the ``-current_charges`` option.

.. option:: -current_charges

   During optimization of molecules in solution with the use of the
   Poisson-Boltzmann solvation model, the free energy of solvation and
   solvent forces can be calculated with the use of atomic partial
   charges other than MMFF. The option :option:`-current_charges` allows the use of
   partial charges read from the input molecular file. In the case where
   the ligand is optimized inside a protein, protein-ligand
   electrostatic interactions (coulomb and/or Poisson-Boltzmann) could
   be calculated based on ligand and protein partial charges read from
   the molecular input files. When input partial charges are not found,
   the MMFF94 partial charges will be used.

Solvent Options 
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -inner_dielectric <d>

   The default value for the protein or ligand dielectric constant of 1.0 can be
   changed to a user-selected value ``d``. This option is aliased as ``-protein_dielectric``.
   The upper allowed limit is 20.0.

.. option:: -shefA <a>

   Parameter ``a`` in the Sheffield solvation potential given in option
   :option:`-sheffield`. If the option is not used, a value of 1.553149 is assigned
   [Grant-2007]_.

.. option:: -shefB <b>

   Parameter ``b`` in the Sheffield solvation potential given in option
   :option:`-sheffield`. If the option is not used, a value of 0.735694 is assigned
   [Grant-2007]_.

.. option:: -sheffield

   Use of this option will result in adding an additional electrostatic
   term in order to mimic the solution environment according to [Grant-2007]_.
   This term is of the form:
   :math:`f_\epsilon/(8\pi\epsilon_0)\sum_{i,j}q_iq_j/\sqrt{(ar^2 + bR_iR_j)}`,
   where :math:`f_\epsilon=(1/\epsilon_{in}-1/\epsilon_{out})`,
   :math:`q_i`, and :math:`q_j` are partial charges,
   and :math:`R_i` and :math:`R_j` are van der Waals radii of atoms ``i`` and ``j``.
   While less accurate than Poisson-Boltzmann, this method is very fast and offers
   analytic first and second derivatives. Because of the latter, it is the only
   solvation option for entropy calculations.

.. option:: -solv_dielectric <d>

   Allows changing the default value for solvent dielectric constant used for Poisson-Boltzmann
   and Sheffield solvation energy calculations. The allowed range is 1 to 100. Default value is 80.

.. option:: -solventCA <s>

   This option can only be used in combination with :option:`freeform -solvent` ``PB`` or :option:`-sheffield`.
   It causes inclusion of a molecular surface solvation term (sometimes called cavity solvation
   term) in the total energy.  The value of parameter ``s`` (microscopic surface tension coefficient)
   is in the range 0.005–0.030 kcal/(mol |A|:math:`^2`). This option is aliased as
   `-solventMA` for compatibility with previous releases.

.. option:: -solventPB

   For optimization of small molecules in solution, the electrostatic
   part of molecule-solvent interactions will be calculated using
   Poisson-Boltzmann model.

.. option:: -protein_elec <m>

   This option provides four choices for calculating protein-ligand electrostatic interaction energies:
   ``m = None, ExactCoulomb, GridCoulomb``, and ``PB``.
   The option ``m`` = ``None`` eliminates electrostatic interactions.
   Values of ``m`` set at ``ExactCoulomb`` and ``GridCoulomb`` result in the usage of coulomb exact
   potential and digitized on the grid, respectively.
   Option ``m`` = ``PB`` provides a more realistic potential which accounts for solvent forces,
   calculated according to the Poisson-Boltzmann model at every iteration step.
   This option requires substantially higher CPU time, particularly for large proteins.
   By default, ``m`` = ``ExactCoulomb``.

.. option:: -radii <type>

   Determines types of atomic radii used for PB calculations
   (options: :option:`freeform -solvent` ``PB`` and :option:`-protein_elec`). By default, the parameter
   ``type`` is set to ``Bondi``. Two other choices are ``ZAP9`` and ``ZAP7``
   [Nicholls-2010]_.

.. option:: -salt <c>

   Allows to all PB calculations to be performed at a specified salt concentration
   in M, up to 0.08M. By default, the salt concentration is zero.

Saving and Loading Coulombic Grids
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -loadPG <filename>

   In the case when the electrostatic component of the protein-ligand
   interaction energy has been precalculated on a grid, this option
   forces **SZYBKI** to read the grid potential from the file ``filename``, and use
   it for ligand optimization inside the protein. This option is available only
   when :option:`-protein_elec` is set with ``GridCoulomb``.

.. option:: -savePG <filename>

   Saves a potential grid in the file named ``filename``. Allows a significant saving in CPU
   time for runs when coulomb grids are used to optimize a number of ligands inside the same
   protein. This option is available only when :option:`-protein_elec` is set with ``GridCoulomb``.

Optimization Options
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -optDOF

   An alias to :option:`-optGeometry`.

.. option:: -optdof

   An alias to :option:`-optGeometry`.

.. option:: -optGeometry <dof>

   Optimization in specified degrees of freedom will be done. The possible choice for the parameter
   ``dof`` are ``cart`` for Cartesian coordinates, ``tor`` or ``torsions`` for torsion
   optimization, ``solid`` for rigid ligand optimization inside a protein receptor, ``none`` or
   ``sp`` for single point calculation, ``Honly`` for hydrogen atoms only optimization, and
   ``calculationDependent``. The value ``calculationDependent``, which is selected by default when an
   option is not used, sets the type of degrees of freedom: free ligands by default are
   optimized in Cartesian coordinates, while protein-bound ligands are in translational-rotational
   coordinates. The option is aliased with :option:`-optDOF` and :option:`-optdof`.

.. option:: -grad_conv <c>

   Optimization is terminated when the RMS gradient reaches the input
   value ``c``, unless it is finished earlier because of other reasons. When
   omitted, the default convergence criteria is 0.1 on gradient vector
   norm: :math:`\sqrt{\sum_i {g_ig_i} }`, where :math:`g_i` is the ``i-th``
   gradient component.

.. option:: -max_iter <m>

   Optimization will be terminated when the number of iteration cycles
   reaches input number ``m``. The default value is 1000.

.. option:: -optMethod <type>

   Selects optimization type. The value of ``type`` replaces the default BFGS optimizer
   for small molecules and the conjugate gradient for systems with 500 or more degrees
   of freedom. Allowed values of ``type`` are ``BFGS`` or ``bfgs`` for BFGS optimization;
   ``CG``, ``cg``, or ``conj`` for conjugate gradient; ``SD``, ``sd``, or ``steepest`` for
   steepest descent optimization; ``sd_bfgs`` for pre-optimization with five steps of steepest
   descent followed by BFGS optimization; ``sd_cg`` for pre-optimization with five steps of
   steepest descent followed by conjugate gradient optimization; and "newton" or "NEWTON"
   for Newton-Raphson optimization if analytic second derivatives are available. Entropy
   estimation requires a BFGS or Newton-Raphson type of optimization, so all values of the
   parameter ``type`` which represent different optimization methods are ignored for
   entropy runs. In addition, when a quasi-Newton method of entropy estimation is requested
   (see :option:`-entropy`), the usage of BFGS is enforced.

Fixing Ligand Atoms
^^^^^^^^^^^^^^^^^^^^^

.. option:: -fix_file <filename>

   The text file ``filename`` should contain a list of molecule names followed by atom
   numbers to be fixed. An example of the command line for a **SZYBKI** run with the use of
   this option is given below in the :ref:`szybki_example` subsection.

.. option:: -fix_smarts <file_name>

   All atoms which belong to a SMARTS pattern specified in a single line of
   the text file ``file_name`` will be fixed. For example, if the input string
   is [!#1], all heavy atoms will be fixed and a **SZYBKI** run will optimize all
   hydrogen atom positions.

.. option:: -flex_file <filename>

   The text file ``filename`` should contain a list of molecule names followed by atom
   numbers to be optimized. All non-listed atoms will be fixed. The atom numbering
   convention used is from 0 to n-1, where n is the molecule's total number of atoms.

Constraining Ligand Atoms 
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -harm_constr1 <k>

   Constrained potential of the form :math:`kr^2` will be imposed on all heavy atoms, where
   :math:`k` is the force constant. By default, no constraint is applied (:math:`k = 0`),
   and the upper allowed limit is 1000 kcal/(mol |A|:math:`^2`).

.. option:: -harm_constr2 <d>

   Constrained potential of the form :math:`V = k(r-d)^2,r>d` and :math:`V=0, r \leq d` will be imposed
   on all heavy atoms, where `d` is the constraining distance in angstroms. This can be used only
   together with :option:`-harm_constr1`. The default value is 0, while the upper allowed value is
   5 |A|.

.. option:: -harm_smarts <file.txt>

   All atoms which belong to a SMARTS pattern read from the file ``file.txt`` will be constrained.
   For example, when the file ``file.txt`` contains a single  line ``cO``, the input option
   ``-harm_smarts file.txt`` will result in constraining all aromatic carbon atoms and oxygen
   atoms bonded to them. This must be used in conjunction with :option:`-harm_constr1`.

Constraining Torsion Angles
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -tor_constr <fn>

   File name containing a single line which determines the torsion to be constrained,
   reference torsion angle, and a force constant.  The constraining potential is in the
   form :math:`V=k_c(cos(phi) - cos(phi0))^2`, where :math:`k_c` is the user-specified
   force constant, and :math:`phi0` is the reference torsion dihedral angle. The input
   data in the file ``fn`` should be in the following order:
   SMARTS  :math:`phi0` :math:`k_c`. SMARTS might be replaced with atom indices:
   :math:`i_1` :math:`i_2` :math:`i_3` :math:`i_4` :math:`phi0` :math:`k_c`.

   Examples of valid inputs are:
   ``[C:1][N:2][c:3][s:4]  0.0  2.0``
   ``5 0 10 25 0.0 2.0``
   Notice that atom indices are numbered from 0 to :math:`N-1`, where :math:`N` is the
   number of atoms in the molecule.

Protein Flexibility
^^^^^^^^^^^^^^^^^^^

.. option:: -flexdist <d>

   Specifies the distance ``d`` from the ligand that determines the flexible residues of a protein receptor
   in the optimization of a ligand inside the protein binding side. This has to be used together with
   :option:`-flextype`.

.. option:: -flexlist <fn>

   Similar to :option:`-flexdist`, but instead of using distance from the ligand as partial protein
   flexibility criteria, provides a file name ``fn`` containing flexible residues. Every line of
   this file should contain a PDB residue name, residue number, and chain ID. For example, a two-line
   file:

   |
   | ILE 78  A
   | Phe 114 B

   informs **SZYBKI** that Ile78 of chain A and Phe114 from chain B will be flexible during ligand
   optimization. This has to be used together with :option:`-flextype`.

.. option:: -flextype <type>

   Allows the user to specify the type of partial protein flexibility. The possible values of parameter ``type``
   are a string ``polarH``, ``sideC``,  or ``residue``, with respective meanings of polar
   hydrogens, side chains, and complete residues. This must be used together with :option:`-flexdist`
   or :option:`-flexlist`.
   The molecular potential used for optimization consists of three components:

   1.  Ligand intramolecular MMFF potential
   2.  Protein-ligand potential

       a.  MMFF terms for interactions between polar protein hydrogens and the ligand

       b.  Interaction between fixed protein atoms and the ligand

   3.  Protein intramolecular potential

       a.  MMFF terms involving polar protein hydrogens and atoms up to three bonds apart

       3.2.  Interaction between the rest of the protein and flexible polar hydrogens

   The sum of the components 2b and 3b might be called a "protein-pseudoligand"
   interaction and is evaluated according to the model selected with the
   :option:`-protein_elec` option above.

Entropy Calculation Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -entropy <type>

   Estimation of the entropy of a ligand will be done. The parameter ``type`` can take three
   values: "None" (default), "QN" (Quasi-Newton Hessian), and "AN" (analytical). The input ligand
   is assumed to be in the form of a multiconformational molecule. The environment is determined by
   the :option:`-sheffield` option (solution), :option:`-protein` option (in the binding site), or
   neither one, indicating a gas phase.

.. option:: -t

   Sets the temperature (in °C) of the system for entropy estimation. The default temperature
   is 25°C (298K).


.. _chapter_freeform:

*********************************
FREEFORM
*********************************

.. toctree::
   :maxdepth: 2

   freeform_overview
   freeform_example
   freeform_help
   freeform_req_params
   freeform_opt_params


.. _freeform_overview:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: freeform

======================
Overview
======================

**Freeform** calculates some thermodynamic properties for small molecules that are
useful for drug discovery.

.. caution::

   `freeform -calc conf` takes over 6 gigabytes of memory by default.

The conformer generation step of `freeform -calc conf` uses a default
maximum conformer limit of 40,000 conformers, leading to a high memory usage
of over 6 GB of memory. Reducing the maximum conformer limit with the
`-maxconfs` flag will significantly reduce memory usage, although this
may reduce the accuracy of the conformer free energies, especially with
molecules containing many rotatable bonds. If memory usage is an issue,
we recommend running a calculation using `maxconfs 20000`. If this
maximum is not reached in the initial conformer generation step (check the
line containing "generating conformers..." in the log file), then there
will be no loss in accuracy compared to the default 40,000.

.. note::

   The graph in the PDF output of `freeform -calc conf` may not show all minima.

The "dG vs Erel" graph in the PDF output of `freeform -calc conf` uses default
axes spanning only 0 to 7 kcal/mol for conformer dG and 0 to 5 kcal/mol for Erel;
generally the whole unbound ensemble contains minima above these ranges (sometimes
the majority of minima). The data for all the minima are contained in both the
output log and CSV files; the graph is intended only to show minima that could
potentially contribute significantly to the room temperature ensemble, hence the
limited range of the axes. The axes are extended somewhat to show tracked minima,
but beyond 30 kcal/mol in either dG or Erel not even these data are shown in the
graph.

.. note::

   It is possible to get a negative local strain energy with :option:`-solvent` ``PB``.

Ordinarily, local strain energy can never be negative because the energy can
only decrease once the restraints are removed and the ligand is allowed to freely
minimize. With :option:`-solvent` ``PB``, PB single-point solvation energies
are taken of the restrained minimum and the corresponding freely minimized
minimum. There are two reasons why this could result in a negative local
strain energy. The first is due to the precision of the PB calculation being
around 0.2 kcal/mol: if the true restrained and free minima are within 0.2 kcal/mol,
the restrained minimum could end up with a slightly higher PB solvation energy
simply due to the imprecision. The second reason is that the Sheffield
solvation energy used in minimizing from the restrained to the free minimum may
simply differ in the opposite direction from the PB solvation energy for the
same minima. 

.. note::

   AM1BCC ELF10 charging may use fewer than 10 conformers for charging.

AM1BCC ELF10 charging is designed to average the AM1BCC charges from 10 conformers
chosen from the 2% of the conformer population having the electrostatically
least-interacting functional (ELF) groups. Ten conformers from 2% means there must
be at least 500 conformers to start with; ligands which have fewer rotatable bonds
may not have this many. In such cases, the AM1BCC ELF10 method is designed to take
all the conformers in the 2% ELF population. For example, if the starting conformer
set has 327 conformers, all 6 conformers in the 2% ELF population will be used.
With 50 or fewer conformers, a single ELF conformer will be used. When more than
one conformer is used, the log file line starting with "Semi-empirical charge averaging"
tells how many were used.



.. _freeform_example:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: freeform

======================
Example Commands
======================

Conformer Free Energies
--------------------------------------------------------------------------------

The default calculation type in **Freeform** is ``-calc conf``, so this is what it will run
if no ``-calc`` option is specified. However, in the following examples we will specify this
calculation type explicitly. The two main types of conformer free energy calculations
are 1) when the input 3D structure is not known or not of special significance, and
for example, if they are believed to be bioactive conformers.
In the latter case, ``-track`` is specified, and **Freeform**
reports specifically on the global and local strain energies for these conformers.

.. note::
   The numbers and values in the examples below are just for illustration and can change
   as we improve the applications.

Example 1
^^^^^^^^^^^^^

Let us begin with case 1 above: when the input 3D structure is not known or not of
special significance. In this example, the input is the SMILES string for Januvia
in file ``januvia.smi``:

(Fc1cc(c(F)cc1F)C[C@@H]([NH3+])CC(=O)N3Cc2nnc(n2CC3)C(F)(F)F)

The command is:

.. code-block:: bash

   prompt> freeform -calc conf -in januvia.smi -prefix januvia.pfn

This produces five output files:

  **januvia.pfn.pdf**: the results report summarizing key results for each molecule in the run.

  **januvia.pfn.log**: the log file of per-molecule results. This also shows the progress of
  the calculation if it is taking a long time, for example, if the run has to minimize a
  conformer ensemble containing 20,000 conformers (this can take over half an hour).

  **januvia.pfn.csv**: the CSV file of per-conformer results (energies, entropies, and free energies)

  **januvia.pfn.oeb**: the file of all the final minima for the molecule.

  **januvia.pfn.param**: all the input parameters of the calculation are written here.

Let us first look at an example of a results report in the file ``januvia.pfn.pdf``, as
shown below.

.. _figure_januvia.pdf:

.. figure:: /_images/freeform_conf_januvia.png
   :width: 800px
   :align: center
   :alt: Results report from Januvia SMILES input

   **Figure 1.** Results report from Januvia SMILES input.

A 2D depiction of the molecule is shown on the left, with a table
that gives the relative energies (E(MMFF) + E(solv)) and conformer
free energies (including entropy) for the relative energy (Erel) and free energy (dG)
minimum conformations. All the energy units in *freeform* are in kcal/mol. The strain
information (local strain and global strain) is empty in this example.
The graph on the right-hand side shows the conformer free energy versus the relative
energy for all the conformers produced in the calculation for the unbound ensemble.
At the top of the graph, we note the number of rotors (rotatable bonds) sampled in the
conformation generation for this molecule (six), and the number of unique minimal in 
the entropy calculation for this molecule (188 in this example).
The red dot on the graph corresponds to the relative energy minimum (see the conformer
also labeled with a red dot in the logfile table; the conformer ID can be used to
reference it in the .oeb file, and in the .csv file).
We can also see that while it is the global energy minimum
in terms of enthalpy, it would cost the dG amount in conformer free energy to select 
this conformer from the aqueous free ligand ensemble.
In contrast, the Min dG conformer has the lowest free energy (corresponding to the 
brown dot on the graph) to select it from the ensemble.

Example 2
^^^^^^^^^^^^^

In the second example, the input file is ``sitagliptin.mol2``; it is in .mol2
format and contains the X-ray crystal coordinates for Januvia (sitagliptin).
Here we are particularly interested in the conformer free energy for this input X-ray
structure since it is the bioactive conformation. We would like to know how much
free energy it costs to select this bioactive conformation from the aqueous free ligand
ensemble. To track the input conformation throughout the calculation, we specify
:option:`-track` `sitagliptin.mol2` to indicate that we wish to use the 3D coordinates of
the input structure and to track this conformer. Note that :option:`-in` `sitagliptin.mol2`
must also be specified so that we use the same structure to derive the
conformers for the unbound aqueous ensemble. Just to be clear: the :option:`-in`
is always required to specify the molecule to be used for the unbound aqueous ensemble;
the :option:`-track` is optional, only needed for tracking one or more specific
conformers.
The command is thus:

.. code-block:: bash

   prompt> freeform -calc conf -track sitagliptin.mol2 -in sitagliptin.mol2 \
   -prefix sitagliptin.3D.pfn

This produces five output files analogous to those above for Januvia and
in addition produces these three files related to the tracked conformer,
each with:

  **sitagliptin.3D.pfn.tracked_input.oeb**, the input tracked conformer.

  **sitagliptin.3D.pfn.tracked_rstr.oeb**, the restrained minimum from the input tracked conformer.

  **sitagliptin.3D.pfn.tracked_free.oeb**, the unrestrained minimum from the input tracked conformer.

The results report is in the file sitagliptin.3D.pfn.pdf.

.. _figure_sitagliptin.3D.pfn.pdf:

.. figure:: /_images/januvia3D.png
   :width: 800px
   :align: center
   :alt: Results report from sitagliptin.3D.pfn

   **Figure 2.** The results report from sitagliptin.mol2, using the "-track" flag.

The results report in this case looks very similar to that of our first example except for
the extra line added to the table and the corresponding blue dot on the graph.
The extra line in the table relates to the bioactive
conformer specified in the input with the :option:`-track` flag. "TrConf0" is an
abbreviation for "Tracked Conformer 0", that is, the first of the tracked conformers
(in this case there was only one). The line beginning "TrConf0" gives information
on the nearest unbound minimum to the tracked conformer, locating the unrestrained
minimum from that conformer (in file **sitagliptin.3D.pfn.tracked_free.oeb**) and the
corresponding relative energy (Erel) and conformer free energy (dG). The additional columns 
for this line give the local strain energy and the global strain energy associated with the
tracked conformer.

These quantities are defined in the :ref:`Freeform Theory <chapter_freeformTheory>` section and depicted there
in :ref:`Figure 3 <figure_TrackedConformers>`, but we will briefly summarize here.
The local strain energy is the relative energy
difference (internal energy + solvation energy) between the restrained energy
minimum (the structure in file **sitagliptin.3D.pfn.tracked_rstr.oeb**) and the
nearest unbound minimum (the structure in file **sitagliptin.3D.pfn.tracked_free.oeb**).
Conceptually, it corresponds to the energy required to distort the nearest
unbound minimum to fit into the active site.
The global strain energy is the sum of the local strain energy and the conformer free 
energy of the nearest unbound minimum.

Example 3
^^^^^^^^^^^^^

The third example is like the second except that PB single-point solvation
energies are requested with the :option:`-solvent` ``PB`` option. This is a
higher level of continuum solvation theory compared to Sheffield solvation
and so the solvation energies are expected to be more accurate. Sheffield
solvation is still used in finding the minima for the unbound ensemble
because it is fast and has the necessary analytic second derivatives.
The command is:

.. code-block:: bash

   prompt> freeform -calc conf -solvent PB -track sitagliptin.mol2 \
   -in sitagliptin.mol2 -prefix sitagliptin.3D.pb.pfn

This produces eight output files analogous to those above for Example 2.

.. _figure_sitagliptin.3D.PBpfn:

.. figure:: /_images/sitagliptin3D.pb.png
   :width: 800px
   :align: center
   :alt: Results report from sitagliptin.3D.pb.pfn

   **Figure 3.** The results report from sitagliptin.mol2, using "-solvent PB".

Note that the energies and the graph differ markedly from that of Example 2.
The partial charges, the number of unique minima, and the minima themselves 
in both Example 2 and Example 3 are found using the Sheffield solvation.
The difference is the solvation energy for each conformer: in Example 2, 
the Sheffield solvation energy is used, whereas in this example
the Sheffield solvation energy has been replaced with a PB single-point
solvation energy evaluated at the coordinates of the Sheffield-based minimum.
The impact of changing to a PB energy is more pronounced with charged ligands.

Example 4
^^^^^^^^^^^^^

In the fourth and final example for :option:`freeform -calc` `conf`, the same input file is used
as in the second example, but now we would like to use the input charges in that file
for the solvation energies. Note that in addition to specifying `-solvcharges input`,
we also need to include `-ionic input` because the default behavior of potentially changing
the ionic state for pH 7.4 cannot be allowed with input charges. The command is thus:

.. code-block:: bash

   prompt> freeform -calc conf -solvcharges input -ionic input -track sitagliptin.mol2 \
   -in sitagliptin.mol2 -prefix sitagliptin.3D.inp.pfn

The results report is in the file sitagliptin.3D.inp.pfn.pdf.

.. _figure_sitagliptin.3D.inp.pfn.pdf:

.. figure:: /_images/sitagliptin3D.pb.png
   :width: 800px
   :align: center
   :alt: Results report from sitagliptin.3D.inp.pfn

   **Figure 4.** The results report using "-solvcharges input``.

Given that only the atomic partial charges differ between this example
and Example 2, we see significant changes in all the energies, yielding quite
a different profile for the
conformational ensemble. This includes changes to the conformer free energy and 
global strain energy values for the nearest unbound minimum to TrConf0.
These differences reflect the impact of using different charge models,
especially on charged ligands; we recommend the default AM1BCC ELF10 charges.

Solvation Free Energies
--------------------------------------------------------------------------------

Example 5
^^^^^^^^^^^^^

In order to estimate solvation free energy, the user must use the option :option:`-calc`
followed by the value ``solv``. The default charge state of the input compound corresponds
to pH = 7.4 (see option :option:`-ionic`), so the following run:

.. code-block:: bash

   prompt> freeform -calc solv -prefix januvia_ph74 januvia.smi

will estimate the Januvia solvation free energy at physiological pH. The graphical output file
for this run is displayed in Figure 5.
On the left the result of the solvation free energy calculation is shown,
including a depiction of the group-wise decompositions of the solvation free energy.
It suggests that, as expected, the cationic :math:`NH_3` group is responsible for
almost all of the strongly negative solvation free energy of this molecule (-53.6 kcal/mol), 
while the trifluorophenyl fragment is the most hydrophobic part of this drug, 
adding to the solvation free energy (2.4 kcal/mol).
To the right, the calculated XlogP partition coefficient is given together with
its fragment decomposition into group contributions.
Note that the calculated XlogP partition coefficient is
always done relative to the uncharged molecule
irrespective of its ionic state in water at any pH.

.. _figure_januvia_solv1:

.. figure:: /_images/januvia_solv1.png
   :width: 600px
   :align: center

   **Figure 5.** Solvation of Januvia at physiological pH.

Example 6
^^^^^^^^^^^^^

In the next example, the solvation free energy of Januvia in its uncharged
form is performed with:

.. code-block:: bash

   prompt> freeform -calc solv -ionic uncharged -prefix januvia_neu januvia.smi

The output is shown in Figure 6.
Note that changing the ionic state of the ligand only affects the solvation
free energy on the left-hand side; the calculated XlogP partition coefficient is
always done relative to the uncharged molecule so it is unchanged from the previous
example. Now since the solvation free energy is also on the uncharged form,
in this example (unlike the last), the solvation free energy and XlogP
calculations correspond to the same (uncharged) form of Januvia.
 
.. _figure_januvia_solv2:

.. figure:: /_images/januvia_solv2.png
   :width: 600px
   :align: center

   **Figure 6.** Solvation of the neutral form of Januvia.




.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _freeform_help:

.. program:: freeform

====================
Command Line Help
====================

A description of the command line interface can be obtained by executing **Freeform**
with the `--help` option.

.. code-block:: console
   
   > freeform --help

will generate the following output:

::

   Help functions:
     freeform --help simple      : Get a list of simple parameters
     freeform --help all         : Get a complete list of parameters
     freeform --help defaults    : List the defaults for all parameters
     freeform --help <parameter> : Get detailed help on a parameter
     freeform --help html        : Create an html help file for this program
     freeform --help versions    : List the toolkits and versions used in the application



.. _freeform_req_params:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: freeform

======================
Required Parameters
======================

.. option:: -calc <run_type>

   Selects type of calculations to be performed. There are two possible strings for
   parameter ``run_type``: ``conf`` and ``solv``. The first one asks *freeform* for the
   evaluation of conformational free energies while the second one tells *freeform* that
   solvation free energy is to be calculated.  The default flag value is set at ``conf``.

.. option:: -in <filename>

   Molecular input file name in any format supported by the OpenEye **OMEGA** Application.
   Warning: The file name ``freeform.oeb`` is used as the default output file name,
   so it should be avoided as an input file name.

.. option:: -i <filename>

   An alias to :option:`-in`.



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _freeform_opt_params:

.. program:: freeform

======================
Optional Parameters
======================

Basic Options
^^^^^^^^^^^^^^^^^

.. option:: -out <filename>

   Molecular output file name in any format supported by **OEChem**. The default name is
   ``freeform.oeb``. For free energy estimation of the conformations for the input
   molecule, the output file contains all unique solution conformations structures 
   identified by *freeform*. In the case of solvation free energy estimation, the output
   file contains the lowest energy vacuum conformation for which the PB solvation 
   calculation was actually done.

.. option:: -param <filename>

   Command line options will be read from the specified file. This file may have been
   generated from a previous run or may be constructed de novo. The default name of the
   file is ``freeform.param``. Any parameter in the parameter setup file is superseded
   by the parameter on the command line.

.. option:: -prefix <p>

   Replaces ``freeform`` prefix in .log,  .param, .oeb and .pdf output files with the
   input string ``p``.

.. option:: -report <filename>

   Name of the graphical output file. Currently only PDF and PS formats are allowed.
   The default name is ``freeform.pdf``.

.. option:: -track <filename>

   The molecular input of conformers to be tracked is read from the file name;
   any 3D molecule file format supported by OpenEye is acceptable.
   Of critical importance is that the molecule graph be identical to that specified
   in the :option:`-in` input file, and that atom and bond ordering also be identical.
   For the most common uses of *freeform*, the same input file is specified for
   both the :option:`-in` and :option:`-track` options.

Advanced Options
^^^^^^^^^^^^^^^^^

.. option:: -ensemble

   The ensemble of conformations is read from the :option:`-in` input file instead of being generated
   internally. In both cases of :option:`-calc` option, this ensemble is treated as if
   it already contains all the conformations needed.  In conformer free energy estimation,
   when used together with :option:`-track`, the tracked conformations are included with
   the ensemble.

.. option:: -ewindow

   The `-ewindow` flag sets the energy window (in kcal/mol) used as an energy cutoff in
   the initial conformation generation stage of *freeform*.
   An ewindow of at least 15.0 is encouraged to better cover accessible conformational
   space; increasing `-ewindow` will increase the number of conformers.
   [Default=15.0]

.. option:: -ff <type>

   This option specifies which force field to use in the energy minimizations and
   thermodynamics calculations following the initial conformer search. Choices include
   ``mmff94s``, ``mmff94``, ``smirnoff99frosst``, ``parsley_openff``, and ``sage_openff``.
   Default: ``sage_openff``.

   In addition to the above, this command accepts any SMIRNOFF force field parameter file.

.. option:: -ionic <type>

   By default, a charge state used in calculations corresponds to pH = 7.4 (the value of
   parameter ``type`` is set at ``pH74``). Two remaining values are ``uncharged`` and
   ``input``. The former corresponds to an uncharged ionic state (i.e., no formal charges);
   the latter to the preexisting ionic state determined from the molecule input file.

.. option:: -maxconfs <value>

   The `-maxconfs` flag sets the maximum number of conformations to be generated
   using **OMEGA** for the initial conformation generation stage of *freeform*.
   A large set is desirable to cover the
   conformational space necessary to include all reasonable conformers that might
   contribute to the partition function. When this initial set is minimized, a large
   reduction is expected in the number of unique minima.
   [Default=40000]

.. option:: -rms <value>

   RMS threshold for conformation generation using **OMEGA**. The default value is
   ``calculationDependent`` meaning that the RMS threshold used depends on whether
   "-calc conf" or "-calc solv" is being run. 0.3 |A| is used with
   "-calc conf" and 0.6 |A| with "-calc solv".
   Values ranging from 0 to 5 are accepted.

.. option:: -solvent <type>

   By default, Sheffield solvation is used with dielectric 80.0 to account for aqueous
   solvation of the unbound ensemble; this can be specifically requested by setting
   the parameter ``type`` to ``sheffield``. 
   Setting ``type`` to ``PB`` will result in Poisson-Boltzmann (PB)
   single-point solvation energies being calculated at the Sheffield-based minima.
   The default solvent dielectric for the PB calculation is 80.0, but this can be
   changed with the :option:`-PBsolvent_dielectric` option.
   Setting ``type`` to ``vacuum`` means that no solvation energy will be calculated.

.. option:: -PBsolvent_dielectric <value>

   This option allows the user to change the solvent dielectric used in the PB
   single-point solvation energies requested with :option:`-solvent` ``PB``.
   The default value is 80.0 to approximate aqueous solvation; it can adopt any
   value between 1.0 and 80.0 .

.. option:: -solvcharges <type>

   Selects the type of partial charges to be used for the solvent forces.
   By default, the value of ``type`` is ``calculationDependent``, meaning that the charge type
   used depends on whether "-calc conf" or "-calc solv" is being run. AM1BCC charges that are 
   AM1-optimized (Opt) (constrained to starting geometry) and symmetric by 2D-bond symmetry 
   (Sym) are used for conformer free energy estimation and nonsymmetric (NoSym) AM1-single-point
   (SPt) for solvation free energy calculations. For net-charged species however, MMFF94 charges are
   used for the conformer free energy estimation, even if the flag value selected is different
   than ``mmff94``. The defaults are different because the science behind the solvation free 
   energy calculation [Nicholls-2010]_ was specifically developed using the "NoSymSPt"
   variant of AM1BCC charges, whereas the conformer free energies require the robustness of the
   canonical AM1BCC charging scheme (symmetric charges from a constrained AM1 optimization) 
   towards large changes in conformation over the course of geometry optimization.
   In addition to the default ``calculationDependent``, the other possible values
   of the parameter ``type`` are ``am1bccSymOpt``,
   ``am1bccNoSymOpt``, ``am1bccSymSPt``, ``am1bccNoSymSPt``, ``mmff94``, and ``input``.
   The first four refer to different variants of the AM1BCC charging scheme; the next applies
   MMFF94 charges and the last is used to specify user-defined charges (which are read in from the 
   input structure). If ``input`` is selected, then the value of "-ionic" is automatically
   set to ``input``.


*********************************
Theory
*********************************

.. toctree::
   :maxdepth: 3

   szybki_theory
   aromatic_rings
   freeform_theory



.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_szybkitheory:

********************************************************************************
SZYBKI Theory
********************************************************************************

.. _section_forcefield:

MMFF94 Force Field
================================================================================

The MMFF potential expression is

.. math::

   V_{MMFF} = \sum_{b}V_{b} + \sum_{a}V_{a} + \sum_{s}V_{s} + \sum_{o}V_{o} + \sum_{t}V_{t} + \sum_{v}V_{v} + \sum_{c}V_{c},

where the seven terms describe bond stretching (`b`),
angle bending (`a`), stretch-bending (`s`), out-of-plane bending
(`o`), torsion (`t`), van der Waals (`v`) and electrostatic (`c`)
interactions. Their functional forms are given below.

Bond Stretching
--------------------------------------------------------------------------------

For a bond `b` between atoms `i` and `j`, the stretching potential is

.. math::

   V_b = 143.9325 \frac{k_{ij}}{2} \Delta r_{ij}^2(1 + c_s \Delta r_{ij} + 7/12{c_s}^2 \Delta r_{ij}^2),

where :math:`k_{ij}` is the force constant,
:math:`\Delta r_{ij}` is the difference between the actual and reference
bond lengths, and :math:`c_s` is a so-called "cubic-stretch" constant
for which the value is -2 |A|:math:`^{-1}`.

Angle Bending
--------------------------------------------------------------------------------

The bending potential of a bond angle `a` made by the bonds between the
atoms `i` and `j` and the atoms `j` and `k` is given by

.. math::

   V_a = 0.043844\frac{k_{ijk}}{2} \Delta \vartheta_{ijk}^{2}(1+c_b \Delta \vartheta_{ijk}),

where :math:`k_{ijk}` is the force constant, :math:`\Delta
\vartheta_{ijk}` is the difference between the actual and reference bond
angles, and :math:`c_b` is the so-called "cubic-bend" constant for which
the value is :math:`-0.4 rad^{-1}`.

Stretch-Bend Interaction
----------------------------------------------------------------------------------

The coupling between the stretching potential of two bonds forming a
bond angle and bending that angle is described by

.. math::

   V_s = 2.5121(k_{ijk} \Delta r_{ij} + k_{kji} \Delta r_{kj})\Delta \vartheta_{ijk},

where :math:`k_{ijk}` and :math:`k_{kji}` are force constants which
couple stretches of `i-j` and `k-j` to the `i-j-k` bend
respectively. :math:`\Delta r` and :math:`\Delta \vartheta` are defined above.

Out-of-Plane Bending
---------------------------------------------------------------------------------

For a trigonal center `j`, the potential of displacement for an atom
`l` bonded to atom `j` out of plane `i-j-k` is

.. math::

   V_o = 0.043844\frac{k_{ijkl}}{2} \chi_{ijkl}^2

where :math:`k_{ijkl}` is the force constant and :math:`\chi_{ijkl}` is an
angle formed by the bond `j-l` and the plane `i-j-k`.

Torsion Interactions
--------------------------------------------------------------------------------

For every four bonded atoms `i-j-k-l`, the torsion interaction is
described by the term

.. math::

   V_t = 0.5(V_1(1 + \cos\Phi) + V_2(1 - \cos2\Phi) +V_3(1+ \cos3\Phi),

where :math:`V_1`, :math:`V_2` and :math:`V_3` are constants depending on atoms `i`,
`j`, `k`, and `l`, and :math:`\Phi` is the dihedral angle formed by bonds
`i-j` and `k-l`.

.. _sub-section_VdW:

Van der Waals Interactions
-------------------------------------------------------------------------------

For a pair of atoms `i` and `j` separated by three or more bonds,
where the distance between them is :math:`r_{ij}`, MMFF adopts the
following van der Waals potential

.. math::

   V_v = \epsilon_{ij} \left(\frac{1.07R_{ij}}{r_{ij}+0.07R_{ij}} \right) ^7 \left( \frac{1.12R_{ij}^7}{r_{ij}^7+0.12R_{ij}} -2 \right),

where :math:`R_{ij}` and :math:`\epsilon_{ij}` are defined as follows:

.. math::

   R_{i} = A_i\alpha_i^{0.25}

.. math::

   R_{ij} = 0.5(R_i + R_j)(1+B(1-\exp(-12\gamma_{ij}^2)))

.. math::

   \gamma_{ij} = (R_i - R_j)/(R_i + R_j)

.. math::

   \epsilon_{ij} = \frac{181.16G_iG_j \alpha_i \alpha_j}{(\alpha_i/N_i)^{0.5} + (\alpha_j/N_j)^{0.5}} \frac{1}{R_{ij}^6}

where :math:`\alpha_i` is the atomic polarizability of atom `i`, `B` is 0.2 or
0.0 if one of the atoms is polar hydrogen, :math:`N_i` and :math:`N_j` are the
Slater-Kirkwood effective numbers of valence electrons, and :math:`G_i`, :math:`G_j`
and :math:`A_i` are scale factors.

.. _sub-section_electrostatic:

Electrostatic Interactions
-----------------------------------------------------------------------------

The electrostatic interaction between two charged atoms `i` and `j`
separated by at least three bonds is calculated from the standard
Coulombic expression

.. math::

   V_c = f\frac{332.0716q_iq_j}{D(r_{ij} + \delta)}

where `D` is the dielectric constant for which the default value is 1,
:math:`q_i` and :math:`q_j` are the MMFF partial charges on atoms `i` and `j`,
:math:`r_{ij}` is the interatomic distance, and :math:`\delta` is the "electrostatic
buffering" constant of 0.05 |A|. The scaling factor `f` is 0.75 for 1,4
interactions and 1.0 otherwise.

.. _sub-section_MMFF-AMBER:

Protein-Ligand Amber Potential
-----------------------------------------------------------------------------

Protein-ligand interactions can be described by the Amber force field instead
of MMFF potential,

.. math::

   V_{Amber} = \sum_{i,j} \left\{ \epsilon_{ij}\left[\left(\frac{R_{ij}}{r_{ij}}\right)^{12}
               -2\left(\frac{R_{ij}}{r_{ij}}\right)^6\right] +
               \frac{q_iq_j}{4\pi\epsilon_0r_{ij}}\right\},

where the summation is over protein-ligand atom pairs. :math:`r_{ij}` is the interatomic distance,
:math:`R_{ij}` is the VdW distance for a pair of atoms, :math:`q_i` and :math:`q_j` are the Amber
partial charges on atoms `i` and `j`, and :math:`\epsilon_0` is the vacuum permittivity.
VdW parameters :math:`R_{ij}` and :math:`\epsilon_{ij}` and partial charges are taken from work by Wang and coworkers
[Wang-J-2000]_.

.. _section_smirnoff:

SMIRNOFF99Frosst and OPENFF
================================================================================

SMIRNOFF (SMIRKS Natural Open Force Field) is a kind of small molecule force field
springing from the `Open Force Field Initiative (OFF Initiative or OFFI) <https://openforcefield.org/>`_. The key feature
of this force field is its chemical
representation of parameters by using extended SMARTS patterns. "Extended"
here means that the :term:`SMARTS` patterns also use atom assignment syntax from :term:`SMIRKS`. For example,
``[*:2]~[*:1]~[#1]`` specifies three atoms, where the first is assigned to be atom 2,
the second atom is assigned to be atom 1, and the third atom is not assigned. This format
frees the force field from using atom types; instead it uses the direct chemical perception
of the extended SMARTS patterns [Mobley-2018]_.
Compared to traditional atom typing approaches, this representation greatly reduces the
number of parameters needed to specify a general small molecule force field and makes
each parameter more independent.

While it currently has a traditional "Amber" type functional form as specified below,
future versions expect to modify the functional form. The OPENFF Initiative release
periodic revisions of the parameters which include changes to the chemical
specifications (i.e., the extended SMARTS patterns) as well as the numerical parameters.
The revision used by the API points will be given with the results.

SMIRNOFF99Frosst OPENFF1.0.0 (released in October 2019) force fields have six terms

.. math::

   V_{SMIRNOFF} = \sum_{b}V_{b} + \sum_{a}V_{a} + \sum_{o}V_{o} + \sum_{t}V_{t} + \sum_{v}V_{v} + \sum_{c}V_{c}

describing bond stretching (`b`), angle bending (`a`),
out-of-plane displacement (`o`), torsion (`t`), van der Waals (`v`), and electrostatic (`c`)
interactions. Their functional forms are similar to those in the AMBER force field and are given below.

Bond Stretching
--------------------------------------------------------------------------------

For `a` bond `b` the stretching potential has a simple harmonic form:

.. math::

   V_b = k_b(r - r_0)^2

where :math:`k_b` is the force constant and :math:`r`, and :math:`r_0` are the actual and
reference bond lengths, respectively.

Angle Bending
--------------------------------------------------------------------------------

For bond angle `a`, the angle bending potential form is

.. math::

   V_a = k_a(\alpha - \alpha_0)^2

where :math:`k_a` is the force constant and :math:`\alpha`, and :math:`\alpha_0` are the actual and
reference bond angle values, respectively.

Torsion Interactions
--------------------------------------------------------------------------------

Every four bonded atoms defines a torsion whose energy is represented with one to six
terms of a Fourier series

.. math::

   V_t = \sum_n{V_n/d_n(1+\cos{(p_n\theta - \gamma_n)})},

where :math:`V_n`, :math:`d_n`, :math:`p_n`, and :math:`\gamma_n` are the barrier height, degeneracy,
periodicity and phase, respectively, for the `n` component of a torsion whose dihedral angle is :math:`\theta`.

Out-of-Plane Bending
---------------------------------------------------------------------------------

It is defined as the potential of a displacement of the trigonal center atom `a` bonded to three other
out-of-plane atoms, `b`, `c`, and `d`.
Its functional form is similar to a regular torsion with a single term. Sometimes it is also called
an `improper torsion`:

.. math::

   V_o = V_n(1+\cos{(p_n\theta - \gamma_n)}).

Since one can define three improper torsions of moving a trigonal atom `a` out of a plane defined by
atoms `b`, `c`, and `d`, the energy of such a displacement is calculated as one third of the sum of
those torsions.

Van der Waals Interactions
-------------------------------------------------------------------------------

For a pair of nonbonded atoms `i` and `j`, a SMIRNOFF force field adopts Lennard-Jones
potential

.. math::

   V_v = \epsilon_{ij}\left[\left(\frac{R_{ij}}{r_{ij}}\right)^{12}
               -2\left(\frac{R_{ij}}{r_{ij}}\right)^6\right],

where :math:`\epsilon_{ij}` is well depth and :math:`R_{ij}` and :math:`r_{ij}` are the
equilibrium and actual distance between atoms `i` and `j`, respectively.

Electrostatic Interactions
------------------------------------------------------------------------------

A simple coulomb term

.. math::

   V_c = \frac{q_iq_j}{4\pi\epsilon_0r_{ij}}

represents coulomb interactions, where :math:`q_i` and :math:`q_j` are partial atomic charges,
:math:`\epsilon_0` is the vacuum permittivity, and :math:`r_{ij}` is the distance between atoms
`i` and `j`.

Entropy Evaluation
================================================================================

Ligand entropy is evaluated as a sum of configurational entropy (:math:`S_c`) and
solvation entropy (:math:`\Delta S_s`):

.. math::

   S = S_c + \Delta S_s

Configurational Entropy
--------------------------------------------------------------------------------
Configurational entropy is calculated as

.. math::

   S_c = kN \Bigg[ 1 + \ln \Bigg(\frac{q}{N} \Bigg) + \frac{T}{q} \frac{\partial q}{\partial T} \Bigg],

where q is the conformation dependent partition function:

.. math::

   q = q_t \sum_{i=1}^{n_c} e^{-\frac{\epsilon_i}{kT}} q_{iv} q_{ir}.

Here :math:`q_t`, :math:`q_ir`, and :math:`q_iv` are the translational, rotational, and vibrational
partition functions, respectively, and :math:`n_c` is the number of unique conformations in the ensemble.
All three partition functions are calculated from the classical statistical mechanics expressions
which could be found in *Statistical Mechanics* by Donald McQuarrie (\ [McQuarrie-1976]_\). Vibrational frequencies for each
conformation, needed for evaluation of :math:`q_{ir}` are derived from diagonalization of a
Hessian matrix obtained from quasi-Newton optimization when convergence is achieved. Eigenvalues
:math:`\lambda_i` of the mass-weighted Hessian

.. math::

   \mathbf{H}^{m} = \mathbf{M^{-1/2}HM^{-1/2}}

are converted into wave numbers :math:`\tilde{\nu}_i` according to

.. math::

   \tilde{\nu}_i = \frac{1}{2\pi c} \sqrt{\lambda_i}.

Solvation Entropy
--------------------------------------------------------------------------------
Solvation entropy is split into electrostatic and hydrophobic parts:

.. math::

   \Delta S_s = \Delta S_{s,elec} + \Delta S_{s,hyd}

The electrostatic part of solvation entropy is divided into the bulk component and tight electrostatic
polar solute-water interactions (hydrogen bonds). The bulk contribution is estimated from the temperature
dependence of the solvent dielectric constant as

.. math::

   \Delta S_{s,elec\_bulk} = -\bigg(\frac{\partial \Delta G_s}{\partial \epsilon_{solv}}\bigg) \bigg(\frac{\partial \epsilon_{solv}}{\partial T}\bigg).

The second term of the electrostatic solvation entropy is estimated as a constant of 28 J/(mol K).

The hydrophobic term, :math:`\Delta S_{s,hyd}`, is evaluated as

.. math::

   \Delta S_{s,hyd} = -\bigg(\frac{\partial \Delta G_{s,hyd}}{\partial T}\bigg),

where :math:`\Delta G_{s,hyd}` consists of three components

.. math::

   \Delta G_{s,hyd} = \Delta G_{cav} + \Delta G_{VdW} + \Delta G_{Ind},

describing the free energy of cavitation, solute-solvent van der Waals, and inductive terms, respectively.
The cavity formation term is calculated from Scaled Particle Theory [Pierotti-1976]_.
Analytical expressions for :math:`\Delta G_{VdW}` and :math:`\Delta G_{Ind}` terms are also taken from
the 1976 Pierotti review.

Protein-Bound Ligand Entropy
--------------------------------------------------------------------------------
The configurational entropy of a protein-bound ligand is calculated totally as vibrational entropy
for 3N modes, assuming that three rotational and three translational degrees of freedom of a solution
ligand are transformed into low vibrational degrees of freedom for the bound ligand.

Solvation entropy for a ligand in the active site is assumed to be a sum of its fractional value
in solution determined by the percentage of the ligand surface exposed to the solvent, :math:`f\Delta S_s`,
and a partial desolvation entropy of the protein active site, :math:`\Delta S_{des}`,

.. math::
   S_{protein} = S_v + f\Delta S_s + \Delta S_{des},

where f is the fraction of ligand surface exposed to the solvent. It is important to notice that
:math:`S_{protein}` is not an experimentally measurable value, and that only the difference between
:math:`S_{protein}` and :math:`S = S_c + \Delta S_s` might be compared with experimental binding
entropy.




.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*



.. _chapter_aromatic_rings:

********************************************************************************
Nonplanar Aromatic Rings in Protein-Bound Ligands
********************************************************************************

Optimization of a ligand in a protein active site, especially if the protein conformation
is held fixed during optimization, can often lead to distortions of the aromatic ring structures.
Aromatic rings in optimized ligands are more prone to distortions when the initial pose structures
are the output of docking, since tools such as **OEDocking** or **POSIT** try to accommodate a
ligand into a rigid receptor pocket. Optimization of a ligand in the protein pocket helps relieve
both intramolecular close contacts within the ligand and intermolecular clashes between
the ligand and the protein.  However, such relaxation of the van der Waals clashes can
sometimes come at the expense of nonplanarity in the aromatic ring structures.

Ligand force fields used in optimization, such as ``Sage``, ``Parsley``, and ``MMFF``, put a
low energy constant in defining the out-of-plane potential of aromatic rings.  The low energy
penalty for aromatic rings to deviate from planarity in the force fields is also supported by quantum mechanical
calculations which estimate only a 0.5 kcal/mol penalty for ~5 degrees of deviation for a benzene
ring. The out-of-plane potential being the lowest vibrational motion during optimization means it
can easily be bent by a few degrees during optimization.


﻿.. include:: ../substitutions
.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _chapter_freeformTheory:

********************************************************************************
Freeform Theory
********************************************************************************

*freeform* has two distinct functions:

"freeform -calc conf...": Evaluation of the conformer free energy in solution,
meaning the free energy required to select a particular conformer out of the whole
conformational ensemble in solution.

"freeform -calc solv...": Fast estimation of the small molecule solvation free energy
and the XlogP calculated partition coefficient
(with graphical representation of fragment-based contributions to these physical
quantities).

.. _section_conformerDG:

Conformer Free Energies
================================================================================ 

Calculating the Partition Function
------------------------------------
The method is based upon combining ligand conformational search, energy minimization,
and entropy estimation in the workflow shown in Figure 1 below.

.. _figure_confstages:

.. figure:: /_images/FreeformConfWorkflow.png
   :width: 600px
   :align: center
   :alt: Stages and workflow in the conformer free energy calculation

   **Figure 1.** Stages and workflow in the conformer free energy calculation.

The conformational search is done at a very high resolution
using the conformation generator **OMEGA** [Hawkins-2010]_.
The energy minimization uses Halgren's MMFF94s force field [Halgren-VI-1999]_ and
consists of several stages, all aimed at arriving at the most thorough sampling of the
accessible conformational space of the ligand. Duplicate conformers are removed from
the final minimized set, leaving an ensemble of :math:`n_c` unique conformers,
referred to below as the *Ensemble of Unbound Minima*, which we use
to create an approximation to the partition function of the unbound ligand.
This is illustrated conceptually in Figure 2.

.. _figure_EntropyWells:

.. figure:: /_images/EntropyWells.png
   :width: 600px
   :align: center
   :alt: Concept of ligand entropy as a sum-over-states of conformers

   **Figure 2.** Concept of ligand entropy as a sum-over-states of conformer entropies.

To the molecule's gas phase potential based on the MMFF94 force field (shown by the red line),
Sheffield solvation energies are added to give a solvation-corrected potential
(shown by the blue line) for which the minima are identified.
The analytic second derivative of each minimum is then used to
calculate the entropy contribution of each energy well according to Wlodek and coworkers [Wlodek-2010]_.
An energy minimum with a wider than average energy well will have a higher entropy,
which will decrease the conformer free energy to select that conformer,
while the converse will be true for a narrower than average energy well.

With this, the contribution
:math:`Q_i` of each energy minimum to the overall partition function :math:`Q` can be calculated as

.. math::

   Q_i = q_t q_{ir} q_{iv} e^{-\epsilon_i /RT}

.. math::

   Q = \sum_{i=1}^{n_c} Q_i

Here :math:`\epsilon_i` is the relative internal energy (including solvation 
and zero-point energies)
of the conformer relative to the global minimum conformation.
:math:`q_t`, :math:`q_ir`, and :math:`q_iv` are the translational,
rotational, and vibrational partition functions, respectively, describing the
entropic contributions from that conformation.
:math:`n_c` is the number of unique conformations in the ensemble.
More details on these terms are given in the :ref:`SZYBKI theory section <chapter_szybkitheory>`.
In practice, we do not compute the translational partition function :math:`q_t`
because it is constant for all conformers, so it cancels out of the conformer
free energies.

Computing the Conformer Free Energies
---------------------------------------
Based upon this approximation of the partition function, we calculate conformer free
energies: the free energy required to select a particular conformation from the unbound
ensemble of all conformers equilibrating in aqueous solution. Strictly speaking,
this is a Helmholtz free energy, not a Gibb's free energy, because we are neglecting
the differential PV (pressure*volume) contribution between conformers, but this
should be negligible. Based on the above conformer and ensemble partition functions, the
conformer free energy for any conformer is calculated straightforwardly as:

.. math::

   \Delta A_i = -RT ( \ln Q_i - \ln Q ).

In addition to the graphic output file, which shows a plot of the calculated free energies of
conformations versus their relative internal and solvation energies, energetic and thermodynamic
results are stored in the log and CSV files.

Tracking Conformers
---------------------------------------

Often we are interested in one or more particular conformers, such as a
known or hypothetical bound conformer of a ligand (the "bioactive" conformer),
or perhaps a number of top-scoring poses from a docking run. One of **Freeform**'s
main purposes is to estimate the free energy cost of selecting such conformers
out of the unbound ensemble, a quantity we will refer to as the *Global Strain Energy*.
**Freeform** tracks these conformers using the :option:`freeform -track` flag,
followed by the filename containing the input conformers for which ligand
strain energies are desired. Note that this is distinct from the input file
specified with the :option:`-in` flag, which specifies the molecule from which
to construct the unbound ensemble. All conformers in the file specified after
the :option:`freeform -track` flag will be tracked by ``freeform``, and the user will
get a direct readout of the energy
required to select that particular conformation out of the aqueous ensemble.
Figure 3 shows how the various components of *Local and Global Strain Energies* are calculated.

.. _figure_TrackedConformers:

.. figure:: /_images/TrackedConformers.png
   :width: 800px
   :align: center
   :alt: The components of Local and Global Strain Energies

   **Figure 3.** The components of *Local and Global Strain Energies*.

A key issue is that the input 3D coordinates of the tracked conformer
may be of artificially high energy, usually due to small deviations of
bond lengths and bond angles from the force field's optimum values;
this is often true particularly of ligands from X-ray structures.
For this reason, the input structure is cleaned up with a restrained optimization
using strong harmonic restraints to the input coordinates.
The strong restraints retain the shape of the ligand
(usually to within 0.2 |A| RMSD) but resolve the artificially high energy.
The energy of this restrained minimum structure is used in calculating
the *Local Strain Energy* as shown in Figure 3 above.

Since conformer free energies must be calculated from energy
minima in order to characterize the entropy, an unconstrained minimization is
now required to find the *Nearest Unbound Minimum* to the input structure.
This minimization allows the torsions
in the input structure to relax away from where they may have been distorted from
the nearby local minimum in order to fit into the active site.
**Freeform** keeps track of this "distortion" strain energy as *Local Strain Energy*.
From this point, **Freeform** simply includes the *Nearest Unbound Minimum* as just
another energy minimum in the aqueous ensemble and calculates its conformer
free energy, which is specifically reported in the PDF and log output (see examples).
Thus, within **Freeform**, the *Global Strain Energy* for the
input 3D structure would be considered to consist of a)
the *Local Strain Energy* required to distort the
*Nearest Unbound Minimum*, so the ligand can adopt the
shape of the input tracked conformer, and b)
the conformer free energy required to select the *Nearest Unbound Minimum*
(i.e., the closest local minimum to the input structure)
from the entire *Ensemble of Unbound Minima*.

Solvation Energy Estimation
================================================================================ 

How It Is Calculated
----------------------
The term "solvation energy" is defined here as the standard free energy of transferring
a compound from the gaseous phase into dilute aqueous solution, :math:`\Delta G_{solv}^{0}`.

Solvation energy is a crucial component of the solubility energetics
and is directly related to hydrophilicity/hydrophobicity of a compound; therefore one can
expect it is correlated with another measure of hydrophobicity, logP, as illustrated in Figure 4 below.
Such a correlation, particularly when a functional group's contribution is
considered, might not exist. **Freeform** shows the graphical group
contributions to solvation free energy and XlogP.

.. _figure_solv_solu_hydro:

.. figure:: /_images/solvation-solubility.png
   :width: 600px
   :align: center

   **Figure 4.** Solvation, solubility, and hydrophobicity.
  
The method is based on the continuum solvent model in which a Poisson–Boltzmann (PB) solver ZAP
[Grant-2001]_ is used. The calculation is performed on the lowest energy gas-phase
conformation found with the MMFF94 force field from the optimized set of conformations
generated by the conformation generator **OMEGA** [Hawkins-2010]_.
A set of atomic radii ZAP9 and AM1BCC partial charges as described by Nicholls [Nicholls-2010]_
is applied for all PB calculations. Atomic and group contributions to the free energy of 
solvation for the input compound are calculated from atomic electrostatic potentials and 
atomic area terms representing the hydrophobic part of solvation. Assuming that a functional
group has :math:`n` atoms, its calculated solvation free energy :math:`\Delta G_s` is

.. math::

   \Delta G_s = \sum_{i}^{n}[(V_{i,s}-V_{i,v})q_i+S_i],

where :math:`V_{i,s}` and  :math:`V_{i,v}` are calculated electrostatic potentials
on atom :math:`i` in solution and in vacuum, respectively, :math:`q_i` is atom partial
charge, and :math:`S_i` is atomic contribution to hydrophobic part of solvation
evaluated from a simple surface area model assuming 6.3 cal/(mol |A|:math:`\AA`) as a value for the
microscopic surface tension coefficient. Graphical representation of group (or atomic) 
contributions to the free energy of solvation is performed with the OpenEye tools **OEDepict TK** and
**Grapheme™ TK**.

Counterintuitive group contributions to solvation energies 
----------------------------------------------------------
Solvation free energy for molecular ions might not be trivial to interpret
because of very strong intrinsic electrostatic interactions. One can most
easily begin to understand these effects by considering zwitterions.  A common
zwitterion will contain both a group with a positive formal charge and a group
with a negative formal charge.  It is well known that zwitterions, though still
having high solvation energies, have significantly smaller solvation energies
than compounds with two formal charges of the same sign.  In fact, zwitterion
solvation energies are typically smaller than the solvation energy of the
analog molecule with a single charge.  For instance, as the examples in Figure 5 show,
the solvation energy of zwitterionic phenylalanine is -35.4 kcal/mol, while the solvation energy 
of the formamide analog and the methyl ester analog are -74.9 and -64.6 kcal/mol, respectively.

.. _figure_phenylalanine:

.. figure:: /_images/phenylalanine.png
   :width: 900px
   :align: center

   **Figure 5.** Solvation energy of zwitterionic phenylalanine and two singly charged analogs.

One can consider, then, that adding a charge of the opposite sign
of the current molecular ion contributes a positive 30 to 40 kcal/mol
to the solvation energy.
A similar situation, perhaps even more dramatic, occurs in the case of intramolecular
salt bridges, where positively and negatively charged groups are positioned in 
a very short distance. That kind of interaction does not only exist in macromolecules:
NMR and hydrogen exchange rate experiments have also confirmed the presence of salt
bridges between arginine or lysine and aspartate or glutamate side chains
in short peptides ([Mayne-1998]_; [Otter-1989]_).
Making positive contributions to the solvation energy is generally considered a
hydrophobic effect, yet here the contribution is made by a charged species, which
is somewhat counterintuitive at first.  Nevertheless, in this
context, one can understand how, under the right conditions, a normally
hydrophilic functional group can make a significant positive contribution to
the solvation energy.
The more confusing circumstance is when, rather than a simple zwitterion, we
see a similar effect in a molecule with either multiple charges of one type
(either positive or negative) and a single charge of the opposite sign.
Consider a molecule with 2 negative ions, one positive ion and a total charge
of -1, like the one shown in Figure 6.

.. _figure_counterint:

.. figure:: /_images/counterintuitive1.png
   :width: 400px
   :align: center
   :alt: Example of counterintuitive group contributions to solvation

   **Figure 6.** Counterintuitive group contributions to solvation.

In this case, the positive ion will change the formal charge from
-2 to -1.  This will make the total solvation energy significantly less
negative (a positive contribution to the solvation energy).  The positive ionic
functional group in this case will have a large positive solvation energy.
While a charged group is indeed not hydrophobic, in this instance, one can
understand that it makes the solvation energy less negative in a manner similar 
to the way a hydrophobic group might, but to a larger degree.  
In more subtle cases, one can observe a similar though less dramatic hydrophobicity 
in a molecule with a single charge, either positive or negative, and another fragment
that makes a large neutralizing contribution to the partial charge of the
molecule.

In order to alert the user, species which contain strong intramolecular
electrostatic interactions of the nature described above are depicted on a
light pink background.  This should act as a reminder to users to consider the
net charge of the molecule in interpreting the relative contribution of each
fragment to the solvation energy.



*********************************
Utilities
*********************************

.. toctree::
   :maxdepth: 2

   OptLigandInDU
   OptimizeDU



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _OptLigandInDU:

******************
OptLigandInDU
******************

.. program:: OptLigandInDU

Overview
===================

:ref:`OptLigandInDU` is an application to optimize a ligand or a series of
ligands in a rigid protein active site. This is suitable for screening a
large amount of docked ligands into a protein receptor.

Example Commands
===================

Ligand Optimization in a Protein Active Site
------------------------------------------------------

This optimizes the ligands in a protein active site using the FF14SB-Parsley force field.

Input files

   * **1H1Q_AB_receptor.oedu**: OEDU file containing the protein active site
   * **1H1Q_AB_fred_docked.oeb**: OEB file containing the ligand to optimize

Command line

      .. code-block:: bash

         prompt> optligandindu 1H1Q_AB_receptor.oedu 1H1Q_AB_fred_docked.oeb 1H1Q_AB_fred_docked_opt.oeb

Output files

   * **1H1Q_AB_fred_docked_opt.oeb**: OEB file containing optimized ligands
   * **OptLigandInDU_rpt.csv**: CSV file containing optimization report

Report File
==============

The CSV report file contains the following fields. 

   * **Molecule**: SMILES representation of the ligand molecule.
   * **Title**: Title of the ligand molecule.
   * **ConfID**: Ligand conformer index.
   * **Inter Ene**: Final intermolecular energy between the protein target and the ligand (kcal/mol).
   * **Ligand Ene**: Final intramolecular energy of the ligand (kcal/mol).
   * **Ligand RMSD**: Root mean square deviation of the ligand between initial and final structures (Å).
   * **ElapsedTime(s)**: Elapsed time for the optimization process (seconds).
   * **Status**: Status of the optimization. (Reported only when the optimization fails. Otherwise, this field is empty.)

Optimize a Ligand Pose in a Rigid Protein
-------------------------------------------------------

This performs a constrained optimization of the ligand in the rigid protein
active site, using the FF14SB-Parsley force field.

Input files

   * **1H1Q_AB_receptor.oedu**: OEDU file containing the protein active site
   * **1H1Q_AB_fred_docked.oeb**: OEB file containing the ligand to optimize

Command line

      .. code-block:: bash

         prompt> optligandindu -du 2IKO.oedu -in 1H1Q_AB_fred_docked.oeb -out 1H1Q_AB_fred_docked_opt.oeb -optimize poseCartesian

Output files

   * **1H1Q_AB_fred_docked_opt.oeb**: OEB file containing optimized ligand

Command Line Help
===================

A description of the command line interface can be obtained by executing **OptLigandInDU**
with the `--help` option.

.. code-block:: console

   > optligandindu --help

will generate the following output:

::

   Help functions:
     optligandindu --help simple      : Get a list of simple parameters
     optligandindu --help all         : Get a complete list of parameters
     optligandindu --help defaults    : List the defaults for all parameters
     optligandindu --help <parameter> : Get detailed help on a parameter
     optligandindu --help html        : Create an html help file for this program
     optligandindu --help versions    : List the toolkits and versions used in the application

Required Parameters
===================

.. option:: -du <filename>

   An OEDU file with a design unit, containing the protein active site.  If the file contains multiple
   design units, only the first one is used.

   [keyless parameter 1]

.. option:: -in <filename>

   Molecular input file name containing 3D coordinates in any format
   supported by **OEChem**.

   [keyless parameter 1]

Acceptable molecule file formats are listed below.

.. list-table:: *SZYBKI File Format Support*
   :widths: 20 25
   :header-rows: 1

   * - File extension
     - Description
   * - mol
     - MDL Mol File
   * - mmd, mmod
     - Macromodel
   * - mol2
     - Tripos Sybyl mol2 file
   * - oeb
     - New Style OEBinary
   * - sd, sdf
     - MDL SD File
   * - xyz
     - XMol XYZ format

Optional Parameters
===================

File Options
==================

.. option:: -log

   The argument for this flag specifies the name of
   the log file.  The level of detail for logfile information can be
   altered using the :option:`-verbose` flag.  Generation of an
   output log may be disabled by providing ``nul`` as a argument in Windows and ``/dev/null`` as an
   argument on Linux and macOS.  
   [default = ``prefix`` _log.txt]

.. option:: -prefix

   The argument for this flag defines the prefix to be used
   for various information and data files generated.  Most
   important among these is the '*prefix_parm.txt*' file which includes a
   copy of all the parameters used in the run.  The prefix is
   also used to generate a default log file name if not explicitly
   specified with the *-log* flag. 
   [default = <app_name>].

.. option:: -verbose

   This is a boolean flag that controls the level of
   detail written to the log file.  By default only
   minimal information is written to the log file. 
   Verbose logging will cause more information to be written to the log
   file in order to follow behavior during program execution.  
   [default = false]

.. option:: -molNames

   This parameter takes a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set then only molecules in the
   input file(s) (see parameter :option:`-in`) with names that match those
   in the text files will be read in.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecule(s) that are contained in a large file, without
   having to extract those molecules by hand from the input molecules file.
   [default = NONE].

.. option:: -progress

   Show progress on screen.  Options are 'none', 'dots', 'log' and 'percent'.
   The 'dots' options will displays dots on screen to show molecules
   completed.  The 'log' option will duplicate the log file on screen.
   The 'percent' option will track progress through the input file.  
   [default = none]


Input Options
--------------

.. option:: -proteinMask

   Design unit components mask defining the subset of design unit components to
   be used as ``protein`` during optimization. Multiple components can also be combined as
   a comma-separated string to create the input.

   Possible values include cofactors, counter_ions, excipients, lipids, metals, nucleic, other_cofactors,
   other_ligands, other_nucleics, other_proteins, packing_residues, polymers,
   post_translational, protein, solvent, and sugars.

   Predefined multicomponent values:

   * **targetComplex** =
     protein,nucleic,cofactors,solvent,metals,counter_ions,lipids,other_proteins,
     other_nucleics,other_ligands,other_cofactors.
   * **targetComplexNoSolvent** = protein,nucleic,cofactors,metals,lipids,other_proteins,
     other_nucleics,other_ligands,other_cofactors.
   * **macroMolComponents** = protein,nucleic,other_proteins,other_nucleics.

     [Default=targetComplex]

.. option:: -receptorMask    [Default=True]

   Flag indicating if the ``Design unit components mask`` defining the subset of design 
   unit components to be used as the ``protein`` during optimization should be picked up based
   on the mask defined in the receptor. If the input ``Design Unit`` does not contain
   a receptor, the optimizer automatically falls back to using the ``-proteinMask``.

.. option:: -ignoreAroBent    [Default=False]

   Flag indicating if optimization should not fail due to excess deviation from
   planarity for aromatic rings in optimized ligands.  By default, optimization would fail
   if aromatic rings deviate from planarity in an optimized ligand by more than five degrees
   on average, or if certain torsion exceeds a maximum of 10 degrees.

Output Options
---------------------------

.. option:: -out <filename>

   Output file name, in any format supported by OEChem, for an
   optimized ligand.

   [keyless parameter 2]

Optimization Options
---------------------------

.. option:: -optimize    [Default=poseCartesian]

   Optimization type.
   Choices: [0] cartesian: performs a full cartesian optimization, or [1] poseCartesian: performs
   a constrained cartesian optimization, ensuring to hold the ligand pose.

.. option:: -ff    [Default=ff14sb_sage]

   The force field to use for optimization.  A predefined force field can be used by
   choosing one from the list of choices.  A different SMIRNOFF/OpenFF formatted
   small molecule force field can be used with ff14SB by passing in the
   small molecule force field OFFXML file as the argument.
   Choices: ``mmff94``, ``mmff94s``, ``mmff_amber``, ``mmffs_amber``, ``ff14sb_parsley``, and ``ff14sb_sage``.

.. option:: -ligandCharge    [Default=current]

   Charges to be assigned for the ligand. The default value of ``current`` refers to
   using the existing charges on the ligand.
   Choices: [0] current, [1] am1bcc [2], am1bccelf10, or [3] MMFF.

.. option:: -gradTol    [Default=1.0e-6]

   Root mean squared (RMS) gradient tolerance for convergence and termination of optimization.

.. option:: -maxIter    [Default=1000]

   Maximum number of iterations for termination of optimization.  Optimization is terminated
   if either the gradient tolerance ``gradTol`` or the maximum iterations limit, whichever
   occurs first, is reached.

.. option:: -solventModel    [Default=vacuum]

   Solvent model to be used during optimization.
   Choices: [0] vacuum, [1] sheffield, or [2] pb.




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. _OptimizeDU:

******************
OptimizeDU
******************

.. program:: OptimizeDU

Overview
===================

:ref:`OptimizeDU` is an application to optimize a protein-ligand complex
inside a design unit. This is suitable for lead optimization, where a complete 
optimization which includes solvent forces and possibly partial relaxation of 
the protein residues in the direct proximity to the ligand desired.

Example Commands
===================

Protein-Ligand Optimization in a Design Unit
------------------------------------------------------

This optimizes the protein-ligand complex in the design unit using the FF14SB-Parsley force field.
Complete protein residues within 2 angstroms from the ligand are considered flexible
by default.

Input files

   * **1H1Q_AB_receptor.oedu**: OEDU file to optimize protein-ligand complex

Command line

      .. code-block:: bash

         prompt> optimizedu 1H1Q_AB_receptor.oedu 1H1Q_AB_opt.oedu

Output files

   * **1H1Q_AB_opt.oedu**: OEDU file containing optimized protein-ligand complex
   * **OptimizeDU_rpt.csv**: CSV file containing optimization report

Report File
==============

The CSV report file contains the following fields. 

   * **Molecule**: SMILES representation of the ligand molecule.
   * **Title**: Title of the ligand molecule.
   * **Inter Ene**: Final intermolecular energy between the protein target and the ligand (kcal/mol).
   * **Ligand Ene**: Final intramolecular energy of the ligand (kcal/mol).
   * **Protein Ene**: Final intramolecular energy of the flexible part of the protein target (kcal/mol).
   * **Ligand RMSD**: Root mean square deviation of the ligand between initial and final structures (Å).
   * **Protein RMSD**: Root mean square deviation of the protein target between initial and final structures (Å).
   * **ElapsedTime(s)**: Elapsed time for the optimization process (seconds).
   * **Status**: Status of the optimization. (Reported only when the optimization fails. Otherwise, this field is empty.)

Optimize a Ligand Pose in a Partially Flexible Protein
-------------------------------------------------------

This performs a constrained optimization of the ligand in the partially flexible protein
active site, using the FF14SB-Parsley force field. Complete protein residues within 2 angstroms
from the ligand are considered flexible by default.

Input files

   * **1H1Q_AB_receptor.oedu**: OEDU file to optimize protein-ligand complex

Command line

      .. code-block:: bash

         prompt> optimizedu -in 1H1Q_AB_receptor.oedu -out 1H1Q_AB_opt.oedu -optimize poseCartesian

Output files

   * **1H1Q_AB_opt.oedu**: OEDU file containing optimized protein-ligand complex

Command Line Help
===================

A description of the command line interface can be obtained by executing **OptimizeDU**
with the `--help` option.

.. code-block:: console

   > optimizedu --help

will generate the following output:

::

   Help functions:
     optimizedu --help simple      : Get a list of simple parameters
     optimizedu --help all         : Get a complete list of parameters
     optimizedu --help defaults    : List the defaults for all parameters
     optimizedu --help <parameter> : Get detailed help on a parameter
     optimizedu --help html        : Create an html help file for this program
     optimizedu --help versions    : List the toolkits and versions used in the application

Required Parameters
===================

.. option:: -in <filename>

   An OEDU file containing one or more design units, containing protein and ligand.

   [keyless parameter 1]

Optional Parameters
===================

File Options
==================

.. option:: -log

   The argument for this flag specifies the name of
   the log file.  The level of detail for logfile information can be
   altered using the :option:`-verbose` flag.  Generation of an
   output log may be disabled by providing ``nul`` as a argument in Windows and ``/dev/null`` as an
   argument on Linux and macOS.  
   [default = ``prefix`` _log.txt]

.. option:: -prefix

   The argument for this flag defines the prefix to be used
   for various information and data files generated.  Most
   important among these is the '*prefix_parm.txt*' file which includes a
   copy of all the parameters used in the run.  The prefix is
   also used to generate a default log file name if not explicitly
   specified with the *-log* flag. 
   [default = <app_name>].

.. option:: -verbose

   This is a boolean flag that controls the level of
   detail written to the log file.  By default only
   minimal information is written to the log file. 
   Verbose logging will cause more information to be written to the log
   file in order to follow behavior during program execution.  
   [default = false]

.. option:: -molNames

   This parameter takes a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set then only molecules in the
   input file(s) (see parameter :option:`-in`) with names that match those
   in the text files will be read in.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecule(s) that are contained in a large file, without
   having to extract those molecules by hand from the input molecules file.
   [default = NONE].

.. option:: -progress

   Show progress on screen.  Options are 'none', 'dots', 'log' and 'percent'.
   The 'dots' options will displays dots on screen to show molecules
   completed.  The 'log' option will duplicate the log file on screen.
   The 'percent' option will track progress through the input file.  
   [default = none]


Input Options
---------------------------

.. option:: -proteinMask

   Design unit components mask defining the subset of design unit components to
   be used as ``protein`` during optimization. Multiple components can also be combined as
   a comma-separated string to create the input.

   Possible values include cofactors, counter_ions, excipients, lipids, metals, nucleic, other_cofactors,
   other_ligands, other_nucleics, other_proteins, packing_residues, polymers,
   post_translational, protein, solvent, and sugars.

   Predefined multi-component values:

   * **targetComplex** =
     protein,nucleic,cofactors,solvent,metals,counter_ions,lipids,other_proteins,
     other_nucleics,other_ligands,other_cofactors.
   * **targetComplexNoSolvent** = protein,nucleic,cofactors,metals,lipids,other_proteins,
     other_nucleics,other_ligands,other_cofactors.
   * **macroMolComponents** = protein,nucleic,other_proteins,other_nucleics.

     [Default=targetComplex]

.. option:: -receptorMask    [Default=True]

   Flag indicating if the ``Design unit components mask`` defining the subset of design 
   unit components to be used as ``protein`` during optimization should be picked up based
   on the mask defined in the receptor. If the input ``Design Unit`` does not contain
   a receptor, the optimizer automatically falls back to using the ``-proteinMask``.

.. option:: -ignoreAroBent    [Default=False]

   Flag indicating if optimization should not fail due to excess deviation from
   planarity for aromatic rings in optimized ligands.  By default, optimization would fail
   if aromatic rings deviate from planarity in an optimized ligand by more than five degrees
   on average, or if certain torsion exceeds a maximum of 10 degrees.

Output Options
---------------------------

.. option:: -out <filename>

   An OEDesignUnit file containing the optimized protein-ligand complexes.

   [keyless parameter 2]

Optimization Options
---------------------------

.. option:: -optimize    [Default=poseCartesian]

   Optimization type.
   Choices: [0] cartesian: performs a full cartesian optimization, or [1] poseCartesian: performs
   a constrained cartesian optimization, ensuring to hold the ligand pose.

.. option:: -ff    [Default=ff14sb_sage]

   The force field to use for optimization.  A predefined force field can be used by
   choosing one from the list of choices.  A different SMIRNOFF/OpenFF formatted
   small molecule force field can be used with ff14SB by passing in the
   small molecule force field OFFXML file as the argument.
   Choices: ``mmff94``, ``mmff94s``, ``mmff_amber``, ``mmffs_amber``, ``ff14sb_parsley``, and ``ff14sb_sage``.

.. option:: -ligandCharge    [Default=current]

   Charges to be assigned for the ligand. The default value of ``current`` refers to
   using the existing charges on the ligand.
   Choices: [0] current, [1] am1bcc, [2] am1bccelf10, and [3] MMFF.

.. option:: -gradTol    [Default=1.0e-6]

   Root mean squared (RMS) gradient tolerance for convergence and termination of optimization.

.. option:: -maxIter    [Default=1000]

   Maximum number of iterations for termination of optimization.  Optimization is terminated
   if either the gradient tolerance ``gradTol`` or the maximum iterations limit, whichever
   occurs first, is reached.

.. option:: -solventModel    [Default=vacuum]

   Solvent model to be used during optimization.
   Choices: [0] vacuum, [1] sheffield, or [2] pb.

Protein Flexibility Options
------------------------------

.. option:: -flexRange    [Default=2.0]

   Distance at which protein residues should be considered flexible. The distance is measured between
   all ligand atoms and the protein residues.  The protein is completely rigid when a value of
   ``0.0`` is used.

.. option:: -residueID    [Default=None]

   Regular expression (Regex) strings describing residues that should be considered flexible.
   When a value for ``residueID`` is provided, it overrides the ``-flexRange`` (i.e., the flexRange
   is ignored).


.. _szybki_releasenotes:

Release History
===============

.. toctree::
   :maxdepth: 3

   version2_9_2
   version2_9_1
   version2_9_0
   version2_8_0
   version2_7_1
   version2_7_0
   version2_6_0
   version2_5_1
   version2_5_0
   version2_4_0
   version2_3_1
   version2_3_0
   version2_2_0
   version1_11_0
   version1_10_1
   version1_10_0
   version1_9_0
   version1_8_0
   version1_7_0
   version1_5_2
   version1_5_1
   version1_5_0
   version1_3_4
   version1_3_3
   version1_3_2
   version1_3_1
   version1_3_0
   version1_2_2


#################
SZYBKI 2.9.1
#################

Minor internal improvements have been made.

****************************************
Related Toolkit Information
****************************************



Szybki TK 2.9.1
================================================================================

Minor internal improvements have been made.



#################
SZYBKI 2.9.0
#################

*************************************
New Features
*************************************

.. program:: OptLigandInDU

* The following two new options have been added to both **OptLigandInDU** and **OptimizeDU**:
  
  * :option:`-receptorMask` enables the use of ``proteinMask`` from the design unit receptor.
  * :option:`-ignoreAroBent` enables the ability to ignore failure due to excess deviation from planarity for aromatic rings.

* The default for  :option:`-optimize` for both **OptLigandInDU** and **OptimizeDU**
  has been changed to ``poseCartesian`` to perform constrained Cartesian optimization,
  ensuring holding of the ligand pose.

*************************************
Minor Bug Fixes
*************************************

* **OptimizeDU** no longer crashes when a nonexistent ``.lst`` or ``.list`` file
  is passed as an argument to :option:`-in`.

****************************************
Related Toolkit Information
****************************************


Szybki TK 2.9.0
================================================================================

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


* A new class, :ref:`OEOELigandChargeOptions<OESz_OELigandChargeOptions>`,
  has been added that provides options related to ligand charge assignment. The following classes
  now derive from :ref:`OEOELigandChargeOptions<OESz_OELigandChargeOptions>`,
  enabling greater flexibility in ligand charge assignment:

  * :ref:`OEProteinLigandOptOptions<OESz_OEProteinLigandOptOptions>`
  * :ref:`OETorsionScanOptions<OESz_OETorsionScanOptions>`
  * :ref:`OEBoundEntropyOptions<OESz_OEBoundEntropyOptions>`
  * :ref:`OELigandEntropyOptions<OESz_OELigandEntropyOptions>`

* The default optimization type has been changed to :ref:`PoseCartesian <OESz_OEOptimizationType_PoseCartesian>`
  in both :ref:`OEFixedProteinLigandOptimizer<OESz_OEFixedProteinLigandOptimizer>` and 
  :ref:`OEFlexProteinLigandOptimizer<OESz_OEFlexProteinLigandOptimizer>`.

* The following two new constants have been added to the :ref:`OESzybkiReturnCode <OESz_OESzybkiReturnCode>` namespace:
  
  * :ref:`AromaticRingDev<OESz_OESzybkiReturnCode_AromaticRingDev>`: refers to failure due to excessive aromatic distortion.
  * :ref:`OptimizerFailed<OESz_OESzybkiReturnCode_OptimizerFailed>`: refers to the optimizer failing to find a solution.

* The following class methods now take an optional predicate describing residues that
  should be considered as part of the protein target during optimization:

  * :ref:`SetProtein<OESz_OEFixedProteinLigandOptimizer_SetProtein>` in :ref:`OEFixedProteinLigandOptimizer<OESz_OEFixedProteinLigandOptimizer>`
  * :ref:`Optimize<OESz_OEFlexProteinLigandOptimizer_Optimize>` in :ref:`OEFlexProteinLigandOptimizer<OESz_OEFlexProteinLigandOptimizer>`
  * :ref:`Energy<OESz_OEFlexProteinLigandOptimizer_Energy>` in :ref:`OEFlexProteinLigandOptimizer<OESz_OEFlexProteinLigandOptimizer>`

* The following new preliminary API classes have been added, enabling optimization
  of a ligand with torsion constraints:

  * :ref:`OELigandEnergy <OESz_OELigandEnergy>`
  * :ref:`OELigandOptOptions <OESz_OELigandOptOptions>`
  * :ref:`OELigandOptResults <OESz_OELigandOptResults>`
  * :ref:`OETorConstraintOptimizer <OESz_OETorConstraintOptimizer>`
  * :ref:`OETorConstraintOptOptions <OESz_OETorConstraintOptOptions>`

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

* :ref:`OEFixedProteinLigandOptimizer<OESz_OEFixedProteinLigandOptimizer>` and 
  :ref:`OEFlexProteinLigandOptimizer<OESz_OEFlexProteinLigandOptimizer>` no longer fail
  to optimize with the :ref:`ExcessiveOverlap<OESz_OESzybkiReturnCode_ExcessiveOverlap>` error code
  prematurely.

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

* :ref:`OEFreeFormConfOptions<OESz_OEFreeFormConfOptions>` now sets the
  :ref:`latest Sage force field<OESz_OEForceFieldType_SAGE_OPENFF>` as the default.

* An issue has been fixed in :ref:`OETorsionScan <OESz_OETorsionScan>` where scanning using the option
  :ref:`SetUseInternalCoord <OESz_OETorsionScanOptions_SetUseInternalCoord>` set to ``true`` would occasionally produce 
  large unphysical energies at certain angles.




SZYBKI  2.8.0
================================================================================

Minor internal improvements have been made.



Szybki TK 2.8.0
================================================================================

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

* The constant :ref:`SAGE_OPENFF <OESz_OEForceFieldType_SAGE_OPENFF>` refers to the
  latest version of the Sage OpenFF force field.

   



SZYBKI  2.7.1
================================================================================

Minor internal improvements have been made.


.. _section_szybkitk_releasenotes_2713:

Szybki TK 2.7.1.3
================================================================================

 * The constant :ref:`OESz_OEForceFieldType_SAGE_OPENFF <OESz_OEForceFieldType_SAGE_OPENFF>` refers to the
   2.2.0 version of the Sage-OpenFF force field.


.. _section_szybkitk_releasenotes_2710:

Szybki TK 2.7.1.0
================================================================================

* :ref:`OEFixedProteinLigandOptimizer<OESz_OEFixedProteinLigandOptimizer>`
  and :ref:`OEFlexProteinLigandOptimizer<OESz_OEFlexProteinLigandOptimizer>` now
  propagate error better when optimization fails.



   



SZYBKI  2.7.0
================================================================================



Szybki TK 2.7.0
================================================================================

New features
--------------------------------------------------------------------------------
* The ability has been added to perform optimization in internal coordinates, with fixed torsions, during a torsion scan.
  Accordingly, the following additional commands
  have been added to :ref:`OETorsionScanOptions <OESz_OETorsionScanOptions>`:

    * :ref:`SetUseInternalCoord <OESz_OETorsionScanOptions_SetUseInternalCoord>`
    * :ref:`GetUseInternalCoord <OESz_OETorsionScanOptions_GetUseInternalCoord>`
    * :ref:`SetTolerance <OESz_OETorsionScanOptions_SetTolerance>`
    * :ref:`GetTolerance <OESz_OETorsionScanOptions_GetTolerance>`
    * :ref:`SetMaxIter <OESz_OETorsionScanOptions_SetMaxIter>`
    * :ref:`GetMaxIter <OESz_OETorsionScanOptions_GetMaxIter>`

* The ability to apply a nonbonded interactions cutoff in
  :ref:`OEProteinLigandOptOptions<OESz_OEProteinLigandOptOptions>` has
  been added. The following two methods are also available in
  the class:

    * :ref:`SetNonBondCutoff <OESz_OEProteinLigandOptOptions_SetNonBondCutoff>`
    * :ref:`GetNonBondCutoff <OESz_OEProteinLigandOptOptions_GetNonBondCutoff>`

* Both :ref:`OEFixedProteinLigandOptimizer<OESz_OEFixedProteinLigandOptimizer>`
  and :ref:`OEFlexProteinLigandOptimizer<OESz_OEFlexProteinLigandOptimizer>`
  now apply a nonbonded interactions cutoff of `40.0` by default.

* A new class, :ref:`OETorsionScanner<OESz_OETorsionScanner>`,
  has been added to provide greater flexibility over the existing
  function :ref:`OETorsionScan<OESz_OETorsionScan>` in extracting
  intermediate results from the scanning.

Major bug fixes
--------------------------------------------------------------------------------
* An issue where the overloaded method :ref:`SetTorsionConstraint <OESz_OESzybki_SetTorsionConstraint>`
  would occasionally fail has been fixed.

Minor bug fixes
--------------------------------------------------------------------------------
* Validation of user-selected torsion in torsion scan has been added. If a torsion passed
  to function :ref:`OETorsionScan <OESz_OETorsionScan>` or method
  :ref:`Scan <OESz_OETorsionScanner_Scan>` does not exist, the torsion scan code stops
  with a message that the torsion does not exist in the input molecule.


   



SZYBKI  2.6.0
================================================================================

Minor bug fixes
--------------------------------------------------------------------------------
* **OptLigandInDU** no longer attempts to write an empty molecule
  in the output file when the optimization fails.

* **OptimizeDU** now fails with an appropriate message when attempting
  to optimize an apo design unit.


.. _section_szybki_releasenotes_2601:

Szybki TK 2.6.0.1
================================================================================

* New constant :ref:`SAGE_OPENFF210 <OESz_OEForceFieldType_SAGE_OPENFF210>` has been
  introduced that refers to the Sage 2.1.0 force field. The constant 
  :ref:`SAGE_OPENFF <OESz_OEForceFieldType_SAGE_OPENFF>` now refers to
  this latest version of Sage force field.


Szybki TK 2.6.0.0
================================================================================

New features
--------------------------------------------------------------------------------
* Three classes have been added to facilitate using ff14SB/OpenFF 
  potential for bound ligands and to bypass using OESzybki:

  * :ref:`OEBoundEntropyOptions <OESz_OEBoundEntropyOptions>`
  * :ref:`OELigandEntropyOptions <OESz_OELigandEntropyOptions>`
  * :ref:`OEEntropyResults <OESz_OEEntropyResults>`

* A new function, :ref:`OEBoundLigandEntropy <OESz_OEBoundLigandEntropy>`, has been added
  to calculate the entropy of a bound ligand.

* A new function, :ref:`OELigandEntropy <OESz_OELigandEntropy>`, has been added to calculate the 
  entropy of a free ligand.

* A new pair of options has been added to the :ref:`OETorsionScanOptions <OESz_OETorsionScanOptions>`
  to address hysteresis in torsion scanning. These provide the ability to increase the number of starts
  (:ref:`SetNumStarts <OESz_OETorsionScanOptions_SetNumStarts>`) and address the
  overlaps between scans (:ref:`SetOverlapDiv <OESz_OETorsionScanOptions_SetOverlapDiv>`) to avoid
  doing full 360-degree scans for many starts unless desired.

Major bug fixes
--------------------------------------------------------------------------------
* An issue with the torsion scan (:ref:`OETorsionScan <OESz_OETorsionScan>`) in
  solution with PB solvation has been fixed. It no longer incorrectly uses the
  MMFF94S potential even when
  scanning is done with the OpenFF force field.

* An issue with hysteresis that in certain cases caused asymmetric torsion scans 
  has been addressed by resetting to the starting angle before starting reverse scans.

Minor bug fixes
--------------------------------------------------------------------------------
* Better diagnostics have been added to :ref:`OEFixedProteinLigandOptimizer <OESz_OEFixedProteinLigandOptimizer>`
  when the optimization of a ligand in a fixed protein receptor fails due to an initial clash.
  An appropriate error code is now returned for such cases.
  
* :ref:`OEFlexProteinLigandOptimizer <OESz_OEFlexProteinLigandOptimizer>`
  now provides an appropriate error code when asked to optimize a design unit
  that does not contain a ligand.

   



SZYBKI  2.5.1
================================================================================

*Fall 2022*

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

* Output for :option:`freeform -calc` ``conf`` now
  adds dG, local strain, and global strain values to tracked conformer output
  files as SD data.

Minor bug fixes
--------------------------------------------------------------------------------
* A misleading error message produced by **SZYBKI** when run with
  :option:`freeform -ff` ``ieff_mmff94`` or :option:`freeform -ff` ``ieff_mmff94s``, without specifying the receptor with
  either :option:`szybki -protein` or :option:`szybki -complex`, has been improved.

* Values of dG, local strain, and global strain have been added to the ``tracked_rst`` file when
  freeform is run with the :option:`freeform -track` option.

* Case-insensitive values for :option:`freeform -ff` are now accepted in :ref:`SZYBKI <chapter_szybki>`.


Szybki TK 2.5.1.2
================================================================================

* Possible crashes in :ref:`OEFixedProteinLigandOptimizer_Optimize <OESz_OEFixedProteinLigandOptimizer_Optimize>` and
  :ref:`OEFlexProteinLigandOptimizer_Optimize <OESz_OEFlexProteinLigandOptimizer_Optimize>`
  methods have been fixed.


Szybki TK 2.5.1.1
================================================================================

New features
--------------------------------------------------------------------------------
* Optimization of bound ligands with ff14SB/Sage and ff14SB/Parsley force fields
  with PB solvation forces in rigid and partially flexible receptors is now available.

* Setting the force field to :ref:`PARSLEY_OPENFF131 <OESz_OEForceFieldType_PARSLEY_OPENFF131>` or
  :ref:`SAGE_OPENFF200 <OESz_OEForceFieldType_SAGE_OPENFF200>` now references the most recent official
  versions of those two parameterizations which are OpenFF_1.3.1 and OpenFF_2.0.0
  respectively. Older versions are still available from the
  :ref:`OEForceFieldType <OESz_OEForceFieldType>` namespace.

* Final ligand geometry is now checked when large initial clashes occur while using 
  :ref:`OEFixedProteinLigandOptimizer <OESz_OEFixedProteinLigandOptimizer>` and :ref:`OESz_OEFlexProteinLigandOptimizer <OESz_OEFlexProteinLigandOptimizer>`
  for optimization of a ligand inside a protein
  receptor. In most cases, clashes are successfully relaxed; however, in some cases
  they can lead to a nonphysical minimum which is characterized with distorted geometry.
  Such results can now be detected by checking the return values of methods
  :ref:`OEFixedProteinLigandOptimizer_Optimize <OESz_OEFixedProteinLigandOptimizer_Optimize>` and
  :ref:`OEFlexProteinLigandOptimizer_Optimize <OESz_OEFlexProteinLigandOptimizer_Optimize>`.


Major bug fixes
--------------------------------------------------------------------------------
* An issue with torsion scan for alkanes using MMFF has been fixed.

* :ref:`OEFixedProteinLigandOptimizer_Optimize <OESz_OEFixedProteinLigandOptimizer_Optimize>` and
  :ref:`OEFlexProteinLigandOptimizer_Optimize <OESz_OEFlexProteinLigandOptimizer_Optimize>`
  now fails properly when optimization leads to a nonphysical state of a molecule,
  characterized with distorted geometry. Such nonphysical optimization can sometimes
  happen when the starting configuration of a protein-ligand complex contains high overlaps.

Minor bug fixes
--------------------------------------------------------------------------------
* A warning regarding 'invalidation of receptor' upon optimization using the
  :ref:`OEFlexProteinLigandOptimizer <OESz_OEFlexProteinLigandOptimizer>` class has been removed.



   



SZYBKI  2.5.0
================================================================================

*Spring 2022*

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

* A new command-line parameter, ``-solventModel``, has been added to :ref:`OptLigandInDU`, and :ref:`OptimizeDU`
  to support the Sheffield solvation model.

Minor bug fixes
------------------------------------------------
* An issue has been fixed where failure to assign atom vdw parameters were ignored
  resulting in calculations being performed with values of zero being assigned as
  the parameters. The effect of this fix can be observed in calculations performed 
  using :ref:`SZYBKI <chapter_szybki>`, :ref:`FREEFORM <chapter_freeform>`,
  :ref:`OptLigandInDU`, and :ref:`OptimizeDU`.

* An issue  causing the ``optimizedu --help``, or any
  related commands, to segfault has been fixed.



Szybki TK 2.5.0
================================================================================

New Features
--------------------------------------------------------------------------------
* The ability to use the Sheffield Solvation Model has been added to :ref:`OEFlexProteinLigandOptimizer <OESz_OEFlexProteinLigandOptimizer>` and
  :ref:`OEFixedProteinLigandOptimizer <OESz_OEFixedProteinLigandOptimizer>`.

* Two additional methods have been added to the
  :ref:`OEProteinLigandOptOptions <OESz_OEProteinLigandOptOptions>`
  class:

    * :ref:`GetSolventModel <OESz_OEProteinLigandOptOptions_GetSolventModel>`
    * :ref:`SetSolventModel <OESz_OEProteinLigandOptOptions_SetSolventModel>`


   



SZYBKI  2.4.0
================================================================================

*Fall 2021*

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

* A new option, ``sage_openff2.0.0``, has been added as a possible value for the ``-ff`` parameter in
  **SZYBKI** and in **Freeform**.

* **Freeform** uses the latest version of the Open Force Field by default.
  For this release that is ``sage_openff2.0.0``.  

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

* :ref:`OptLigandInDU` now operates with expected keyless entries in the command line.

* An issue where "MMFF94S" was logged to the logfile regardless of what force field was used has been fixed.
   

Documentation Changes
-------------------------------------------------------------------------------

* :ref:`Freeform Examples<freeform_example>`  has been updated.
  


SZYBKI 1.10.0
================================================================================

*November 2018*

* This version of **SZYBKI** has been built using **OEToolkits 2018.Oct**. The 
  previous version was built using **OEToolkits 2015.Oct**.

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

* The **Freeform** application has been re-implemented to take advantage of the
  re-engineered functionality in **Szybki TK**.

* The ``PDF`` report generated with **Freeform** has been improved for clarity.

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

* An issue that caused a **SZYBKI** entropy job to terminate if a molecule in a 
  multi-molecule input file failed to process successfully has been fixed. If the 
  entropy calculation fails on a particular molecule, the next molecule is 
  now processed.



SZYBKI 1.10.1
================================================================================

*May 2019*

* This version of **SZYBKI** has been built using **OEToolkits 2019.Apr**. The previous
  version was built using **OEToolkits 2018.Oct**.

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

* ``freeform -calc solv`` has been fixed to properly
  calculate solvation energy when used with ``-solvcharges input``.

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

* Occasional overflow of table contents in the ``freeform -calc conf`` generated report
  file has been eliminated.

* Unreasonably high energy conformers information are clipped from the energy plots
  in the report generated from ``freeform -calc conf``.

* **SZYBKI** entropy calculation with ``-entropy AN`` no longer produces a crash.


SZYBKI 1.11.0
================================================================================

*Nov 2019*

* This version of **SZYBKI** has been built using **OEToolkits 2019.Oct**. The previous
  version was built using **OEToolkits 2019.Apr**.

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

* Two SMIRNOFF (SMIRks Native Open Force Field) specification-based force fields,
  ``Smirnoff99Frosst`` and ``OpenFF1.0.0``, have been added as legal values for the command
  line option ``-ff`` for both **SZYBKI** and **FreeForm**. These force fields use
  extended SMARTS patterns for chemical representation of parameters.
  See https://openforcefield.org/ for more information.

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

* **SZYBKI** now exits cleanly with invalid inputs in MPI mode.

* **SZYBKI** now works with pipes.

* **SZYBKI** now works in MPI mode when there is more than one protein in the input file, which is
  consistent with its behavior in single processor mode. Previously, **SZYBKI** threw a fatal error in MPI mode.

* Issue with molecule count when running ``freeform -calc solv`` has been fixed.


.. _szybki_releasenotes_122:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


SZYBKI 1.2.2
================================================================================

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

*  Two new functions are added to the API:

   void SetResidueFlexibility(double dist);
   double GetResidueFlexibility() const;

   These allow the user to introduce and query for the flexibility of
   entire residues around the ligand.

Bug fixes
--------------------------------------------------------------------------------

*  In the case when protein electrostatic model was set at
   ``OEProteinElectrostatics::NoElectrostatics`` and partial protein
   flexibility was allowed with the ``void
   SetSideChainsFlexibility(double)`` or ``void
   SetPolarHFlexibility(double)`` functions, Coulombic terms describing
   the interaction between the ligand and flexible protein atoms were
   included during optimization. This was inconsistent with the
   meaning of ``NoElectrostatics``, therefore those Coulombic terms were
   eliminated in the current release

*  Using the function ``void SetSideChainsFlexibility(double)`` resulted
   occasionally in double counting of some residues. This bug was fixed.

*  Fixing atoms with a function ``bool FixAtoms(std::string)`` where the
   passed string is SMARTS pattern, was based on MMFF aromaticity
   types.  Starting from the current release OE aromaticity model is
   used.


.. _szybki_releasenotes_130:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


SZYBKI 1.3.0
================================================================================

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

*  Optimization using conjugate gradient method was added as an
   alternative to the default quasi-Newton method with the BFGS
   Hessian update scheme. In Szybki toolkit this is done by the usage
   of a new function ``void SetOptimizerType(unsigned int type)``. In
   Szybki application a flag ``-conj`` has been added for that
   purpose.

*  Default value of the protein dielectric constant is 1. Previous
   default value for that parameter was 2, however it was not
   consistent with the default value of MMFF94 force field.

*  Protein-electrostatic models in Szybki application are selected with
   descriptive strings. Available options are:
     
   + ``None`` - no electrostatic potential used (default option)
   + ``ExactCoulomb`` - exact MMFF Coulomb potential
   + ``GridCoulomb`` - MMFF Coulomb potential on grid
   + ``PB`` - PP solvent forces used at every step

Bug fixes
--------------------------------------------------------------------------------

*  A bug causing crash in the case of combined usage of partial protein
   flexibility and protein electrostatic model
   OEProteinElectrostatics::SolventPBForces was fixed.

*  A bug causing different behavior and/or occasional crash depending
   of the order of calls: SetProtein(const OEChem::OEMolBase&),
   SetRunType(unsigned int) and SetResidueFlexibility(double) has been
   fixed.

*  Modification of the potential function after the usage of coordinate
   adaptors could occasionally result in crash, for example when
   function FixAtoms() was followed by SetRemoveCoulombTerms(). This
   bug was fixed.

*  Running in the pvm mode requires now setting the PVM_PATH variable,
   which points at the directory where the Szybki script is
   located. For example if Szybki was untarred in the directory
   ``mydir``, then using bash shell one can set the above variable
   with: export PVM_PATH=mydir/openeye/bin


.. _szybki_releasenotes_131:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


SZYBKI 1.3.1
================================================================================

Bug fixes
--------------------------------------------------------------------------------

*  The combination of options ``-complex if1`` and ``-ligands if2`` run
   in the pvm mode caused incorrect behavior in the case when the
   preexisting ligand in the macromolecule (in the file if1)
   overlapped with one or more ligands from the input file if2.

*  Run time license for the shape toolkit is added. It is required when the
   combination of options ``-complex if1`` and ``-ligands if2`` is used.

*  Redundant  warnings  generated  upon  ``-protein_elec  none`` and
   ``-strip_water`` were removed.

*  Spelling in the log file was fixed.

*  Year 2008 was added to the Szybki banner.

*  In the documentation description for the ``-fix_smarts`` option an
   example was added which illustrates the adjustment of hydrogen atom
   positions.

*  Examples of log files generated upon ligand optimization in the
   partially flexible protein followed by a single point PB
   calculations are given.


.. _szybki_releasenotes_132:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


SZYBKI 1.3.2
================================================================================

Bug fixes
--------------------------------------------------------------------------------

*  A bug which occasionally caused errors in fixing a subset of atoms, was
   fixed.

*  When using PVM, Szybki now runs a mechanism for checking versions
   used by master and slaves. This mechanism prevents the situation of
   different versions of Szybki running on the master and slaves.

*  Molecules containing atoms for which MMFF types are not properly
   typed are not processed. In previous versions attempts were made to
   assign for such atom the closest MMFF type, however this procedure
   almost always lead to errors. This situation occurred for example in
   the case of bad pdb files. For proteins, better diagnostics
   (residue name and number, atom name) are included as output.

*  Reading protein data in .oeb binary format containing additional
   untagged information (FRED receptor files) is allowed. Until now
   using such a file in pvm mode caused a fatal error.


.. _szybki_releasenotes_133:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


SZYBKI 1.3.3
================================================================================

Bug fixes
--------------------------------------------------------------------------------

*  Until current release, molecular output files in the .oeb format had
   MMFF aromaticity. In practice, such a situation lead to the visual
   change between the input and output aromaticity of some molecules.
   Starting from now OpenEye aromaticity model is used in the .oeb
   output files.


.. _szybki_releasenotes_134:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: szybki

SZYBKI 1.3.4
================================================================================

New features
--------------------------------------------------------------------------------
*  Calculation of the constant potential terms at the end of adapted
   optimization can be optionally eliminated, by the use of the
   :option:`-neglect_frozen` flag. This feature allows for less memory
   and cpu usage in the case of partial optimization of large
   molecules.

*  The corresponding atom symbols, bond symbols, and torsion angles
   are now printed on a line under the matching smarts pattern.

Bug fixes
--------------------------------------------------------------------------------

*  Input proteins with only partial information about residues were not
   handled properly. As a result, none of the side chains which were
   supposed to be made flexible with the use of an option ``-sideC``
   were optimized.  This problem was fixed.

*  A bug causing memory corruption in the case of ligand optimization
   in partially flexible protein receptor is fixed. 

*  Residues with nonstandard name ``CYX`` were not properly handled in
   the situation when their side chains were included into the
   flexible part of the protein receptor. This bug has been fixed.



.. _szybki_releasenotes_150:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: szybki

SZYBKI 1.5.0
================================================================================

.. program:: szybki

New features
--------------------------------------------------------------------------------
*  Starting from the current release, certain classes of divalent selenium 
   compounds can be handled by Szybki. Currently only some compounds in which 
   selenium is bonded to the hydrogen or carbon atoms can be processed. Those 
   compounds include selenols (RSeH) and selenides (RSeR1) in which Se is bonded 
   to alkyl or aromatic carbon atoms, with the exception when Se makes a bond with 
   alkyl C which belongs to the 3- or 4-membered ring.
   
*  Previous Szybki releases attempted to assign the "closest" MMFF94 atom type
   to those atoms for which a unique MMFF94 type could not be found. Starting 
   from the 1.5.0 release this feature is removed, so consequently the input
   molecules containing such atoms will not be processed.

*  Ligand RMSD which is reported in the log file, can optionally refer to the heavy atoms 
   only. The new option used for that purpose is :option:`-heavy_rms`. 

*  Entropy calculations of a ligand in different environments can be performed
   based on the methods described in the recent paper of Wlodek *et. al.* (\ [Wlodek-2010]_\).
   This is done with the option :option:`-entropy` described in the section 4.1 of this manual.

* Default VdW protein-ligand potential used for the optimization of a ligand inside the
  protein binding site is precalculated in the form of a lookup table. This is done
  for the purpose of speed. The exact VdW protein-ligand potential can be used with the
  option :option:`-exact_vdw`.
    

Bug fixes
--------------------------------------------------------------------------------
*  Memory leak in ligand torsion optimization inside the partially flexible
   protein receptor was removed. 



.. _szybki_releasenotes_151:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: szybki

SZYBKI 1.5.1 
================================================================================

.. program:: szybki

Bug fixes
--------------------------------------------------------------------------------
*  Ligand optimization in the active site with the use of the flag :option:`-protein_elec` 
   set at ``PB`` ended prematurely. This problem has been fixed.

*  In the previous (1.5.0) release the entropy calculation of the protein-bound ligand
   worked only when a single molecule in the ligand input file was present. In the case when
   the ligand input file contained two or more molecules, the calculation was performed
   for the first molecule and died on next one with segmentation fault. This bug is fixed.

* Calculated entropy of the protein-bound ligand was underestimated by up to 0.5 kcal/mol
  due to the underestimation of the buried protein surface area upon binding. This error
  is corrected in the current release.  

*  Using options: :option:`-exact_vdw` and :option:`-protein_elec` set at ``PB`` resulted
   in minimization with Coulomb and VdW potential only. This has been corrected in the
   current release.

*  Parameter file was written without the user command line flags. This bug is fixed.

*  A tiny memory leak in the calculations of protein-ligand interaction has been removed.     

*  Two subsections in documentation has been added. That includes the theory of entropy
   estimation adopted by SZYBKI and several examples of command line SZYBKI executions.


.. _szybki_releasenotes_152:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


SZYBKI 1.5.2 
================================================================================

New features 
--------------------------------------------------------------------------------
*  Entropy calculation of protein-bound ligands has been modified. Specifically,
   the fraction :math:`f` of ligand surface exposed to the solvent used in the 
   entropy component term: :math:`f\Delta S_s`, is calculated currently as 
   :math:`f = A_{Lexp}/A_L`, where :math:`A_{Lexp}` and :math:`A_L` are ligand 
   solvent accessible surfaces in the protein complex and solution respectively.
   The reason for a change is the recent OpenEye internal study which show 
   that the above fraction :math:`f` calculated according to the equation:
   :math:`f = 0.5(A_L - A_P + A_{PL})/A_L` (\ [Wlodek-2010]_\) is for many 
   protein-ligand complexes overestimated. The previous way of protein-bound 
   ligands entropy calculation is available with the option: "-ent 151".

*  The default value of microscopic surface tension used for protein entropy
   desolvation calculation is now 6 :math:`cal/(mol A^2)` (previously default
   value was set at 5 :math:`cal/(mol A^2)`. The flag "-sfp x", where x is
   microscopic surface tension for protein desolvation entropy calculation,
   allows to overwrite the default value.

*  Two more flags have been introduced: "-t x" and "-rws". The first of them
   sets the temperature x in C for entropy calculations (the default value is 
   25C). The second flag removes water molecules from all solvent accessible 
   surface calculations used for the evaluation of protein-bound ligand entropy,
   in the case the input protein contains water molecules.          

*  More entropy terms are reported in the log file. In earlier SZYBKI versions only 
   the total entropy was reported. Starting from 1.5.2 release in addition to total 
   entropy, configurational, solvation (or partial solvation) and protein desolvation
   entropy terms are reported.


.. _szybki_releasenotes_170:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


SZYBKI 1.7.0 
================================================================================

New features 
--------------------------------------------------------------------------------
*  An extension of the MMFF94 force field for three coordinated boron compounds 
   is offered in this release. Most compounds containing B-X bonds where X=C,N,O,S,
   and H are covered with the following exceptions: X=N(imine),N(sulfonamide),
   N(pyridinium) and N(quaternary). Also not supported are compounds in which
   boron is bonded to X=F,Cl,Br,I,B and Si, or makes a bond angle BYX.
   Compounds in which boron is a part of four-membered rings of B1CCC1 type are also
   not available in the current parameterization because their existence is questionable:
   Ab initio calculations at the MP2/6-31G** level failed to identify stable structures
   for them (highly polar structures in which boron is four-coordinated are formed). 

*  New input flag ``-solv_dielectric`` is added. It controls solvent dielectric
   for all PB and Sheffield calculations. Default value is 80. Flag 
   ``-prot_dielectric`` is changed into ``-inner_dielectric``. Previous flag
   ``-prot_dielectric`` can be used.

*  New option flag ``-salt x`` which sets the salt concentration for PB 
   calculations is added. x is concentration in mM. Default value is 0.

*  New option ``-flex_file`` which allow to specify only those atoms which will be
   optimized is added.    

*  Starting from the current release, binding entropy (:math:`T\Delta S`), can
   be calculated in a single run:

   szybki -entropy QN -complex pl_complex.oeb -ligands ligands.oeb

   where pl_complex.oeb is a protein-ligand complex file, and ligands.oeb 
   contains an ensemble of ligand conformations in solution.  

*  Entropy calculation of protein-bound ligands has been modified. Specifically,
   the fraction :math:`f` of ligand surface exposed to the solvent used in the 
   entropy component term: :math:`f\Delta S_s`, is calculated currently as 
   :math:`f = A_{Lexp}/A_L`, where :math:`A_{Lexp}` and :math:`A_L` are ligand 
   solvent accessible surfaces in the protein complex and solution respectively.
   The reason for a change is the recent OpenEye internal study which show 
   that the above fraction :math:`f` calculated according to the equation:
   :math:`f = 0.5(A_L - A_P + A_{PL})/A_L` (\ [Wlodek-2010]_\) is for many 
   protein-ligand complexes overestimated.

*  The default value of microscopic surface tension used for protein entropy
   desolvation calculation is now 6 :math:`cal/(mol A^2)` (previously default
   value was set at 5 :math:`cal/(mol A^2)`. The flag ``-sfp x``, where x is
   microscopic surface tension for protein desolvation entropy calculation,
   allows to overwrite the default value.

*  Two more flags have been introduced: ``-t x`` and ``-rws``. The first of them
   sets the temperature x in C for entropy calculations (the default value is 
   25C). The second flag removes water molecules from all solvent accessible 
   surface calculations used for the evaluation of protein-bound ligand entropy,
   in the case the input protein contains water molecules.          

*  More entropy terms are reported in the log file. In earlier SZYBKI versions only 
   the total entropy was reported. Starting from 1.7.0 release in addition to total 
   entropy, configurational, solvation (or partial solvation) and protein desolvation
   entropy terms are reported.

*  flag ``-mol2charges`` is replaced with ``-current_charges``. ``-mol2charges`` is now 
   an alias to the new flag.

* The format of the log file has been changed. Its readability is significantly improved.

* A new option ``-out_complex`` is added. It allows to output a protein-ligand complex
  after ligand optimization in partially flexible protein.

Bug fixes
--------------------------------------------------------------------------------
*  Optimization of polar hydrogens with the ``-polarH`` option when the input protein
   was in the PDB format resulted occasionally in mangling PDB atom names in the protein 
   output file. This bug has been fixed.

*  Combination of flags ``-complex``, ``-protein_elec PB`` and ``-exact_vdw`` caused 
   a crash on Windows platform. This bug has been fixed.

*  Previous Szybki versions produced the parameter and status files even when Szybki
   was run without any user option. This problem has been fixed in the current release.

*  Optimization of ligands in the partially flexible protein receptors in the case
   when the input file contained more than one ligand, stopped after processing the
   first ligand. This bug has been fixed.

*  Information on the selected user options was written to the stdout. That was making
   piping impossible. This behavior has been eliminated in the current release.

*  Input molecular files with badly specified geometry (with atom clashes), were not handled 
   properly. Starting from the current release such an input is caught and the processing of 
   such a molecule is skipped.

*  Optimization of large molecules (e.g. optimization of hydrogen positions in very large
   proteins) can lead to memory exhaustion on some platforms, due to too large amount of VdW 
   interactions or inability to allocate Hessian matrix in the quasi-Newton optimization.
   Previous Szybki releases terminated on such cases with the bad_alloc crash. This has
   been corrected by terminating the run and generating information on the mentioned above
   cases, so the user might decrease the number of VdW interactions or switch to conjugate
   gradient optimization method.


﻿.. _szybki_releasenotes_180:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: szybki

SZYBKI 1.8.0 
================================================================================

.. program:: szybki

New features 
--------------------------------------------------------------------------------
*  New utility program called ``FreeForm`` is available for Szybki users.
   It provides two distinct functionalities: evaluation of the solvation free energy
   of the input molecules and free energies of solution conformations.

*  A new forcefield for protein-ligand interactions is available upon selecting
   a new option :option:`-ff` followed by ``Amber_MMFF94`` or ``Amber_MMFF94S``. 
   It is a combination of MMFF94 (or MMFF94S) with Amber. 
   In this combined force field, MMFF94 (or MMFF94S) is used to describe the 
   intramolecular interactions of the ligand and the Amber force field is used 
   for the VdW and Coulomb interactions between ligand and protein. Currently, 
   this force field can be used only for ligands inside rigid proteins.

*  Entropy estimation based on analytical MMFF Hessian is extended for ligands 
   bound in a rigid protein using the option :option:`-entropy`.

*  Constraining torsion potential in the form: :math:`V=k_c(cos(phi) - cos(phi0))^2`, 
   where :math:`k_c` is the user specified force constant and :math:`phi0` is the 
   reference torsion dihedral angle is available with the use of the input flag
   :option:`-tor_constr`.

*  New option :option:`-optMethod` is introduced for optimization method selection.
   The possible choices of optimizers type are BFGS, conjugate gradient, steepest
   descent and mixtures of steepest descent preoptimization followed by BFGS
   of conjugate gradient. Option ``-conj`` is no longer supported.

*  Optimization of molecular systems with large number of degrees of freedom
   (>= 500) is by default done with the conjugate gradient method unless
   specifically requested with the option :option:`-optMethod`.

*  New option :option:`-optGeometry` is introduced for selection of coordinate
   system to be used during optimization. It replaces no longer supported 
   options `-opt_cart``, ``-opt_torsions``, ``-solid`` and
   ``-no_opt``. It can be also used to optimize hydrogen atoms positions
   only, instead of using for that purpose :option:`-fix_smarts`.  

*  Molecules from the input file which failed during processing are by default
   written to the separate molecular file. See the description of new option 
   :option:`-keepFailures`.

*  Starting from this release flags :option:`-fix_smarts` and :option:`-harm_smarts` 
   are followed by the name of the text file containing a single line with a SMARTS 
   pattern used to fix or constrain atoms. Input of SMARTS strings on the command line 
   for those flags are not used anymore because some SMARTS strings may contain special 
   characters which may be interpreted incorrectly on some platforms. 

Bug fixes
--------------------------------------------------------------------------------
* A few numerical errors in the calculation of analytical second derivatives
  (Hessian matrix) in MMFF torsion and out-of plane terms have been fixed. 

* When preoptimized ligands are used for entropy estimation it is necessary to gently
  moved the ligand out of minimum. The gradient norm below which such a perturbation was
  done was raised from 1 kcal/(mol |A|:math:`\AA`) to 10 kcal/(mol |A|:math:`\AA`). 
  Our research showed that for some conformations the above limit was too low which 
  resulted in overestimation of its vibrational entropy. 

* The usage of AM1BCC charges for PB, Sheffield and Coulomb protein-ligand interactions
  (option :option:`-am1bcc`) produces the output molecule which preserves the existing 
  partial charges from the input molecule. In previous versions MMFF94 charges were 
  attached to the output molecule.

* Output ligand molecule in the oeb format in a run when protein was partially flexible and
  when a flags :option:`-out_protein` or :option:`-out_complex` were used, had attached
  a protein molecule. This bug was fixed in the current release.  

Other changes
--------------------------------------------------------------------------------
* PVM (parallel virtual machine) is no longer supported. OpenMPI version 1.6 is supported 
  on all platforms. The :option:`-mpi_np` and :option:`-mpi_hostfile` flags are now used 
  to run SZYBKI in MPI mode. These new flags replace the oempirun script.

* This will be the last release to support SuSe 10.  


﻿.. _szybki_releasenotes_190:

.. |Angstrom|  replace:: Ångström

.. |Angstroms| replace:: Ångströms

.. |A|         replace:: Å

.. |Huckel|    replace:: Hückel

.. |Kekule|    replace:: Kekulé

.. |OpenEye|   replace:: *OpenEye, Cadence Molecular Sciences*


.. program:: szybki

SZYBKI 1.9.0 
================================================================================

.. program:: szybki

***************************************************
Major Changes in Freeform (``freeform -calc conf``)
***************************************************

* Tracking input conformers is no longer controlled by the
  ``-input3D`` flag (which has been removed). This is now done by specifying the
  file containing the conformers to track after the ``-track`` command line flag.

* Tracking multiple input conformers at once is now possible.

* Better solvation energies are now accessible as Poisson-Boltzmann
  single-point solvation energies at the Sheffield-solvation minima.

* Better conformational sampling in Freeform's first stage.

******************************
New Features
******************************

New features in SZYBKI
--------------------------------------------------------------------------------
*  A SMARTS pattern is no longer required to constrain torsion with harmonic
   potential (option :option:`-tor_constr`). This can now be done by providing 4 atom indices
   that define the torsion. 

*  Options ``-residue``, ``-sideC`` and ``-polarH`` are now deprecated
   and have been replaced by a combination of the :option:`-flextype` option and
   :option:`-flexdist` or :option:`-flexlist`. The latter allows user selected residues
   to be become flexible during bound ligand optimization.

*  Beginning with this release, the default value of the :option:`-protein_elec` option
   is ``ExactCoulomb``. In all previous versions, no protein-ligand electrostatic
   interactions were used by default.

New features in ``freeform -calc conf``
--------------------------------------------------------------------------------
*  The method for tracking input conformers has been changed.  The input file
   containing these conformers must now be specified after the `-track` flag. The old
   method of using the flag ``-input3D`` or ``-useInput3D`` will not work and will cause
   a command line error.

*  The command-line flag ``-input3D`` or ``-useInput3D``
   has been removed; the equivalent
   functionality is now performed by specifying an input file with the ``-track`` flag.

*  More than one input conformer per molecule can now be tracked in one run. The
   input conformers must either be successive conformers in an OEB file or successive
   structures of identical chemical graph, atom ordering, and bond ordering in
   another acceptable format.

*  A new flag ``-solvent`` has been added, allowing users to control whether they want
   a Poisson-Boltzmann corrected Sheffield solvation or
   no solvent at all (i.e., gas phase)
   as alternatives to Sheffield solvation (the default).

*  The new default method for applying partial charges to a ligand is AM1BCC ELF10,
   allowing up to 10 diverse conformers to be selected from conformers having the
   Electrostatically Least-interacting Functional groups (ELF).
   These conformers are then charged with the AM1BCCSym method and the charge sets
   averaged to come up with a single charge set applied to all conformers.
   This yields good-quality charge sets even for charged ligands.
   Previously, neutral versus charged ligands behaved differently:
   neutral ligands were charged using AM1BCCSym on a single ELF conformer, while
   charged ligands received MMFF94 charges for the sake of consistency.

*  The initial conformational search is now performed using the
   full MMFF94S forcefield with Sheffield solvation, and with an energy window increased
   to 15 kcal/mol. This leads to improved performance particularly for molecules having
   internal hydrogen bonds.

*  A new flag ``-ewindow`` has been added.  This flag sets the energy window used to
   accept or reject conformers in the initial conformational search stage
   in a manner strictly analogous to the flag of the same name used
   in **OMEGA** or the `SetEnergyWindow` parameter in **Omega TK**.

*  A new flag ``-maxconfs`` has been added.  This flag sets the maximum number of
   conformers allowed in the initial conformational search stage
   in a manner strictly analogous to the flag of the same name used
   in **OMEGA** or the `SetMaxConfs` parameter in **Omega TK**.

*  A new flag ``-solvent_dielectric`` has been added, allowing users to specify
   a dielectric other than 80.0 (the default) for the solvent dielectric of the
   Poisson-Boltzmann calculations in PB corrected solvation energies.

*  A new flag ``-forcefield`` has been added, allowing users to specify
   the MMFF94 forcefield instead of MMFF94S (the default) for the `freeform -calc conf`
   energy minimizations. The conformational search still uses MMFF94S.

*  To aid in analyzing the results of tracked conformers,
   three new output files have been added, with suffixes
   `*.tracked_input.oeb`, `*.tracked_rstr.oeb`, and `*.tracked_free.oeb`.
   These contain the structures and key output values (as SD tags)
   for the tracked conformers' input structures, restrained-optimized minima, and
   freely-optimized minima, respectively.

*  Zero-point energy is now included together with the internal
   energy and solvation energy when calculating the partition function. This quantity is
   calculated based on the same vibrational states used for the vibrational entropy.

*  The output log file has changed its contents and format to make it easier 
   to locate and extract key values.

*  The output CSV file has several fields that contain
   additional values relevant to conformer free energies.

Bug fixes
--------------------------------------------------------------------------------
* A discontinuity has been removed in flat-bottom potentials (:option:`-harm_constr1`
  followed by :option:`-harm_constr2`) that caused poor convergence during optimization
  and/or incorrect values of the harmonic potential to be reported in the log file.
  
* With the :option:`-flextype` option set with ``polarH`` the printed list now
  includes protein polar hydrogens that are flexible during bound ligand optimization.
  Previously, only a list of side chains or complete flexible residues was printed.

* An error message is now generated when trying to use Newton optimization when

  * a protein-ligand electrostatic model is not ``ExactCoulomb`` or ``None``, 
  * a free ligand is not in vacuum or other than Sheffield solvation model is used, 
  * a subset of atoms is fixed, or
  * a harmonic constraint potential is applied.

* When AM1BCC charges are selected in Sheffield or PB solvation models for multiply charged 
  species (with option `-am1bcc`), the SCF procedure in AM1 might not converge within
  20 cycles.
  To make sure that the calculated atomic charges are stable, up to 1000 SCF
  iterations are allowed for multiply charged molecules.

* Option :option:`-max_iter` no longer can be set to a value of zero.

* **SZYBKI** output molecular files in OEB format contain a number of calculated numeric data. 
  Previously, if such files had been used as input files in a subsequent **SZYBKI** run,
  the results reported in the log file could have been wrong. This problem has been fixed.          

* In ``freeform -calc conf``, using an existing input ensemble was previously restricted to molecules
  with 20 or fewer rotatable bonds. This limitation has been removed. 



﻿.. _szybki_releasenotes_220:

SZYBKI 2.2.0
================================================================================

*Spring 2020*

* This version of **SZYBKI** has been built using **OEToolkits 2020.0**.

* As part of the integration of **OEToolkits** and **OEApplications** into a single
  release, the version number of **SZYBKI** has been upgraded to 2.2.0 to make it
  consistent with that of **Szybki TK**.

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

* **SZYBKI** applications can now use SMIRNOFF force fields with the built-in parameters
  ``parsley_1.0.0`` and ``parsley_1.1.1``.  In addition, the applications can now use
  custom OpenFF parameters from an XML file.

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

* An issue with **Freeform** results that occurred when the output was in ``sd`` format combined
  with the option ``-track`` has been fixed.



.. _section_szybki_app_releasenotes_2302:

SZYBKI  2.3.0.2
================================================================================

*March 2021*

* A new parameter, ``-proteinMask``, has been added to both :ref:`OptimizeDU` and :ref:`OptLigandInDU`
  to provide flexibility in identifying the target protein components of a
  design unit for optimization.

.. _section_szybki_app_releasenotes_2300:

SZYBKI  2.3.0.0
================================================================================

*Fall 2020*

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

*  A new utility, :ref:`OptLigandInDU`, has been added that optimizes  a ligand
   against a rigid protein active site in a design unit.  Optimization can be
   performed with ``fff14sb_parsley``, ``mmff_amber``, or ``mmff`` force fields.

*  A new utility, :ref:`OptimizeDU`, has been added that optimizes a protein-ligand
   complex inside a design unit.  The protein can be treated as partially flexible
   during the optimization, and  can be performed with ``fff14sb_parsley``,
   ``mmff_amber``, or ``mmff`` force fields.

*  New options,  ``parsley_openff1.2.1`` and ``ff14sb_parsley``, have been added to
   the -ff command in  **SZYBKI**. The ``ff14sb_parsley`` is only meaningful when
   optimizing a protein or a part of a protein that includes cofactors.

* A new option, ``parsley_openff1.2.1``, , has been added to the ``-ff`` command
  in **Freeform -conf**.

Major Bug Fixes
--------------------------------------------------------------------------------
*  An issue that delivered incorrect results from binding entropy calculation
   with **SZUBKI**, when the ``-complex`` flag was used has been fixed.

*  Depiction of **Freeform -solv** results now shows the breakdown of group contributions.

Minor Bug Fixes
--------------------------------------------------------------------------------
*  Protein-ligand optimization with ``OpenFF-Parsley`` force fields using **SZYBKI** no
   longer fails even when the initial gradient norm is 1e15 kcal/(mol A) or larger.

*  The **SZYBKI** log file for protein-ligand complexes optimized with ``OpenFF-Parsley``
   force fields no longer provides the misleading message ``mmff94 partial charges were used``.

*  The log file for default **Freeform -conf** calculations that runs with default charges
   has been improved to correctly say that the ``ELF10`` partial charges were used.

*  Unnecessary warnings in entropy calculations with **SZYBKI** have been removed.


Szybki TK 2.3.0
================================================================================

*Fall 2020*

New features
--------------------------------------------------------------------------------
* A new SMIRNOFF force field from the `Open Force Field Initiative <https://openforcefield.org/>`_,
  Parsley 1.2.1, has been added as a built-in force field. It is
  defined as :ref:`PARSLEY_OPENFF121 <OESz_OEForceFieldType_PARSLEY_OPENFF121>`.

* A protein or part of a protein can now be optimized with the FF14SB force field.
  Cofactors with the exception if HEME are handled by the OpenFF/Parsley force field
  (for example Parsley 1.2.1), while parameters for HEME are taken from `Bryce Group <http://research.bmh.manchester.ac.uk/bryce/amber/>`_.

* The following preliminary classes have been added that enable optimizing protein-ligand complexes,
  with or without partial flexibility of the proteins, using the new :ref:`OEFF14SBParsleyComplex <OEFF_OEFF14SBParsleyComplex>` force fields,
  among others:

  * :ref:`OEFixedProteinLigandOptimizer <OESz_OEFixedProteinLigandOptimizer>`
  * :ref:`OEFlexProteinLigandOptimizer <OESz_OEFlexProteinLigandOptimizer>`

* A new preliminary class, :ref:`OEProteinLigandOptResults <OESz_OEProteinLigandOptResults>`, has been added
  that represents results of a protein-ligand complex optimization.

* Two new preliminary classes, :ref:`OEProteinLigandOptOptions <OESz_OEProteinLigandOptOptions>` and
  :ref:`OEProteinFlexOptions <OESz_OEProteinFlexOptions>`, have been added that provide choices for
  protein-ligand optimization and protein flexibility.

* A new namespace, :ref:`OESzybkiReturnCode <OESz_OESzybkiReturnCode>`, and a corresponding function,
  :ref:`OEGetSzybkiError <OESz_OEGetSzybkiError>`, have been added that correspond to return codes
  from the new optimizer classes.

Minor bug fixes
--------------------------------------------------------------------------------
*  Protein-ligand optimization with OpenFF/Parsley force fields using :ref:`OESzybki <OESz_OESzybki>` no
   longer fails, even when the initial gradient norm is 1e^15 kcal/(mol A) or larger.





SZYBKI  2.3.1
================================================================================

*July 2021*

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

* A new option, ``parsley_openff1.3.1`` has been added as a possible value for the ``-ff`` parameter in
  **SZYBKI** and in **Freeform**.

Minor Bug Fixes
--------------------------------------------------------------------------------
* The log file for **SZYBKI** has been updated with a note that option ``-exact_vdw``
  might be used to improve convergence for ligand optimization inside a protein
  receptor when MMFF94 or MMFF94S force fields are used. 


Szybki TK 2.3.1
================================================================================

*July 2021*

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

* The latest version of the
  `Open Force Field Initiative <https://openforcefield.org/community/news/general/new-releases-oct2020>`_,
  Parsley 1.3.1, has been added to the :ref:`OEForceFieldType <OESz_OEForceFieldType>` namespace as built-in force field
  :ref:`PARSLEY_OPENFF131 <OESz_OEForceFieldType_PARSLEY_OPENFF131>`.

* Support for user-defined force fields has been added to the :ref:`OETorsionScan <OESz_OETorsionScan>` function.
  Two new API points, :ref:`SetForceField <OESz_OETorsionScanOptions_SetForceField>` and :ref:`GetForceField <OESz_OETorsionScanOptions_GetForceField>`,
  have been added for setting and getting this value.

* Support for user defined dihedral angles has been added to :ref:`OETorsionScan <OESz_OETorsionScan>`.
  Two new API points, :ref:`SetUserDefinedAngles <OESz_OETorsionScanOptions_SetUserDefinedAngles>` and
  :ref:`GetUserDefinedAngles <OESz_OETorsionScanOptions_GetUserDefinedAngles>`, have been added for setting and getting this value.





.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _szybki_citation:

************
Citation
************

.. note:: To cite SZYBKI please use the following:

    SZYBKI |szybki_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com


.. VIDA documentation master file

.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _vida-application:

*******************
VIDA |vida_version|
*******************

.. toctree::
   :maxdepth: 2

   introduction
   install
   file_io
   display_3d
   display_2d
   spreadsheet
   lists
   processes
   builder
   customviews
   query
   scripting
   extensions
   preferences
   menus
   examples
   appendix/appindex
   releasenotes/index
   citation

..  only:: not html

    ..  include:: <isonum.txt>

=========================
Copyright and Trademarks
=========================

.. do not put explicit line breaks in this section

|copy| 1997-2024 Cadence Design Systems, Inc. (Cadence), 2655 Seely Ave., San Jose, CA 95134, USA. All rights reserved.

OpenEye, Lexichem, ROCS, Grapheme, and Orion are registered trademarks of Cadence Design Systems, Inc.

This material contains proprietary information of Cadence Design Systems, Inc.  Use of copyright notice is precautionary only and does not imply publication or disclosure.

The information supplied in this document is believed to be true, but no liability is assumed for its use or the infringement of the rights of others resulting from its use.  Information in this document is subject to change without notice and does not represent a commitment on the part of Cadence Design Systems, Inc.

This package is sold/licensed/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out, or otherwise circulated without Cadence Design Systems' prior consent, in any form of packaging or cover other than that in which it was produced.  No part of this manual or accompanying documentation, may be reproduced, stored in a retrieval system on optical or magnetic disk, tape, CD, DVD or other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying recording, or otherwise for any purpose other than for the purchaser's personal use without a legal agreement or other written permission granted by Cadence.

This product should not be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation, or communication of aircraft or ground support equipment. Cadence Design Systems, Inc., shall not be liable, in whole or in part, for any claims arising from such use, including death, bankruptcy or outbreak of war.

Windows is a registered trademark of Microsoft Corporation.  Apple, OS X, macOS, and Macintosh are registered trademarks of Apple Inc. UNIX is a registered trademark of the Open Group.  Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. SUSE, SLED, and SLES are registered trademarks of Novell, Inc. Ubuntu is a registered trademark of Canonical Ltd.

SYBYL is a registered trademark of Certara, L.P. MDL, BIOVIA and ISIS are registered trademarks of Dassault Systemes and/or its affiliates. SMARTS and SMIRKS are registered trademarks of Daylight Chemical Information Systems, Inc. MacroModel is a registered trademark of Schrodinger, LLC.

Python is a registered trademark of the Python Software Foundation. Django is a registered trademark of the Django Software Foundation. Java is a registered trademark of Oracle and/or its affiliates.

Other products and software packages referenced in this document are trademarks and registered trademarks of their respective vendors or manufacturers.


    ================
Sample Code
================

For all of the code examples and samples within
documents published by OpenEye, Cadence Molecular Sciences,
the following terms of use apply.

TERMS FOR USE OF SAMPLE CODE

The software below ("Sample Code") is
provided to current licensees or subscribers of Cadence products or
SaaS offerings (each a "Customer"). Customer is hereby permitted to use,
copy, and modify the Sample Code,
subject to these terms. Cadence claims no rights to Customer's
modifications. Modification of Sample Code is at Customer's sole and
exclusive risk. Sample Code may require Customer to have a then
current license or subscription to the applicable Cadence offering.

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.  CADENCE DISCLAIMS ALL WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. In no event shall Cadence be
liable for any damages or liability in connection with the Sample Code
or its use.

    ===========
Citation
===========

Please follow the guidelines in this document to cite use of our products in research publications and other documents.

For more information, please contact `OpenEye Support <mailto:support@openeye.com>`_.

Orion\ :sup:`®`
=====================

To cite use of Orion, please use the following::

    Orion <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Orion 2025.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The version number for Orion appears in the product's release notes, for example,
https://docs.eyesopen.com/orion-user-interface/releasenotes/index.html.

Orion Floes
=====================

To cite use of an Orion-based floe package, please use the following::

    OpenEye <package-name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Large-Scale Floes 4.2.3. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.


The version number for a floe package is displayed on the first page of the package's release notes.  For
example: https://docs.eyesopen.com/floe/modules/large_scale_floes/docs/source/releasenotes_2025_1.html.

Toolkits and Applications
==========================

To cite OpenEye toolkits or applications used in your work, please use the following::

    OpenEye Toolkits [or Applications] <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    OpenEye Toolkits 2024.2.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.



..  explicit URL used below because labels are too complicated to maintain across releases

The Applications and Toolkits are released as a package, multiple times per year.  The first
part of the version number designates the calendar year.  `The version number appears on the summary
document for the package <https://docs.eyesopen.com/applications/index.html>`_.


If you want to cite an individual application or toolkit, you can use the syntax::

    <product name> <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

where *<product name>* is:

* Bioisostere TK
* OEChem TK
* OEDepict TK
* OEDocking TK
* OEFF TK
* Eon TK
* FastROCS TK
* Grapheme TK
* GraphSim TK
* Lexichem TK
* OEMedChem TK
* MolProp TK
* Omega TK
* Quacpac TK
* Shape TK
* Spicoli TK
* Spruce TK
* Szmap TK
* Szybki TK
* Zap TK

*   AFITT Application
*   BROOD Application
*   OEDocking Application
*   EON Application
*   OMEGA Application
*   PICTO Application
*   pKa-Prospector Application
*   QUACPAC Application
*   ROCS Application
*   SiteHopper Application
*   SPRUCE Application
*   SZMAP Application
*   SZYBKI Application
*   VIDA Application

You can use the version number of the individual Application or Toolkit.   For example::

    SZYBKI Application 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    Szybki TK 2.8.0.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

The first documentation pages give the product names and version numbers, as in https://docs.eyesopen.com/applications/szybki/index.html and
https://docs.eyesopen.com/toolkits/python/szybkitk/index.html.

Publications for Bibliographies
=================================

Please also cite these publications if the corresponding product was used in your research.

Orion
-----------

Sørensen, J., Bannan, C.C., Calabrò, G., Jain, V., Ovanesyan, G., Smith, A.,
Zhang, S., Bayly, C.I., Darden, T.A., Geballe, M.T., LeBard, D.N.,
McGann, M., Moon, J.B., Muddana, H.S., Shewmaker, A., LaFon, J.,
Tolbert, R.W., Skillman, A.G., Nicholls, A.
Orion\ ® A Cloud-Native Molecular Design Platform.
In *Computational Drug Discovery*. V. Poongavanam and V. Ramaswamy, Eds. Wiley-VCH, 2024; pp. 579–615.
DOI: 10.1002/9783527840748.ch24

AFITT and FLYNN Applications
----------------------------------

Wlodek, S.; Skillman, A.G.; Nicholls, A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
*Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
DOI: 10.1107/s0907444906016076

OEDocking Application and Toolkit
------------------------------------

Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

OMEGA Application and Toolkit
---------------------------------

If you are using OMEGA in torsion driving mode, please cite the following two publications.

Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer
Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the
Protein Databank and the Cambridge Structural
Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

Hawkins, P.C.D. and Nicholls, A.  Conformer
Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
*J. Chem. Inf. Model.* **2012**, *52* (11), 2919–2936. DOI: /10.1021/ci300314k

If you are using OMEGA in macrocyle mode, please cite the following.

Hawkins, P.C.D. and Wlodek, S. Decisions with Confidence: Application to the Conformation Sampling of
Molecules in the Solid State. *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
DOI: /10.1021/acs.jcim.0c00358


ROCS Application
------------------

Hawkins, P.C.D.; Skillman, A.G.; Nicholls, A. Comparison of Shape-Matching and Docking
as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365



OpenEye MMDS Web Service
============================

To cite use of the Macromolecular Data Service (MMDS) web service, please use the syntax::

    Macromolecular Data Service <version-number>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

For example::

    Macromolecular Data Service 1.1. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

`The MMDS version number appears on the web service's release notes <https://docs.eyesopen.com/webservices/mmds/releasenotes/index.html>`_.


    ======================
Technology Licensing
======================

OpenEye products use the following technology under license.

Some of the open source technologies we use are licensed under the GNU Public License (GPL)
version 2 or 3. In all instances, these technologies are communicated with using the
"at arms length" principle, using pipes and command line arguments.

While the software is in some instances assembled into a container,
that assembly does not invoke the GPL copyleft scope. For each Floe package where these are
used, the environment log clearly details the installed programs and their version numbers.
With the links below for each technology, the source for each of those programs is available.

..  csv-table:: Licensed Technology
    :header-rows: 1
    :widths: auto
    :file: 3rd_party_license_attribution.csv

    GCC
================================================================================

On the Linux platform, The OpenEye toolkits are linked with the GCC libraries
using an eligible compilation process under the terms of the
GCC RUNTIME LIBRARY EXCEPTION (see below).

The OpenEye toolkits are NOT open source software and are NOT governed by GPL
or other open source licenses. Your right to use the toolkits are governed by
the OpenEye license which is binding to You.

For certain Linux distributions, GCC library components are included as object
files.  Your rights to use GCC library components (libstdc++, libgcc, and
libgomp) included with these distributions are governed by the GPLv3 license as
follows:

The components libstdc++, libgcc, and libgomp are part of GCC.

* GCC is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

* GCC is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GCC (see below).  If not, see `Licenses GNU Project  <http://www.gnu.org/licenses/>`_ .

Per GPLv3, section 6d, the source for GCC is available for download from the
following location: `GNU  <http://gcc.gnu.org>`_.  The GCC library components
included here are from version gcc-4.9.3 and are built using the standard
instructions at `Installing GCC <http://gcc.gnu.org/install/>`_.



GCC RUNTIME LIBRARY EXCEPTION
---------------------------------

:: 

   Version 3.1, 31 March 2009

   Copyright © 2009 Free Software Foundation, Inc. http://fsf.org/

   Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

   This GCC Runtime Library Exception ("Exception") is an additional permission under section 7 of the GNU General Public License, 
   version 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that bears a notice placed by the copyright holder 
   of the file stating that the file is governed by GPLv3 along with this Exception.

   When you use GCC to compile a program, GCC may combine portions of certain GCC header files and runtime libraries with 
   the compiled program. The purpose of this Exception is to allow compilation of non-GPL (including proprietary) programs 
   to use, in this way, the header files and runtime libraries covered by this Exception.

   0. Definitions.

   A file is an "Independent Module" if it either requires the Runtime Library for execution after a Compilation Process, 
   or makes use of an interface provided by the Runtime Library, but is not otherwise based on the Runtime Library.

   "GCC" means a version of the GNU Compiler Collection, with or without modifications, governed by version 3 (or a specified 
   later version) of the GNU General Public License (GPL) with the option of using any subsequent versions published by the FSF.

   "GPL-compatible Software" is software whose conditions of propagation, modification and use would permit combination with 
   GCC in accord with the license of GCC.

   "Target Code" refers to output from any compiler for a real or virtual target processor architecture, in executable 
   form or suitable for input to an assembler, loader, linker and/or execution phase. Notwithstanding that, Target Code 
   does not include data in any format that is used as a compiler intermediate representation, or used for producing a 
   compiler intermediate representation.

   The "Compilation Process" transforms code entirely represented in non-intermediate languages designed for human-written 
   code, and/or in Java Virtual Machine byte code, into Target Code. Thus, for example, use of source code generators and 
   preprocessors need not be considered part of the Compilation Process, since the Compilation Process can be understood 
   as starting with the output of the generators or preprocessors.

   A Compilation Process is "Eligible" if it is done using GCC, alone or with other GPL-compatible software, or if it is 
   done without using any work based on GCC. For example, using non-GPL-compatible Software to optimize any GCC intermediate 
   representations would not qualify as an Eligible Compilation Process.

   1. Grant of Additional Permission.

   You have permission to propagate a work of Target Code formed by combining the Runtime Library with Independent Modules, 
   even if such propagation would otherwise violate the terms of GPLv3, provided that all Target Code was generated by 
   Eligible Compilation Processes. You may then convey such a combination under terms of your choice, consistent with the 
   licensing of the Independent Modules.

   2. No Weakening of GCC Copyleft.

   The availability of this Exception does not imply any general presumption that third-party software is unaffected by 
   the copyleft requirements of the license of GCC.

.. seealso::

   * http://www.gnu.org/licenses/gcc-exception.html



GNU GENERAL PUBLIC LICENSE
----------------------------


::

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
   Everyone is permitted to copy and distribute verbatim copies
   of this license document, but changing it is not allowed.

                            Preamble

   The GNU General Public License is a free, copyleft license for
   software and other kinds of works.

     The licenses for most software and other practical works are designed
   to take away your freedom to share and change the works.  By contrast,
   the GNU General Public License is intended to guarantee your freedom to
   share and change all versions of a program--to make sure it remains free
   software for all its users.  We, the Free Software Foundation, use the
   GNU General Public License for most of our software; it applies also to
   any other work released this way by its authors.  You can apply it to
   your programs, too.

     When we speak of free software, we are referring to freedom, not
   price.  Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   them if you wish), that you receive source code or can get it if you
   want it, that you can change the software or use pieces of it in new
   free programs, and that you know you can do these things.

     To protect your rights, we need to prevent others from denying you
   these rights or asking you to surrender the rights.  Therefore, you have
   certain responsibilities if you distribute copies of the software, or if
   you modify it: responsibilities to respect the freedom of others.

     For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must pass on to the recipients the same
   freedoms that you received.  You must make sure that they, too, receive
   or can get the source code.  And you must show them these terms so they
   know their rights.

     Developers that use the GNU GPL protect your rights with two steps:
   (1) assert copyright on the software, and (2) offer you this License
   giving you legal permission to copy, distribute and/or modify it.

     For the developers' and authors' protection, the GPL clearly explains
   that there is no warranty for this free software.  For both users' and
   authors' sake, the GPL requires that modified versions be marked as
   changed, so that their problems will not be attributed erroneously to
   authors of previous versions.

     Some devices are designed to deny users access to install or run
   modified versions of the software inside them, although the manufacturer
   can do so.  This is fundamentally incompatible with the aim of
   protecting users' freedom to change the software.  The systematic
   pattern of such abuse occurs in the area of products for individuals to
   use, which is precisely where it is most unacceptable.  Therefore, we
   have designed this version of the GPL to prohibit the practice for those
   products.  If such problems arise substantially in other domains, we
   stand ready to extend this provision to those domains in future versions
   of the GPL, as needed to protect the freedom of users.

     Finally, every program is threatened constantly by software patents.
   States should not allow patents to restrict development and use of
   software on general-purpose computers, but in those that do, we wish to
   avoid the special danger that patents applied to a free program could
   make it effectively proprietary.  To prevent this, the GPL assures that
   patents cannot be used to render the program non-free.

     The precise terms and conditions for copying, distribution and
   modification follow.

                       TERMS AND CONDITIONS

     0. Definitions.

     "This License" refers to version 3 of the GNU General Public License.

     "Copyright" also means copyright-like laws that apply to other kinds of
   works, such as semiconductor masks.

     "The Program" refers to any copyrightable work licensed under this
   License.  Each licensee is addressed as "you".  "Licensees" and
   "recipients" may be individuals or organizations.

     To "modify" a work means to copy from or adapt all or part of the work
   in a fashion requiring copyright permission, other than the making of an
   exact copy.  The resulting work is called a "modified version" of the
   earlier work or a work "based on" the earlier work.

     A "covered work" means either the unmodified Program or a work based
   on the Program.

     To "propagate" a work means to do anything with it that, without
   permission, would make you directly or secondarily liable for
   infringement under applicable copyright law, except executing it on a
   computer or modifying a private copy.  Propagation includes copying,
   distribution (with or without modification), making available to the
   public, and in some countries other activities as well.

     To "convey" a work means any kind of propagation that enables other
   parties to make or receive copies.  Mere interaction with a user through
   a computer network, with no transfer of a copy, is not conveying.

     An interactive user interface displays "Appropriate Legal Notices"
   to the extent that it includes a convenient and prominently visible
   feature that (1) displays an appropriate copyright notice, and (2)
   tells the user that there is no warranty for the work (except to the
   extent that warranties are provided), that licensees may convey the
   work under this License, and how to view a copy of this License.  If
   the interface presents a list of user commands or options, such as a
   menu, a prominent item in the list meets this criterion.

     1. Source Code.

     The "source code" for a work means the preferred form of the work
   for making modifications to it.  "Object code" means any non-source
   form of a work.

     A "Standard Interface" means an interface that either is an official
   standard defined by a recognized standards body, or, in the case of
   interfaces specified for a particular programming language, one that
   is widely used among developers working in that language.

     The "System Libraries" of an executable work include anything, other
   than the work as a whole, that (a) is included in the normal form of
   packaging a Major Component, but which is not part of that Major
   Component, and (b) serves only to enable use of the work with that
   Major Component, or to implement a Standard Interface for which an
   implementation is available to the public in source code form.  A
   "Major Component", in this context, means a major essential component
   (kernel, window system, and so on) of the specific operating system
   (if any) on which the executable work runs, or a compiler used to
   produce the work, or an object code interpreter used to run it.

     The "Corresponding Source" for a work in object code form means all
   the source code needed to generate, install, and (for an executable
   work) run the object code and to modify the work, including scripts to
   control those activities.  However, it does not include the work's
   System Libraries, or general-purpose tools or generally available free
   programs which are used unmodified in performing those activities but
   which are not part of the work.  For example, Corresponding Source
   includes interface definition files associated with source files for
   the work, and the source code for shared libraries and dynamically
   linked subprograms that the work is specifically designed to require,
   such as by intimate data communication or control flow between those
   subprograms and other parts of the work.

     The Corresponding Source need not include anything that users
   can regenerate automatically from other parts of the Corresponding
   Source.

     The Corresponding Source for a work in source code form is that
   same work.

     2. Basic Permissions.

     All rights granted under this License are granted for the term of
   copyright on the Program, and are irrevocable provided the stated
   conditions are met.  This License explicitly affirms your unlimited
   permission to run the unmodified Program.  The output from running a
   covered work is covered by this License only if the output, given its
   content, constitutes a covered work.  This License acknowledges your
   rights of fair use or other equivalent, as provided by copyright law.

     You may make, run and propagate covered works that you do not
   convey, without conditions so long as your license otherwise remains
   in force.  You may convey covered works to others for the sole purpose
   of having them make modifications exclusively for you, or provide you
   with facilities for running those works, provided that you comply with
   the terms of this License in conveying all material for which you do
   not control copyright.  Those thus making or running the covered works
   for you must do so exclusively on your behalf, under your direction
   and control, on terms that prohibit them from making any copies of
   your copyrighted material outside their relationship with you.

     Conveying under any other circumstances is permitted solely under
   the conditions stated below.  Sublicensing is not allowed; section 10
   makes it unnecessary.

     3. Protecting Users' Legal Rights From Anti-Circumvention Law.

     No covered work shall be deemed part of an effective technological
   measure under any applicable law fulfilling obligations under article
   11 of the WIPO copyright treaty adopted on 20 December 1996, or
   similar laws prohibiting or restricting circumvention of such
   measures.

     When you convey a covered work, you waive any legal power to forbid
   circumvention of technological measures to the extent such circumvention
   is effected by exercising rights under this License with respect to
   the covered work, and you disclaim any intention to limit operation or
   modification of the work as a means of enforcing, against the work's
   users, your or third parties' legal rights to forbid circumvention of
   technological measures.

     4. Conveying Verbatim Copies.

     You may convey verbatim copies of the Program's source code as you
   receive it, in any medium, provided that you conspicuously and
   appropriately publish on each copy an appropriate copyright notice;
   keep intact all notices stating that this License and any
   non-permissive terms added in accord with section 7 apply to the code;
   keep intact all notices of the absence of any warranty; and give all
   recipients a copy of this License along with the Program.


     You may charge any price or no price for each copy that you convey,
   and you may offer support or warranty protection for a fee.

     5. Conveying Modified Source Versions.

     You may convey a work based on the Program, or the modifications to
   produce it from the Program, in the form of source code under the
   terms of section 4, provided that you also meet all of these conditions:

      a) The work must carry prominent notices stating that you modified
      it, and giving a relevant date.

      b) The work must carry prominent notices stating that it is
      released under this License and any conditions added under section
      7.  This requirement modifies the requirement in section 4 to
      "keep intact all notices".

      c) You must license the entire work, as a whole, under this
      License to anyone who comes into possession of a copy.  This
      License will therefore apply, along with any applicable section 7
      additional terms, to the whole of the work, and all its parts,
      regardless of how they are packaged.  This License gives no
      permission to license the work in any other way, but it does not
      invalidate such permission if you have separately received it.

      d) If the work has interactive user interfaces, each must display
      Appropriate Legal Notices; however, if the Program has interactive
      interfaces that do not display Appropriate Legal Notices, your
      work need not make them do so.

     A compilation of a covered work with other separate and independent
   works, which are not by their nature extensions of the covered work,
   and which are not combined with it such as to form a larger program,
   in or on a volume of a storage or distribution medium, is called an
   "aggregate" if the compilation and its resulting copyright are not
   used to limit the access or legal rights of the compilation's users
   beyond what the individual works permit.  Inclusion of a covered work
   in an aggregate does not cause this License to apply to the other
   parts of the aggregate.

     6. Conveying Non-Source Forms.

     You may convey a covered work in object code form under the terms
   of sections 4 and 5, provided that you also convey the
   machine-readable Corresponding Source under the terms of this License,
   in one of these ways:

     a) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by the
     Corresponding Source fixed on a durable physical medium
     customarily used for software interchange.

     b) Convey the object code in, or embodied in, a physical product
     (including a physical distribution medium), accompanied by a
     written offer, valid for at least three years and valid for as
     long as you offer spare parts or customer support for that product
     model, to give anyone who possesses the object code either (1) a
     copy of the Corresponding Source for all the software in the
     product that is covered by this License, on a durable physical
     medium customarily used for software interchange, for a price no
     more than your reasonable cost of physically performing this
     conveying of source, or (2) access to copy the
     Corresponding Source from a network server at no charge.

     c) Convey individual copies of the object code with a copy of the
     written offer to provide the Corresponding Source.  This
     alternative is allowed only occasionally and noncommercially, and
     only if you received the object code with such an offer, in accord
     with subsection 6b.

     d) Convey the object code by offering access from a designated
     place (gratis or for a charge), and offer equivalent access to the
     Corresponding Source in the same way through the same place at no
     further charge.  You need not require recipients to copy the
     Corresponding Source along with the object code.  If the place to
     copy the object code is a network server, the Corresponding Source
     may be on a different server (operated by you or a third party)
     that supports equivalent copying facilities, provided you maintain
     clear directions next to the object code saying where to find the
     Corresponding Source.  Regardless of what server hosts the
     Corresponding Source, you remain obligated to ensure that it is
     available for as long as needed to satisfy these requirements.

     e) Convey the object code using peer-to-peer transmission, provided
     you inform other peers where the object code and Corresponding
     Source of the work are being offered to the general public at no
     charge under subsection 6d.

    A separable portion of the object code, whose source code is excluded
  from the Corresponding Source as a System Library, need not be
  included in conveying the object code work.

    A "User Product" is either (1) a "consumer product", which means any
  tangible personal property which is normally used for personal, family,
  or household purposes, or (2) anything designed or sold for incorporation
  into a dwelling.  In determining whether a product is a consumer product,
  doubtful cases shall be resolved in favor of coverage.  For a particular
  product received by a particular user, "normally used" refers to a
  typical or common use of that class of product, regardless of the status
  of the particular user or of the way in which the particular user
  actually uses, or expects or is expected to use, the product.  A product
  is a consumer product regardless of whether the product has substantial
  commercial, industrial or non-consumer uses, unless such uses represent
  the only significant mode of use of the product.

    "Installation Information" for a User Product means any methods,
  procedures, authorization keys, or other information required to install
  and execute modified versions of a covered work in that User Product from
  a modified version of its Corresponding Source.  The information must
  suffice to ensure that the continued functioning of the modified object
  code is in no case prevented or interfered with solely because
  modification has been made.

    If you convey an object code work under this section in, or with, or
  specifically for use in, a User Product, and the conveying occurs as
  part of a transaction in which the right of possession and use of the
  User Product is transferred to the recipient in perpetuity or for a
  fixed term (regardless of how the transaction is characterized), the
  Corresponding Source conveyed under this section must be accompanied
  by the Installation Information.  But this requirement does not apply
  if neither you nor any third party retains the ability to install
  modified object code on the User Product (for example, the work has
  been installed in ROM).

    The requirement to provide Installation Information does not include a
  requirement to continue to provide support service, warranty, or updates
  for a work that has been modified or installed by the recipient, or for
  the User Product in which it has been modified or installed.  Access to a
  network may be denied when the modification itself materially and
  adversely affects the operation of the network or violates the rules and
  protocols for communication across the network.

    Corresponding Source conveyed, and Installation Information provided,
  in accord with this section must be in a format that is publicly
  documented (and with an implementation available to the public in
  source code form), and must require no special password or key for
  unpacking, reading or copying.

    7. Additional Terms.

    "Additional permissions" are terms that supplement the terms of this
  License by making exceptions from one or more of its conditions.
  Additional permissions that are applicable to the entire Program shall
  be treated as though they were included in this License, to the extent
  that they are valid under applicable law.  If additional permissions
  apply only to part of the Program, that part may be used separately
  under those permissions, but the entire Program remains governed by
  this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option
  remove any additional permissions from that copy, or from any part of
  it.  (Additional permissions may be written to require their own
  removal in certain cases when you modify the work.)  You may place
  additional permissions on material, added by you to a covered work,
  for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you
  add to a covered work, you may (if authorized by the copyright holders of
  that material) supplement the terms of this License with terms:

      a) Disclaiming warranty or limiting liability differently from the
      terms of sections 15 and 16 of this License; or

      b) Requiring preservation of specified reasonable legal notices or
      author attributions in that material or in the Appropriate Legal
      Notices displayed by works containing it; or

      c) Prohibiting misrepresentation of the origin of that material, or
      requiring that modified versions of such material be marked in
      reasonable ways as different from the original version; or

      d) Limiting the use for publicity purposes of names of licensors or
      authors of the material; or

      e) Declining to grant rights under trademark law for use of some
      trade names, trademarks, or service marks; or

      f) Requiring indemnification of licensors and authors of that
      material by anyone who conveys the material (or modified versions of
      it) with contractual assumptions of liability to the recipient, for
      any liability that these contractual assumptions directly impose on
      those licensors and authors.

     All other non-permissive additional terms are considered "further
   restrictions" within the meaning of section 10.  If the Program as you
   received it, or any part of it, contains a notice stating that it is
   governed by this License along with a term that is a further
   restriction, you may remove that term.  If a license document contains
   a further restriction but permits relicensing or conveying under this
   License, you may add to a covered work material governed by the terms
   of that license document, provided that the further restriction does
   not survive such relicensing or conveying.

     If you add terms to a covered work in accord with this section, you
   must place, in the relevant source files, a statement of the
   additional terms that apply to those files, or a notice indicating
   where to find the applicable terms.

     Additional terms, permissive or non-permissive, may be stated in the
   form of a separately written license, or stated as exceptions;
   the above requirements apply either way.

     8. Termination.

     You may not propagate or modify a covered work except as expressly
   provided under this License.  Any attempt otherwise to propagate or
   modify it is void, and will automatically terminate your rights under
   this License (including any patent licenses granted under the third
   paragraph of section 11).

     However, if you cease all violation of this License, then your
   license from a particular copyright holder is reinstated (a)
   provisionally, unless and until the copyright holder explicitly and
   finally terminates your license, and (b) permanently, if the copyright
   holder fails to notify you of the violation by some reasonable means
   prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
   reinstated permanently if the copyright holder notifies you of the
   violation by some reasonable means, this is the first time you have
   received notice of violation of this License (for any work) from that
   copyright holder, and you cure the violation prior to 30 days after
   your receipt of the notice.

     Termination of your rights under this section does not terminate the
   licenses of parties who have received copies or rights from you under
   this License.  If your rights have been terminated and not permanently
   reinstated, you do not qualify to receive new licenses for the same
   material under section 10.

     9. Acceptance Not Required for Having Copies.

     You are not required to accept this License in order to receive or
   run a copy of the Program.  Ancillary propagation of a covered work
   occurring solely as a consequence of using peer-to-peer transmission
   to receive a copy likewise does not require acceptance.  However,
   nothing other than this License grants you permission to propagate or
   modify any covered work.  These actions infringe copyright if you do
   not accept this License.  Therefore, by modifying or propagating a
   covered work, you indicate your acceptance of this License to do so.

     10. Automatic Licensing of Downstream Recipients.

     Each time you convey a covered work, the recipient automatically
   receives a license from the original licensors, to run, modify and
   propagate that work, subject to this License.  You are not responsible
   for enforcing compliance by third parties with this License.

     An "entity transaction" is a transaction transferring control of an
   organization, or substantially all assets of one, or subdividing an
   organization, or merging organizations.  If propagation of a covered
   work results from an entity transaction, each party to that
   transaction who receives a copy of the work also receives whatever
   licenses to the work the party's predecessor in interest had or could
   give under the previous paragraph, plus a right to possession of the
   Corresponding Source of the work from the predecessor in interest, if
   the predecessor has it or can get it with reasonable efforts.

     You may not impose any further restrictions on the exercise of the
   rights granted or affirmed under this License.  For example, you may
   not impose a license fee, royalty, or other charge for exercise of
   rights granted under this License, and you may not initiate litigation
   (including a cross-claim or counterclaim in a lawsuit) alleging that
   any patent claim is infringed by making, using, selling, offering for
   sale, or importing the Program or any portion of it.

     11. Patents.

     A "contributor" is a copyright holder who authorizes use under this
   License of the Program or a work on which the Program is based.  The
   work thus licensed is called the contributor's "contributor version".

     A contributor's "essential patent claims" are all patent claims
   owned or controlled by the contributor, whether already acquired or
   hereafter acquired, that would be infringed by some manner, permitted
   by this License, of making, using, or selling its contributor version,
   but do not include claims that would be infringed only as a
   consequence of further modification of the contributor version.  For
   purposes of this definition, "control" includes the right to grant
   patent sublicenses in a manner consistent with the requirements of
   this License.

     Each contributor grants you a non-exclusive, worldwide, royalty-free
   patent license under the contributor's essential patent claims, to
   make, use, sell, offer for sale, import and otherwise run, modify and
   propagate the contents of its contributor version.

     In the following three paragraphs, a "patent license" is any express
   agreement or commitment, however denominated, not to enforce a patent
   (such as an express permission to practice a patent or covenant not to
   sue for patent infringement).  To "grant" such a patent license to a
   party means to make such an agreement or commitment not to enforce a
   patent against the party.

     If you convey a covered work, knowingly relying on a patent license,
   and the Corresponding Source of the work is not available for anyone
   to copy, free of charge and under the terms of this License, through a
   publicly available network server or other readily accessible means,
   then you must either (1) cause the Corresponding Source to be so
   available, or (2) arrange to deprive yourself of the benefit of the
   patent license for this particular work, or (3) arrange, in a manner
   consistent with the requirements of this License, to extend the patent
   license to downstream recipients.  "Knowingly relying" means you have
   actual knowledge that, but for the patent license, your conveying the
   covered work in a country, or your recipient's use of the covered work
   in a country, would infringe one or more identifiable patents in that
   country that you have reason to believe are valid.

     If, pursuant to or in connection with a single transaction or
   arrangement, you convey, or propagate by procuring conveyance of, a
   covered work, and grant a patent license to some of the parties
   receiving the covered work authorizing them to use, propagate, modify
   or convey a specific copy of the covered work, then the patent license
   you grant is automatically extended to all recipients of the covered
   work and works based on it.

     A patent license is "discriminatory" if it does not include within
   the scope of its coverage, prohibits the exercise of, or is
   conditioned on the non-exercise of one or more of the rights that are
   specifically granted under this License.  You may not convey a covered
   work if you are a party to an arrangement with a third party that is
   in the business of distributing software, under which you make payment
   to the third party based on the extent of your activity of conveying
   the work, and under which the third party grants, to any of the
   parties who would receive the covered work from you, a discriminatory
   patent license (a) in connection with copies of the covered work
   conveyed by you (or copies made from those copies), or (b) primarily
   for and in connection with specific products or compilations that
   contain the covered work, unless you entered into that arrangement,
   or that patent license was granted, prior to 28 March 2007.

     Nothing in this License shall be construed as excluding or limiting
   any implied license or other defenses to infringement that may
   otherwise be available to you under applicable patent law.

     12. No Surrender of Others' Freedom.

     If conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License.  If you cannot convey a
   covered work so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you may
   not convey it at all.  For example, if you agree to terms that obligate you
   to collect a royalty for further conveying from those to whom you convey
   the Program, the only way you could satisfy both those terms and this
   License would be to refrain entirely from conveying the Program.

     13. Use with the GNU Affero General Public License.

     Notwithstanding any other provision of this License, you have
   permission to link or combine any covered work with a work licensed
   under version 3 of the GNU Affero General Public License into a single
   combined work, and to convey the resulting work.  The terms of this
   License will continue to apply to the part which is the covered work,
   but the special requirements of the GNU Affero General Public License,
   section 13, concerning interaction through a network will apply to the
   combination as such.

     14. Revised Versions of this License.

     The Free Software Foundation may publish revised and/or new versions of
   the GNU General Public License from time to time.  Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

     Each version is given a distinguishing version number.  If the
   Program specifies that a certain numbered version of the GNU General
   Public License "or any later version" applies to it, you have the
   option of following the terms and conditions either of that numbered
   version or of any later version published by the Free Software
   Foundation.  If the Program does not specify a version number of the
   GNU General Public License, you may choose any version ever published
   by the Free Software Foundation.

     If the Program specifies that a proxy can decide which future
   versions of the GNU General Public License can be used, that proxy's
   public statement of acceptance of a version permanently authorizes you
   to choose that version for the Program.

     Later license versions may give you additional or different
   permissions.  However, no additional obligations are imposed on any
   author or copyright holder as a result of your choosing to follow a
   later version.

     15. Disclaimer of Warranty.

     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

     16. Limitation of Liability.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.

     17. Interpretation of Sections 15 and 16.

     If the disclaimer of warranty and limitation of liability provided
   above cannot be given local legal effect according to their terms,
   reviewing courts shall apply local law that most closely approximates
   an absolute waiver of all civil liability in connection with the
   Program, unless a warranty or assumption of liability accompanies a
   copy of the Program in return for a fee.

			END OF TERMS AND CONDITIONS

	       How to Apply These Terms to Your New Programs

     If you develop a new program, and you want it to be of the greatest
   possible use to the public, the best way to achieve this is to make it
   free software which everyone can redistribute and change under these terms.

     To do so, attach the following notices to the program.  It is safest
   to attach them to the start of each source file to most effectively
   state the exclusion of warranty; and each file should have at least
   the "copyright" line and a pointer to where the full notice is found.

       <one line to give the program's name and a brief idea of what it does.>
       Copyright (C) <year>  <name of author>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

   Also add information on how to contact you by electronic and paper mail.

     If the program does terminal interaction, make it output a short
   notice like this when it starts in an interactive mode:

       <program>  Copyright (C) <year>  <name of author>
       This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
       This is free software, and you are welcome to redistribute it
       under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the appropriate
   parts of the General Public License.  Of course, your program's commands
   might be different; for a GUI interface, you would use an "about box".

     You should also get your employer (if you work as a programmer) or school,
   if any, to sign a "copyright disclaimer" for the program, if necessary.
   For more information on this, and how to apply and follow the GNU GPL, see
   <http://www.gnu.org/licenses/>.

     The GNU General Public License does not permit incorporating your program
   into proprietary programs.  If your program is a subroutine library, you
   may consider it more useful to permit linking proprietary applications with
   the library.  If this is what you want to do, use the GNU Lesser General
   Public License instead of this License.  But first, please read
   <http://www.gnu.org/philosophy/why-not-lgpl.html>.


.. seealso::

   * http://www.gnu.org/licenses/gpl.txt





.. _introduction:

************
Introduction
************

..  toctree::

    general_concepts.rst

    scope.rst

    layout.rst

    undo.rst

    mouse_maps.rst

    user_dir.rst

    help.rst

.. _general_concepts:


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


General Concepts
================

There are some key concepts that are helpful for understanding how to interact
with |product|.  Individual objects in |product| can be in various states,
including *Focused*, *Visible*, *Locked*, *Marked*, and *Selected*.  Each of 
these states carries some special behaviors which are described below.  These
states also provide a way to refer to specific molecules or sets of molecules.
For example, one could apply a coloring scheme or rendering style to all 
*Marked* objects, or to the *Focused* object.

|product's| "Scope" determines which objects will be affected by operations 
within the program, based on their states, and is discussed in the "Scope"
section below.

Focused State
-------------

The *Focused* state is a property of a single object in the application; 
there can be only one *Focused* object at any given time. Being 
*Focused* indicates that that particular object is the current object of 
interest and is therefore the primary focus of all relevant windows. If the 
*Focused* object is not already *Visible* (see below), it will behave as if 
it were *Visible* for as long as it remains *Focused*.

In addition, when a molecule is the *Focused* object, its SMILES 
representation is displayed in the application's status bar (which can be found
at the bottom of the application window). If any of the molecule's atoms are
selected, that selection will be indicated in the SMILES display by the 
coloring of relevant atoms. Selected atoms are colored using the current
selection color (the default is orange) and are also in a bolded font while
all of the unselected atoms will be displayed in their usual normal black font.

For large molecules (>100 atoms in this case), no SMILES representation is
displayed as it would not fit in the status bar.

Visible State
-------------

The *Visible* state is an indicator of whether or not the associated 
object is drawn in the 3D display. Multiple objects can be *Visible* 
simultaneously. If |product| is operating in tiled mode (see 
:ref:`display_3d_tiled`), each *Visible* object will be displayed in its own 
individual pane.

If the 2D display is also shown and |product| is in
tiled mode, *Visible* molecules will be drawn in the 2D display as well as 
the 3D display. 

Locked State
------------

The *Locked* state is essentially the same as the *Visible* state 
except in the situation
where the application is in tiled mode, in which case each *Locked* object
will be displayed in every pane of the 3D display. However, a *Locked* 
object can also be simultaneously *Visible* and/or *Focused* in which case it will be 
displayed in its own individual pane as well as every other pane in the 3D 
display.

Marked State
------------

The *Marked* state is simply an indicator of user interest in the 
associated object. The *Marked* state can be used to help filter data as 
well as to specify the desired input to application functions. For instance,
the *Marked* state can be used to specify which molecules out of a large
list are saved. Finally, when certain operations generate too many results to 
be displayed at one time, the *Marked* state can be used to indicate the 
results of those operations.

Selected State
--------------

The *Selected* state is a special property of the *Visible* state. Only objects 
that are *Visible*, *Focused*, or *Locked* can be *Selected*. Much like the 
*Marked* state, the *Selected* state is an indicator of interest and provides an 
input set to application functions. Unlike, the *Marked* state, the *Selected* 
state is more transient and is easily cleared. The act of *selection* is 
usually performed in either the 3D or 2D display. Selected objects are usually 
indicated by a change of color (the default is orange) in the 2D display, and
by a colored outline in the 3D display.  More 
details on the actual process of selection can be found in the chapters on 3D 
and 2D displays.




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


Scope
=====

Scope is a state of |product|, and indicates which objects the application 
should operate on. The default application scope is *Focused* which means 
that all of the application functions will operate on the *Focused* object.

.. _figure_scopes:

.. figure:: /_images/scopes.png
   :scale:  100
   :align:  center
   
   **Scope Order of Precedence**

However, as seen in :ref:`Figure: Scope Order of Precedence<figure_scopes>`, 
if there is anything currently *Selected*, the 
selected set will take precedence over the current scope *i.e.* the action will apply
only to the selected atoms/objects. Furthermore, in 
*Focused* scope, if there is no *Selected* set and no *Focused* object, the 
*Focused* scope defaults to behaving as if it were the *Visible* scope. 

The *Visible* scope operates on all objects that are currently *Visible*, 
*Locked*, and/or *Focused*.

The *Marked* scope operates on all objects that are currently *Marked*.

The *All* scope operates on every object currently loaded in the 
application. Operating on the *All* scope can be a very lengthy process, 
and as such, its progress is displayed in the progress bar in lower right hand
corner of the application. Operations performed on the *All* scope can
be halted if desired by clicking on the *Stop* button immediately to the
left of the progress bar.

The current scope is displayed in and can be modified from the main application 
toolbar as seen in the figure below.

.. _figure_scopes_toolbar:

.. figure:: /_images/scope_toolbar.png
   :scale: 100
   :align: center
   
   **Scope Toolbar Control**




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


Layout
======

The layout of the application should be relatively familiar to most users. 
|product| provides a menu bar with many standard as well as specific menus, a 
toolbar for common operations, a central main window, and a number of 
peripheral windows. An example of the layout can be seen in 
:ref:`Figure: Docked Layout<figure_applayout>`.

.. _figure_applayout:

.. figure:: /_images/applayout.png
   :scale:  50
   :align: center
   
   **Docked Layout**

The layout including the position and visibility of the main and peripheral 
windows is saved on exit and will be restored the next time the application is 
run. The layout of the windows can be changed by clicking on the title bar of
the individual window and dragging it to the desired location. A placeholder
window will appear when the mouse is over an area where the dragged window can
be placed as seen in :ref:`Figure: Dragging Windows<figure_layout_change>`.

.. _figure_layout_change:

.. figure:: /_images/layout_change.png
   :scale:  50
   :align: center
   
   **Dragging Windows**

Furthermore, multiple windows can be tiled on top of each other into a tab
controlled area as can be seen in the bottom window in 
:ref:`Figure: Docked Layout<figure_applayout>`. This example shows tabs for 
"Spreadsheet" and "Scripting Window".

.. _figure_layout_toolbar:

.. figure:: /_images/layout_toolbar.png
   :scale:  50
   :align: center
   
   **Custom Layouts**

In addition to manually changing the layout, there are a number of predefined
layouts which are accessible via a drop down button on the toolbar as can be 
seen in :ref:`Figure: Custom Layouts<figure_layout_toolbar>`. The colored icon 
associated with each option indicates 
which peripheral windows will be shown and where. Hovering the mouse over any 
given option for about one second will generate a preview image of the 
resulting layout. The "Save" option allows for the creation and storage of 
custom layouts. The "Organize" option enables the reorganization of the 
ordering of the layouts.

Main Window
-----------

The main window is the window that occupies the central area of the 
application on the screen. At any given time, there can be only one main
window; however, there are multiple windows which are capable of being the
main window if desired. The choice of main window can be controlled by 
selecting the desired option from the "Main window" submenu in the top-level 
*Windows* menu. In 
:ref:`Figure: Docked Layout<figure_applayout>`, the 3D display (see 
:ref:`3D Display <display_3d>`) is serving as the main window.

Currently, there are three different main window options: the 3D display, 
the 2D display, and the spreadsheet. More details about 
the individual windows can be found in their relevant chapters.

Fullscreen
^^^^^^^^^^

In addition to the standard layout described above, the main window can 
optionally be displayed in fullscreen mode, by selecting the "Fullscreen"
option in the top-level *View* menu. Pressing the "Esc" key will exit 
fullscreen mode (please note that clicking the mouse on the screen may be 
required before hitting the "Esc" key in order to ensure that the key press is
registered).

When in fullscreen mode, the main menu bar and status bar are hidden by default.
However, they can be toggled on or off by hitting the "F1" and "F2" keys 
respectively.

The 3D display normally contains popup toolbars around the edge of the window.
These toolbars remain when in fullscreen mode to allow for easy access to 
display functionality. For more details on these toolbars see 
:ref:`3D Display <display_3d>`.

Peripheral Windows
------------------

In addition to the main window, there can be multiple peripheral windows docked
around the edges of the main window or as separate floating top level windows. 
Furthermore, multiple windows can be placed on top of each other in a tabbed 
region.

Currently, multiple peripheral windows (including the potential main windows) 
are available:

* 2D Display
* 2D Preview
* 3D Viewer
* Builder
* List Window
* Scripting Window
* Spreadsheet
* Style Control

The display of peripheral windows is controlled by toggling the desired 
window options in the *Windows* menu. Currently visible windows are indicated 
by the presence of a check mark next to their names. Peripheral can also be 
hidden by clicking on the 'X' in the upper right hand corner of the window. 
As mentioned above, the layout of the peripheral windows can be controlled by 
dragging the individual windows to their desired locations (see 
:ref:`Figure: Dragging Windows<figure_layout_change>`).


.. _undo:


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


Undo / Redo
===========

|product| provides multi-step undo and redo functionality for almost all 
operations. Operations can be undone by selecting the "Undo" option in the 
*Edit* menu, clicking on the undo button in the top 3D toolbar, or by hitting 
*Ctrl+Z* on the keyboard. Any of these actions will undo the last operation 
performed. This can be done repeatedly or the undo history can be viewed in 
the "Undo History" option the *Edit* menu which allows selecting how far back 
into the undo history to go. Please note that while this menu only displays the 
10 most recent operations, the undo history can be much greater, so feel free 
to revisit the "Undo History" option to go back further.

Operations that were just undone can be redone by selecting the "Redo" option 
in *Edit* menu, clicking on the redo button in the top 3D toolbar, or by 
hitting *Ctrl+Y* on the keyboard. Any of these will redo the last operation 
undone. This can be done repeatedly or the redo history can be viewed in the 
"Redo History" option in the *Edit* menu which allows selecting how far into 
the redo history to go. Like the undo history, this menu only displays the 10 
most recent undone operations, but the redo history may be much greater and can 
be revisited to go further.



.. _mouse_map:

Mouse Map
=========

User interaction in the 3D display is primarily performed using the mouse. The 
following table details the available functions as well as the mouse actions
required to perform those functions.

=============================  ===============================
**Function**                   **Mouse Action**
=============================  ===============================
Zoom                           Scroll wheel
Zoom                           Move mouse with *Middle* button
Zoom                           Move mouse with *Left* + *Right* buttons
Rotate                         Move mouse with *Left* button
Rotate around Z axis           Move mouse with *Left* button + *Alt* key
Translate in XY plane          Move mouse with *Left* button + *Shift* key
Translate in Z plane           Scroll wheel with *Alt* key
Select                         Click *Left* button
Select rectangle               Move mouse with *Right* button
Select add                     Click *Left* button with *Ctrl* or *Shift* key
Select grow                    Double click *Left* button
Select add grow                Double click *Left* button *Ctrl* or *Shift* key
Select rectangle and add       Move mouse with *Right* button and *Ctrl* or *Shift* key
Change clipping plane          Scroll wheel with *Ctrl* + *Shift* key
Change far clipping plane      Scroll wheel with *Alt* + *Ctrl* key
Change near clipping plane     Scroll wheel with *Alt* + *Shift* key
Text scale                     Scroll wheel with *Ctrl* key
Menu                           Click *Right* button
Adjust contour level           Scroll wheel with *Shift* key
Show labels                    Move with *Ctrl* key
=============================  ===============================

Special Builder Mouse Actions
-----------------------------
When a molecule is in *Editing* mode, the **Rotate** and **Translate in XY
plane** actions above can be applied exclusively to the molecule being
edited by holding down the *Ctrl* key (*Command* key on a Macintosh) while rotating or translating.


VIDA Sketcher Window
-----------------------

The 2D sketcher window contains a basic 2D sketching environment at 
the top and a 1D text entry mechanism below that. The 1D input mechanism provides 
a very fast way to specify a new molecule or get started with new molecule
creation. The 1D input mechanism supports SMILES, IUPAC and common names, as well 
as FASTA sequences for small peptides (sequence must be prefixed by a leading 
angle bracket (>) character). Disconnected fragments can be specified on the 1D 
input line by entering a vertical bar (|) character between the entries.  Once a 
valid molecule has been specified in the 1D area, that molecule will be depicted in the 2D sketching area.

A basic overview of the 2D sketcher can be seen in :ref:`Figure: 2D Sketcher<figure_sketcher>`

.. figure:: /_images/2D_sketcher.png
   :scale: 75
   :align: center

   **2D Sketcher**

.. list-table::
  :widths: 15 50
  :header-rows: 1
  
  * - Icon
    - Description
  * - .. image:: images/2D_sketcher_icons/pencil.png
    - **Pencil:**  This is the default drawing tool.  With the pencil icon selected (highlighted) click in the 
      main sketcher window to start drawing a new molecule.  Clicking on an atom in 
      the main sketcher window will incrementally build up a carbon chain.  The attachment points 
      are highlighted in orange.  Clicking on a bond will toggle the bond order.
      This tool can also be used to close rings.  Click on the first 
      atom and drag to the second atom where the ring will close.

      Hovering the mouse over an atom or bond highlights it orange.  Right-click on the highlighted 
      atom to access a right-click menu which allows the user to *Set Element*, *Set Formal Charge* 
      or *Delete* the selected atom/bond.  If a bond is highlighted then the 
      right-click menu offers an option to *Set Bond Order*.  There are also options to 
      *Attach...* (through an atom) or *Fuse...* (through an atom or bond) a functional group.  
      In these cases a secondary dialog opens 
      in which a SMILES string can be input of the group to be attached or fused. 
  * - .. image:: images/2D_sketcher_icons/bond.png
    - **Bond order:**  
      Clicking on a bond in the main sketcher window will cycle through the
      available bond orders for that bond.

      Bond order can also be set through the *Set Bond Order* option of the right-click menu.
      Hovering the mouse over an individual bond will temporarily highlight it orange
      and the right-click menu will operate on that bond only.  If multiple bonds are 
      selected (and therefore highlighted orange) using the *Selection* tool (below) then they
      will ALL be set to the new bond order using *Bond Order* in the right-click menu.
      Available options are 0-4 where 0 will break the bond.
  * - .. image:: images/2D_sketcher_icons/element.png
    - **Element:**  
      Click on the small arrow to open a dropdown menu and select from some commonly 
      used elements.  Clicking on an atom in the main 2D sketcher window will cause 
      that atom to be changed to the selected atom type.  In addition to the 
      commonly used atoms there is an "X" dummy atom type.  Clicking the "..." option in 
      the list opens a full periodic table of the elements from which any element 
      can be selected.

      This icon shows an image of the currently active atom type.  The default is 
      "C".

      Atoms types can also be set through the *Set Element* option of the right-click menu.
      Hovering the mouse over a single atom will temporarily highlight it orange
      and the right-click menu will operate on that atom only.  If multiple atoms are 
      selected (and therefore highlighted orange) using the *Selection* tool (below) then they
      will ALL be set to the same atom type using *Set Element* in the right-click menu.
  * - .. image:: images/2D_sketcher_icons/charge.png
    - **Charge:**  Click on the small arrow to open a dropdown and select the formal 
      charge for an atom.  Options available are -2, -1, 0, +1, +2.  With the 
      charge icon active (highlighted white) clicking on any atom in the main 
      sketcher window will modify the atom to have the currently selected charge.

      This icon displays an image of the currently active charge.  
      The default is "-2".

      Formal charge can also be set through the *Set Formal Charge* option of the right-click menu.
      Hovering the mouse over an individual atom will temporarily highlight it orange
      and the right-click menu will operate on that atom only.  If multiple atoms are 
      selected (and therefore highlighted orange) using the *Selection* tool (below) then they
      will ALL be set to the new formal charge using *Set Formal Charge* in the right-click menu.
      This method provides a wider range of charge values than can be accessed using the *Charge* icon.
  * - .. image:: images/2D_sketcher_icons/rings.png
    - **Rings:**  
      Click on the small arrow to open a dropdown menu and select from some commonly 
      used rings, such as benzene, cyclopropane and cyclohexane. The selected  
      ring can be added to the growing molecule multiple times.  The attachment atom or fusion bond 
      is highlighted in orange and alternative fusion options can be accessed using 
      the mouse scroll wheel.  

      This icon shows an image of the currently active ring template.  The default is benzene.

.. list-table::
  :widths: 15 50
  :header-rows: 0

  * - .. image:: images/2D_sketcher_icons/templates.png
    - **Templates:**  
      Click on the small arrow to open a dropdown menu and select from numerous 
      predefined template functional groups, linkers and rings.  There is also an 
      option to define a Custom functional group.  This opens a new dialog into 
      which a SMILES string can be input.  The selected functional group, linker or 
      ring can be added to the growing molecule multiple times.  The attachment atom or fusion bond 
      is highlighted in orange and alternative fusion options can be accessed using 
      the mouse scroll wheel.

      This icon shows an image of the currently active functional group, linker or 
      ring.  The default is "C". 

      With the default "C" functional group selected clicking on an atom in the 
      main sketcher window will build up a carbon chain.  This tool can also be 
      used to close rings.  Click on the first atom and drag to the second atom 
      where the ring will close.
  * - .. image:: images/2D_sketcher_icons/stereo.png
    - **Stereochemistry:**  Click on the small arrow to open a dropdown and select 
      atom and bond CIP stereochemistry options.  Available options are R and S 
      for chiral atoms and E or Z for chiral bonds.  There is also an option to 
      invert the current stereochemistry.

      This icon displays an image of the currently active option.  
      The default is "Invert".

      If no stereochemistry is already set then clicking an atom with the *Invert* option 
      selected will initially set the stereochemistry to R and subsequent clicks with *Invert* will
      toggle between R and S.  In the case of bonds where no stereochemistry is already set the 
      *Invert* option will initially set the stereochemistry to E and then toggle between E and Z.
      Thus *Invert* can be considered a 'one stop shop'.
  * - .. image:: images/2D_sketcher_icons/select.png
    - **Select:**  With the arrow icon highlighted drag to draw a loop around the 
      atoms to be selected or Shift-click or Ctrl-click to incrementally select 
      multiple atoms and/or bonds.  The selected atoms and bonds will be 
      highlighted in orange.  

      A right-click menu allows the user to *Set Element*, *Set Formal Charge* 
      or *Delete* the selected atom(s).  This operation acts on ALL the selected atoms 
      *e.g.* they would all get the same charge.  If only bonds are selected then the 
      right-click menu offers an option to *Set Bond Order*.  There are also options to 
      *Attach...* (through an atom) or *Fuse...* (through an atom or bond) a functional group.  
      In these cases a secondary dialog opens 
      in which a SMILES string can be input of the group to be attached or fused.
  * - .. image:: images/2D_sketcher_icons/wand.png
    - **Clean up the display:** This tool is useful after portions of the molecule have been 
      deleted, especially if a ring has been cleaved.  It uses an OEDepict algorithm to 
      redraw the molecule according to an internal set of rules.
  * - .. image:: images/2D_sketcher_icons/undo.png
    - **Undo:**  Clicking on this icon will undo the last action in the main sketcher window.  
      Repetitive use will undo actions further back in the history.  *Ctrl-Z* is a keyboard
      shortcut that can also be used.
  * - .. image:: images/2D_sketcher_icons/eraser.png
    - **Eraser:**  Delete atoms and/or bonds by selecting the eraser tool and clicking on the 
      atom or bond to be deleted.

      Atoms and bonds can also be deleted through the *Delete* option of the right-click menu.
      Hovering the mouse over a single atom or bond will temporarily highlight it orange
      and the right-click menu will operate on that atom/bond.  If multiple atoms/bonds are 
      selected (and therefore highlighted orange) using the *Selection* tool (below) then they
      will ALL be deleted using *Delete* in the right-click menu.


###################################
VIDA Python API
###################################

..  toctree::

    application.rst

    scope.rst

    ui.rst

    display.rst

    objects.rst

    builder.rst

    spreadsheet.rst

    deprecated.rst


General Functions
*****************

The functions defined in this section provide a wide variety of functionality
that is generally applicable to the VIDA application as a whole.

.. oe:function:: About

   .. oe:api::

      void About()

   Displays information about the VIDA product.

.. oe:function:: AppAddCallback

   .. oe:api::

      unsigned int AppAddCallback(changeName, callbackFunction)

   Adds a Python callback function to be called when certain changes occur 
   within the product.  The changeName parameter is a string, and can have the
   following values:

   - "ActiveChanged"
   - "DisplayChanged"
   - "LockedChanged"
   - "MarkedChanged"
   - "ObjectsAdded"
   - "ObjectsDeleted"
   - "SelectedChanged"
   - "VisibleChanged"
   - "StateReset"

   The callbackFunction parameter is the actual Python function (not a string) 
   to be called each time the specified change happens.

   The return value is an integer callback ID, which can be used to remove
   the callback later.  See :oe:func:`AppRemoveCallback`.

.. oe:function:: AppCurrentDir

   .. oe:api::

      std::string AppCurrentDir()

   Returns the current working directory.  

.. oe:function:: AppCurrentDirSet

   .. oe:api::

      bool AppCurrentDirSet(const std::string &name)

   Sets the current working directory and returns whether or not the change 
   was successful.

.. oe:function:: AppDir

   .. oe:api::

      std::string AppDir()
      
   Returns the path of the directory where the application is installed.

.. oe:function:: AppDocDir

   .. oe:api::

      std::string AppDocDir()

   Returns the path to the directory containing all of the documentation.

.. oe:function:: AppExampleDir

   .. oe:api::

      std::string AppExampleDir()

   Returns the path to the directory containing all of the examples provided 
   with the application.

.. oe:function:: AppInstallDir

   .. oe:api::

      std::string AppInstallDir()

   Returns the path to the directory where VIDA is installed.

.. oe:function:: AppLastDirGet

   .. oe:api::

      std::string AppLastDirGet()

   Returns the path to the last directory that was accessed by VIDA.
   However, if the user has the preference "Open Current Dir" specified, this
   function will return an empty string.

.. oe:function:: AppLastDirSet

   .. oe:api::

      void AppLastDirSet(const std::string &)

   Stores the path to the last directory that was accessed by VIDA.

.. oe:function:: AppLastOpenDirGet

   .. oe:api::

      std::string AppLastOpenDirGet()

   Returns the path to the last directory from which a file was opened. However,
   if the user has the preference "Open Current Dir" specified, this function 
   will return an empty string.

.. oe:function:: AppLastOpenDirSet

   .. oe:api::

      void AppLastOpenDirSet(const std::string &)

   Sets the path to the last directory from which a file was opened.

.. oe:function:: AppLastSaveDirGet

   .. oe:api::

      std::string AppLastSaveDirGet()

   Returns the path to the last directory to which a file was saved. However, if
   the user has the preference "Open Current Dir" specified, this function will
   return an empty string.

.. oe:function:: AppLastSaveDirSet

   .. oe:api::

      void AppLastSaveDirSet(const std::string &)

   Sets the path to the last directory to which a file was saved.

.. oe:function:: AppLicenseFile

   .. oe:api::

      std::string AppLicenseFile()

   Returns the path to the license file being used by VIDA.

.. oe:function:: AppLicenseUpdate

   .. oe:api::

      void AppLicenseUpdate(bool promptonly)

   Searches for a new valid license file. If ``promptonly`` is True, VIDA
   will prompt the user to specify the location of the license file. If it is
   False, VIDA will search the expected potential locations for a new
   valid license file before prompting. If a valid license file is found in one 
   of these locations, that file will be used and the user will not be prompted.

.. oe:function:: AppOpenUrl

   .. oe:api::

      void AppOpenUrl(const std::string &url)

   Opens the specified URL using the most appropriate program for the specified
   URL. For instance, web pages will be opened with the default web browser and 
   files will be opened with the program that that file type is associated.

.. oe:function:: AppRemoveCallback

   .. oe:api::

      void AppRemoveCallback(changeName, unsigned int callbackID)

   Removes a callback created using the AppAddCallback function.  The
   callbackID argument is the value returned from AppAddCallback, and the
   changeName string must be the same one that was used in the call to
   AppAddCallback.  See :oe:func:`AppAddCallback`.

.. oe:function:: AppScriptSave

   .. oe:api::

      bool AppScriptSave(const std::string &fname)

   Saves the current scripting history to the specified file.

.. oe:function:: AppUserDir

   .. oe:api::

      std::string AppUserDir()

   Returns the path of the application user directory containing the application
   preferences, settings, startup script, journal file, and license.

.. oe:function:: AppVersion

   .. oe:api::

      std::string AppVersion()

   Returns a string representation of the complete version number

.. oe:function:: AppVersionMajor

   .. oe:api::

      int AppVersionMajor()

   Returns the first, or major, part of the version number as an integer
   
   
.. oe:function:: AppVersionMinor

   .. oe:api::

      int AppVersionMinor()

   Returns the second, or minor, part of the version number as an integer
   
.. oe:function:: AppVersionBugFix

   .. oe:api::

      int AppVersionBugFix()

   Returns the third, or bug fix, part of the version number as an integer

.. oe:function:: CopyData

   .. oe:api::

      void CopyData(const std::string &data)

   Copies the specified data onto the system clipboard where it can be pasted
   into other applications.

.. oe:function:: CopyMolecules

   .. oe:api::

      void CopyMolecules(const std::vector<OEPropDB::OEKey> &keys)

   Copies the specified molecules onto the system clipboard where they can be 
   pasted into other applications in a variety of formats.

.. oe:function:: CopyMoleculesScoped

   .. oe:api::

      void CopyMoleculesScoped(unsigned int scope = BestScope)

   Copies all of the molecules in the specified scope onto the system clipboard
   where they can be pasted into other applications in a variety of formats.

.. oe:function:: Error

   .. oe:api::

      void Error(const std::string &err)

   Raises an exception when called from within a script, otherwise, it reports
   the specified error message to the status bar.

.. oe:function:: ErrorDetailsDialog

   .. oe:api::

      void ErrorDetailsDialog(const std::string &title, const std::string &message, 
                              const std::string &error)

   Launches an error dialog that contain detailed information about the error 
   that occurred.

.. oe:function:: ExtensionsEdit

   .. oe:api::

      void ExtensionsEdit()

   Launches the extensions manager.

.. oe:function:: IsLicensed

   .. oe:api::

      bool IsLicensed(const std::string &toolkit)

   Returns whether or not a valid license exists for the specified toolkit. If
   a valid license is present, that toolkit can be accessed from Python in 
   VIDA. If a valid license is not present, importing that toolkit in
   Python will fail and throw an exception.

.. oe:function:: JournalInit

   .. oe:api::

      void JournalInit(bool force)

   For internal use only. This function specifies the script as a "Journal
   Script" which forces the application to clear its current state and run the
   script starting from a clean state.

.. oe:function:: ObservableBool

   .. oe:api::

      BoolObservable &ObservableBool(const std::string &name, bool create=False)

   Returns a reference to an observable boolean value.

.. oe:function:: ObservableFloat

   .. oe:api::

      FloatObservable &ObservableFloat(const std::string &name, bool create=False)

   Returns a reference to an observable floating point value.

.. oe:function:: ObservableInt

   .. oe:api::

      IntObservable &ObservableInt(const std::string &name, bool create=False)

   Returns a reference to an observable integer value.

.. oe:function:: ObservableKey

   .. oe:api::

      KeyObservable &ObservableKey(const std::string &name, bool create=False)

   Returns a reference to an observable OEKey object.

.. oe:function:: ObservableString

   .. oe:api::

      StringObservable &ObservableString(const std::string &name, bool create=False)

   Returns a reference to an observable string value.

.. oe:function:: ObservableUInt

   .. oe:api::

      UIntObservable &ObservableUInt(const std::string &name, bool create=False)

   Returns a reference to an observable unsigned integer value.

.. oe:function:: ObservableUpdate

   .. oe:api::

      UpdateObservable &ObservableUpdate(const std::string &name, bool create=False)

   Returns a reference to an observable updater.

.. oe:function:: ObservableVecFloat

   .. oe:api::

      FloatVectorObservable &ObservableVecFloat(const std::string &name, 
                                                bool create=False)

   Returns a reference to an observable list of floating point values.

.. oe:function:: ObservableVecInt

   .. oe:api::

      IntVectorObservable &ObservableVecInt(const std::string &name, 
                                            bool create=False)

   Returns a reference to an observable list of integer values.

.. oe:function:: ObservableVecString

   .. oe:api::

      StringVectorObservable &ObservableVecString(const std::string &name, 
                                                  bool create=False)

   Returns a reference to an observable list of string values.

.. oe:function:: ObservableVecUInt

   .. oe:api::

      UIntVectorObservable &ObservableVecUInt(const std::string &name, 
                                              bool create=False)

   Returns a reference an observable list of unsigned integer values.

.. oe:function:: Open

   .. oe:api::

      std::vector<unsigned int> Open(const std::string &filename, 
                                     const std::string &type="")
      std::vector<unsigned int> Open(const std::vector<std::string> &filenames, 
                                     const std::string &type="")

   This function opens the specified file or files. The optional type parameter is the
   file extension to assume for this file.

.. oe:function:: OpenState

   .. oe:api::

      void OpenState(const std::string &filename)

   This function opens the specified state file.  This action will clear the current
   session, including deleting all the loaded molecules.

.. oe:function:: PasteMolecules

   .. oe:api::

      void PasteMolecules()
      void PasteMolecules(const std::vector<std::string> &, 
                          const std::string &format)

   Pastes all of the molecules that can be found in the system clipboard into
   the application. Pasted molecules will appear in a new list called "Pasted".

.. oe:function:: PreferenceDump

   .. oe:api::

      void PreferenceDump()

   This function prints out all the current preferences.

.. oe:function:: PreferenceGetBool

   .. oe:api::

      bool PreferenceGetBool(const std::string &pref, bool def=False)

   This function returns the current boolean value of the given preference.

.. oe:function:: PreferenceGetColor

   .. oe:api::

      OESystem::OEColor PreferenceGetColor(const std::string &pref, 
                                           const OESystem::OEColor &def=OESystem::OEWhite)

   This function returns the current color of the given preference.

.. oe:function:: PreferenceGetDouble

   .. oe:api::

      double PreferenceGetDouble(const std::string &pref, double def=0.0)

   This function returns the double precision number (non-integral) value of the given preference.

.. oe:function:: PreferenceGetFloat

   .. oe:api::

      float PreferenceGetFloat(const std::string &pref, float def=0.0f)

   This function returns the floating point (non-integral) value of the given preference.

.. oe:function:: PreferenceGetInt

   .. oe:api::

      int PreferenceGetInt(const std::string &pref, int def=0)

   This function returns the integer value of the given preference.

.. oe:function:: PreferenceGetString

   .. oe:api::

      std::string PreferenceGetString(const std::string &pref, 
                                      const std::string &def="")

   This function returns the string value of the given preference.

.. oe:function:: PreferenceGetVBool

   .. oe:api::

      std::vector<bool> PreferenceGetVBool(const std::string &pref, 
                                           const std::vector<bool> &v=std::vector<bool>())

   This function returns the vector of boolean values for the given preference.

.. oe:function:: PreferenceGetVDouble

   .. oe:api::

      std::vector<double> PreferenceGetVDouble(const std::string &pref, 
                                               const std::vector<double> &v=std::vector<double>())

   This function returns the vector of double precision values for the given preference.

.. oe:function:: PreferenceGetVFloat

   .. oe:api::

      std::vector<float> PreferenceGetVFloat(const std::string &pref, 
                                             const std::vector<float> &v=std::vector<float>())

   This function returns the vector of floating point values for the given preference.

.. oe:function:: PreferenceGetVInt

   .. oe:api::

      std::vector<int> PreferenceGetVInt(const std::string &pref, 
                                         const std::vector<int> &v=std::vector<int>())

   This function returns the vector of integer values for the given preference.

.. oe:function:: PreferenceIsBool

   .. oe:api::

      bool PreferenceIsBool(const std::string &pref)

   This function returns whether the given preference is a boolean preference.

.. oe:function:: PreferenceIsColor

   .. oe:api::

      bool PreferenceIsColor(const std::string &pref)

   This function returns whether the given preference is a color.

.. oe:function:: PreferenceIsDouble

   .. oe:api::

      bool PreferenceIsDouble(const std::string &pref)

   This function returns whether the given preference is a double precision number.

.. oe:function:: PreferenceIsFloat

   .. oe:api::

      bool PreferenceIsFloat(const std::string &pref)

   This function returns whether the given preference is a floating point number.

.. oe:function:: PreferenceIsInt

   .. oe:api::

      bool PreferenceIsInt(const std::string &pref)

   This function returns whether the given preference is an integer.

.. oe:function:: PreferenceIsSet

   .. oe:api::

      bool PreferenceIsSet(const std::string &pref)

   This function returns whether the given preference has a value.

.. oe:function:: PreferenceIsString

   .. oe:api::

      bool PreferenceIsString(const std::string &pref)

   This function returns whether the given preference is a string.

.. oe:function:: PreferenceIsVBool

   .. oe:api::

      bool PreferenceIsVBool(const std::string &pref)

   This function returns whether the given preference is a list of booleans.

.. oe:function:: PreferenceIsVDouble

   .. oe:api::

      bool PreferenceIsVDouble(const std::string &pref)

   This function returns whether the given preference is a list of double precision numbers.

.. oe:function:: PreferenceIsVFloat

   .. oe:api::

      bool PreferenceIsVFloat(const std::string &pref)

   This function returns whether the given preference is a list of floating point numbers.

.. oe:function:: PreferenceIsVInt

   .. oe:api::

      bool PreferenceIsVInt(const std::string &pref)

   This function returns whether the given preference is a list of floating point numbers.

.. oe:function:: PreferenceMark

   .. oe:api::

      void PreferenceMark()

   This function marks the preferences as a point for undoing.

.. oe:function:: PreferenceRemove

   .. oe:api::

      bool PreferenceRemove(const std::string &pref)

   This function deletes a preference.

.. oe:function:: PreferenceRestore

   .. oe:api::

      void PreferenceRestore()

   This function restores the default preferences.

.. oe:function:: PreferenceSetBool

   .. oe:api::

      bool PreferenceSetBool(const std::string &pref, bool v)

   This function sets the boolean value of the preference.

.. oe:function:: PreferenceSetColor

   .. oe:api::

      bool PreferenceSetColor(const std::string &pref, const OESystem::OEColor &v)

   This function sets the color value of the preference.

.. oe:function:: PreferenceSetCommand

   .. oe:api::

      bool PreferenceSetCommand(const std::string &pref, const std::string &cmd)

   This function sets the command to activate the changes in the preference.

.. oe:function:: PreferenceSetDouble

   .. oe:api::

      bool PreferenceSetDouble(const std::string &pref, double v)

   This function sets double precision value of the preference.

.. oe:function:: PreferenceSetFloat

   .. oe:api::

      bool PreferenceSetFloat(const std::string &pref, float v)

   This function sets floating point value of the preference.

.. oe:function:: PreferenceSetInt

   .. oe:api::

      bool PreferenceSetInt(const std::string &pref, int v)

   This function sets integer value of the preference.

.. oe:function:: PreferenceSetString

   .. oe:api::

      bool PreferenceSetString(const std::string &pref, const std::string &v)

   This function sets the string value of the preference.

.. oe:function:: PreferenceSetVBool

   .. oe:api::

      bool PreferenceSetVBool(const std::string &pref, const std::vector<bool> &v)

   This function sets value of the preference to the passed list of booleans.

.. oe:function:: PreferenceSetVDouble

   .. oe:api::

      bool PreferenceSetVDouble(const std::string &pref, 
                                const std::vector<double> &v)

   This function sets value of the preference to the passed list of double precision numbers.

.. oe:function:: PreferenceSetVFloat

   .. oe:api::

      bool PreferenceSetVFloat(const std::string &pref, 
                               const std::vector<float> &v)

   This function sets value of the preference to the passed list of floating point numbers.

.. oe:function:: PreferenceSetVInt

   .. oe:api::

      bool PreferenceSetVInt(const std::string &pref, const std::vector<int> &v)

   This function sets value of the preference to the passed list of integers.

.. oe:function:: PreferenceValidateCommands

   .. oe:api::

      std::string PreferenceValidateCommands()

   This function checks all the commands for the preferences to ensure that they
   all exist.  It returns a list of Preference commands that could not be found.

.. oe:function:: PreferencesEdit

   .. oe:api::

      void PreferencesEdit()

   This function opens the preferences dialog.

.. oe:function:: Quit

   .. oe:api::

      void Quit(bool force=False)
      void quit(bool force=False)

   Exits the application. If *force* is set to ``False``, the user will be 
   prompted before actually exiting.

.. oe:function:: Redo

   .. oe:api::

      void Redo()
      void Redo(unsigned int steps)

   This function redoes any previously undone actions.

.. oe:function:: RedoTo

   .. oe:api::

      bool RedoTo(const std::string &)

   Redoes all the previously undone operation up to the specified location in 
   the undo stack.
   
   (See :oe:func:`UndoMark`.)

.. oe:function:: Save

   .. oe:api::

      void Save(const std::string &filename, const std::vector<unsigned int> &ids)
      void Save(const std::string &filename, 
                const std::vector<OEPropDB::OEKey> &keys)

   This function saves the passed IDs or OEKeys to a file with the given filename.

.. oe:function:: SaveMiniState

   .. oe:api::

      void SaveMiniState(const std::string &filename, const std::string &version="")

   This function saves the current application state as a "mini state" to the
   specified file.

.. oe:function:: SaveState

   .. oe:api::

      void SaveState(const std::string &filename, const std::string &version="")

   This function saves the current application state to the specified file.

.. oe:function:: SaveStateFilter

   .. oe:api::

      void SaveStateFilter(const std::string &filename, const std::string &filter)

   This function saves the state of the application to the specified file in the 
   state file format determined by the specified *filter*.

.. oe:function:: SettingsGetBool

   .. oe:api::

      bool SettingsGetBool(const std::string &s, bool def=False)

   This function returns the specified boolean setting.

.. oe:function:: SettingsGetFloat

   .. oe:api::

      float SettingsGetFloat(const std::string &s, float def=0.0f)

   This function returns the specified float setting.

.. oe:function:: SettingsGetInt

   .. oe:api::

      int SettingsGetInt(const std::string &s, int def=0)

   This function returns the specified int setting.

.. oe:function:: SettingsGetString

   .. oe:api::

      std::string SettingsGetString(const std::string &s, const std::string &def="")

   This function returns the specified string setting.

.. oe:function:: SettingsRestore

   .. oe:api::

      void SettingsRestore()

   This function returns the specified restore setting.

.. oe:function:: SettingsSetBool

   .. oe:api::

      bool SettingsSetBool(const std::string &s, bool v)

   This function sets the specified bool setting.

.. oe:function:: SettingsSetFloat

   .. oe:api::

      bool SettingsSetFloat(const std::string &s, float v)

   This function sets the specified float setting.

.. oe:function:: SettingsSetInt

   .. oe:api::

      bool SettingsSetInt(const std::string &s, int v)

   This function sets the specified integer setting.

.. oe:function:: SettingsSetString

   .. oe:api::

      bool SettingsSetString(const std::string &s, const std::string &v)

   This function sets the specified string setting.

.. oe:function:: SettingsSync

   .. oe:api::

      void SettingsSync()

   This function synchronizes the application settings with those stored on disk.
   Ordinarily this function should not need to be called.

.. oe:function:: StateMark

   .. oe:api::

      int StateMark()

   Reserved for internal use.

.. oe:function:: StatePop

   .. oe:api::

      int StatePop(bool load=True)

   Reserved for internal use.

.. oe:function:: Undo

   .. oe:api::

      void Undo()
      void Undo(unsigned int steps)

   This function undoes the previous actions.

.. oe:function:: UndoHint

   .. oe:api::

      void UndoHint(const std::string &action, bool replace=True)

   This function is used to name the current undo action. Ordinarily this function
   should not need to be called by the user.

.. oe:function:: UndoMark

   .. oe:api::

      bool UndoMark(const std::string &)

   Sets a name for the current position in the undo stack which can be used
   later by the :oe:func:`UndoTo` function.

.. oe:function:: UndoTo

   .. oe:api::

      bool UndoTo(const std::string &)

   Undoes all the previous operations up to the specified operation.
   
   (See :oe:func:`UndoMark`.)

.. oe:function:: UpdateRedo

   .. oe:api::

      void UpdateRedo()

   This function updates the redo menu. Ordinarily this function
   should not need to be called by the user.

.. oe:function:: VFSleep

   .. oe:api::

      void VFSleep(unsigned int seconds)

   Sleeps the application for the specified number of seconds.

.. oe:function:: ViewerExportPOVRAY

   .. oe:api::

      void ViewerExportPOVRAY(const std::string &fname)

   This function exports the current scene in the 3D display to a POV-Ray input
   file. The resulting file can be used as input to the POV-Ray raytracing program
   to generate very high quality static 3D images.

.. oe:function:: ViewerScreenshot

   .. oe:api::

      void ViewerScreenshot(const std::string &fname)
      void ViewerScreenshot(const std::string &fname, unsigned int width, 
                            unsigned int height)

   This function saves a screenshot of the 3D display window to the specified
   file (*fname*) in PNG format.

.. oe:function:: WriteHistory

   .. oe:api::

      void WriteHistory(const std::string &filename)

   Writes the current Python interpreter history to the specified filename.



.. |product|        replace:: VIDA
.. |product's|      replace:: VIDA's
.. |settings_file|  replace:: *VIDA.ini*
.. |product_ext_url| replace:: VIDA_EXTENSIONS_URL
.. |xp_user_dir|    replace:: ``C:\Documents and Settings\USERNAME\Application Data\OpenEye\VIDA\5.0``
.. |vista_user_dir| replace:: ``C:\Users\USERNAME\AppData\Local\OpenEye\VIDA\5.0``
.. |osx_user_dir|   replace:: ``/Users/USERNAME/Library/OpenEye/VIDA/5.0``
.. |linux_user_dir| replace:: ``~USERNAME/.OpenEye/VIDA/5.0``
 


Molecule Builder Functions
**************************

The functions detailed in this section provide the ability to create new
molecules from basic inputs and to modify existing ones.

.. oe:function:: AtomAddHydrogens

   .. oe:api::

      void AtomAddHydrogens(const OEPropDB::OEKey &k, bool polaronly=false)

   Adds explicit hydrogens to the specified atom. If *polaronly* is set to True,
   this will only add polar hydrogens to the specified atom.

.. oe:function:: AtomAddHydrogensScoped

   .. oe:api::

      void AtomAddHydrogensScoped(bool polaronly=false, 
                                  unsigned int scope = SelectedScope)

   Scoped version of :oe:func:`AtomAddHydrogens`.

.. oe:function:: AtomAtomicNumDefaultGet

   .. oe:api::

      unsigned int AtomAtomicNumDefaultGet()

   Returns the default value of the atomic number to be used when setting the
   atomic number of an atom via a mouse action.

.. oe:function:: AtomAtomicNumDefaultSet

   .. oe:api::

      void AtomAtomicNumDefaultSet(unsigned int)

   Sets the default value of the atomic number to be used when setting the 
   atomic number of an atom via a mouse action.

.. oe:function:: AtomAtomicNumGet

   .. oe:api::

      unsigned int AtomAtomicNumGet(const OEPropDB::OEKey &k)

   Returns the atomic number of the specified atom.

.. oe:function:: AtomAtomicNumSet

   .. oe:api::

      void AtomAtomicNumSet(const OEPropDB::OEKey &k, unsigned int an)

   Sets the atomic number of the specific atom.

.. oe:function:: AtomAtomicNumSetScoped

   .. oe:api::

      void AtomAtomicNumSetScoped(unsigned int an, 
                                  unsigned int scope = SelectedScope)

   Scoped version of :oe:func:`AtomAtomicNumSet<AtomAtomicNumSet>`.

.. oe:function:: AtomAttach

   .. oe:api::

      void AtomAttach(const OEPropDB::OEKey &k, const std::string &oeb)
      void AtomAttach(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2)
      void AtomAttach(const OEPropDB::OEKey &k, const std::string &smiles, int attach)

   Attaches the specified molecule fragment to the specified atom. There are 
   three different implementations of this function which allow for different 
   specifications of the fragment. The atom being attached to, is always the 
   first parameter. The attachment is performed by the creation of a single bond.
  
   The first implementation takes a hexadecimal encoding of a molecule specified
   in OEB format. This implementation is primarily intended for internal use.
  
   The second implementation takes an OEKey parameter specifying an atom on an 
   already loaded fragment to which the attachment will occur.

   The third implementation takes a SMILES string representing the fragment to
   be attached as well as an index specifying which atom in that fragment will be
   the attachment point.

.. oe:function:: AtomDelete

   .. oe:api::

      void AtomDelete(const OEPropDB::OEKey &k)

   Deletes the specified atom as well as any attached hydrogens.

.. oe:function:: AtomDeleteHydrogens

   .. oe:api::

      void AtomDeleteHydrogens(const OEPropDB::OEKey &k)

   Deletes all of the hydrogens attached to the specified atom.

.. oe:function:: AtomDeleteHydrogensScoped

   .. oe:api::

      void AtomDeleteHydrogensScoped(bool nonpolar=false, 
                                     unsigned int scope = SelectedScope)

   Scoped version of 
   :oe:func:`AtomDeleteHydrogens`.

.. oe:function:: AtomDeleteScoped

   .. oe:api::

      void AtomDeleteScoped(unsigned int scope = SelectedScope)

   Scoped version of 
   :oe:func:`AtomDelete`.

.. oe:function:: AtomFormalChargeDefaultGet

   .. oe:api::

      int AtomFormalChargeDefaultGet()

   Returns the default value of the formal to be used when setting the
   formal of an atom via a mouse action.

.. oe:function:: AtomFormalChargeDefaultSet

   .. oe:api::

      void AtomFormalChargeDefaultSet(int)

   Sets the default value of the formal to be used when setting the
   formal of an atom via a mouse action.

.. oe:function:: AtomFormalChargeGet

   .. oe:api::

      int AtomFormalChargeGet(const OEPropDB::OEKey &k)

   Returns the formal charge for the specified atom.

.. oe:function:: AtomFormalChargeModify

   .. oe:api::

      void AtomFormalChargeModify(const OEPropDB::OEKey &k, int delta)

   Modifies the formal charge on the specified atom by the specified delta 
   value. The delta value can be either positive or negative.

.. oe:function:: AtomFormalChargeModifyScoped

   .. oe:api::

      void AtomFormalChargeModifyScoped(int delta, 
                                        unsigned int scope = SelectedScope)

   Scoped version of 
   :oe:func:`AtomFormalChargeModify`.

.. oe:function:: AtomFormalChargeSet

   .. oe:api::

      void AtomFormalChargeSet(const OEPropDB::OEKey &k, int chg)

   Sets the formal charge on the specified atom.

.. oe:function:: AtomFormalChargeSetScoped

   .. oe:api::

      void AtomFormalChargeSetScoped(int chg, 
                                     unsigned int scope = SelectedScope)

   Scoped version of 
   :oe:func:`AtomFormalChargeSet`.

.. oe:function:: AtomFuse

   .. oe:api::

      void AtomFuse(const OEPropDB::OEKey &k, const std::string &oeb)
      void AtomFuse(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2)
      void AtomFuse(const OEPropDB::OEKey &k, const std::string &smiles, int attach)

   Fuses the specified molecule fragment to the specified atom. There are 
   three different implementations of this function which allow for different 
   specifications of the fragment. The atom being fused to is always the 
   first parameter.
  
   The first implementation takes a hexadecimal encoding of a molecule specified
   in OEB format. This implementation is primarily intended for internal use.
  
   The second implementation takes an OEKey parameter specifying an atom on an 
   already loaded fragment where the fusion will occur.

   The third implementation takes a SMILES string representing the fragment to
   be fused as well as an index specifying which atom in that fragment will be
   the site of the fusion.

.. oe:function:: AtomHybridizationGet

   .. oe:api::

      unsigned int AtomHybridizationGet(const OEPropDB::OEKey &k)

   Returns the hybridization state of the specified atom.

.. oe:function:: AtomHybridizationSet

   .. oe:api::

      void AtomHybridizationSet(const OEPropDB::OEKey &k, unsigned int hyb)

   Sets the hybridization state of the specified atom.  

.. oe:function:: AtomHybridizationSetScoped

   .. oe:api::

      void AtomHybridizationSetScoped(unsigned int hyb, 
                                      unsigned int scope = SelectedScope)

   Scoped version of
   :oe:func:`AtomHybridizationSet`.

.. oe:function:: AtomIsotopeGet

   .. oe:api::

      unsigned int AtomIsotopeGet(const OEPropDB::OEKey &k)

   Returns the isotope of the specified atom.

.. oe:function:: AtomIsotopeSet

   .. oe:api::

      void AtomIsotopeSet(const OEPropDB::OEKey &k, unsigned int iso)

   Sets the isotope for the specified atom.

.. oe:function:: AtomIsotopeSetScoped

   .. oe:api::

      void AtomIsotopeSetScoped(unsigned int iso, 
                                unsigned int scope = SelectedScope)

   Scoped version of
   :oe:func:`AtomIsotopeSet`.

.. oe:function:: AtomSprout

   .. oe:api::

      void AtomSprout(const OEPropDB::OEKey &k, unsigned int elem=6, 
                      unsigned int order=1)

   Sprouts a new atom off of the specified atom. The atomic number of the new 
   atom is specified by *elem* and the order of the bond to the new atom is 
   specified by the *order* parameter.

.. oe:function:: AtomSproutScoped

   .. oe:api::

      void AtomSproutScoped(unsigned int elem=6, unsigned int order=1, 
                            unsigned int scope = SelectedScope)

   Scoped version of 
   :oe:func:`AtomSprout`.

.. oe:function:: AtomStereoDefaultGet

   .. oe:api::

      std::string AtomStereoDefaultGet()
      
   Returns the default value for the stereochemistry setting to be used when
   setting the stereochemistry via a mouse action. Allowed values include:
  
   * "R"
   * "S"
   * "Invert"  

.. oe:function:: AtomStereoDefaultSet

   .. oe:api::

      void AtomStereoDefaultSet(const std::string &s)

   Sets the default value for the stereochemistry setting to be used when
   setting the stereochemistry via a mouse action. Allowed values include:
  
   * "R"
   * "S"
   * "Invert"  

.. oe:function:: AtomStereoSet

   .. oe:api::

      void AtomStereoSet(const OEPropDB::OEKey &k, const std::string &s)

   Sets the CIP stereochemistry of the specified atom. Allowed values are "R"
   and "S".
  
.. oe:function:: AtomStereoSetScoped

   .. oe:api::

      void AtomStereoSetScoped(const std::string &s, 
                               unsigned int scope = SelectedScope)

   Scoped version of
   :oe:func:`AtomStereoSet`.

.. oe:function:: AtomStereoToggle

   .. oe:api::

      void AtomStereoToggle(const OEPropDB::OEKey &k)

   Toggles the stereochemistry of the specified atom.

.. oe:function:: AtomStereoToggleScoped

   .. oe:api::

      void AtomStereoToggleScoped(unsigned int scope = SelectedScope)

   Scoped version of:
   :oe:func:`AtomStereoToggle`.

.. oe:function:: BondAngleGet

   .. oe:api::

      double BondAngleGet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2)
      double BondAngleGet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                          const OEPropDB::OEKey &k3)

   Returns the angle between the two specified bonds or the three specified 
   atoms.

.. oe:function:: BondAngleModify

   .. oe:api::

      void BondAngleModify(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                           double angle, unsigned int rmode)
      void BondAngleModify(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                           const OEPropDB::OEKey &k3, double ang, unsigned int rmode)

   Modifies the angle between the two specified bonds or the three specified 
   atoms. The amount by which the angle is adjusted is specified by the *angle*
   parameter. The portion of the molecule which is actually moved in this 
   process is specified by the *rmode* parameter:
  
   * 0 - the smaller portion of the molecule will be moved
   * 1 - the larger portion of the molecule will be moved

.. oe:function:: BondAngleSet

   .. oe:api::

      void BondAngleSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                        double angle, unsigned int rmode)
      void BondAngleSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                        const OEPropDB::OEKey &k3, double ang, unsigned int rmode)

   Sets the angle between the two specified bonds or the three specified 
   atoms. The desired angle is specified by the *angle* parameter. The portion 
   of the molecule which is actually moved in this process is specified by the 
   *rmode* parameter:
  
   * 0 - the smaller portion of the molecule will be moved
   * 1 - the larger portion of the molecule will be moved

.. oe:function:: BondCreate

   .. oe:api::

      void BondCreate(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                      unsigned int order=1, double length=0.0)

   Creates a new bond between the two specified atoms with an order and length
   specified by the two eponymous parameters.

..  _vida_bonddelete:

.. oe:function:: BondDelete

   .. oe:api::

      void BondDelete(const OEPropDB::OEKey &k)

   Deletes the specified bond.

.. oe:function:: BondDeleteScoped

   .. oe:api::

      void BondDeleteScoped(unsigned int scope = SelectedScope)

   Scoped version of :ref:`BondDelete <vida_bonddelete>`.

.. oe:function:: BondFuse

   .. oe:api::

      void BondFuse(const OEPropDB::OEKey &b, const std::string &oeb)
      void BondFuse(const OEPropDB::OEKey &b1, const OEPropDB::OEKey &b2)
      void BondFuse(const OEPropDB::OEKey &b, const OEPropDB::OEKey &e, 
                    const std::string &oeb)
      void BondFuse(const OEPropDB::OEKey &b, const std::string &smiles, int battach, 
                    int eattach)
      void BondFuse(const OEPropDB::OEKey &b1, const OEPropDB::OEKey &e1, 
                    const OEPropDB::OEKey &b2, const OEPropDB::OEKey &e2)
      void BondFuse(const OEPropDB::OEKey &beg, const OEPropDB::OEKey &end, 
                    const std::string &smiles, int battach, int eattach)

   Fuses two bonds together. There are multiple implementations of this function
   which allow for different mechanisms of specifying the source bond as well as
   the target bond (and associated fragment). The source bond can be specified 
   using a distinct bond key or by specifying the keys of the beginning and end
   atoms of that bond. The target bond can also be specified using a distinct
   bond key or by two keys representing the beginning and end atoms of the bond.
   However, the target bond can also be set as part of a specified fragment.
  
   One implementation allows for specification of a hexadecimal encoded OEB
   string representing the molecule fragment and selected target bond. This
   method is primarily intended for internal use.
  
   The other mechanism allows for specification of the fragment as a SMILES
   string associated with an index for the beginning and end atoms defining
   the bond.

.. oe:function:: BondLengthGet

   .. oe:api::

      double BondLengthGet(const OEPropDB::OEKey &k)
      double BondLengthGet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2)

   Returns the length of the specified bond. The bond can be specified using 
   either a bond key or two atom keys corresponding to the endpoints of the 
   bond.

.. oe:function:: BondLengthModify

   .. oe:api::

      void BondLengthModify(const OEPropDB::OEKey &k, double len, unsigned int rmode)
      void BondLengthModify(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                            double length, unsigned int rmode)

   Modifies the length of the specified bond by the amount specified in the 
   *len* parameter. The bond can be specified using either a bond key or two
   atom keys corresponding to the endpoints of the bond. The portion of the
   molecule which is actually moved is determined by the *rmode* parameter. 
   Available values include:
  
   * 0 - the smaller portion of the molecule is moved
   * 1 - the larger portion of the molecule is moved

.. oe:function:: BondLengthSet

   .. oe:api::

      void BondLengthSet(const OEPropDB::OEKey &k, double len, unsigned int rmode)
      void BondLengthSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                         double length, unsigned int rmode)

   Sets the length of the specified bond to the value specified in the 
   *len* parameter. The bond can be specified using either a bond key or two
   atom keys corresponding to the endpoints of the bond. The portion of the
   molecule which is actually moved is determined by the *rmode* parameter. 
   Available values include:
  
   * 0 - the smaller portion of the molecule is moved
   * 1 - the larger portion of the molecule is moved

.. oe:function:: BondLengthSetScoped

   .. oe:api::

      void BondLengthSetScoped(double length, 
                               unsigned int rmode=OEForge::RotateMode::Smaller, 
                               unsigned int scope = SelectedScope)

   Scoped version of
   :oe:func:`BondLengthSet`.

.. oe:function:: BondOrderDefaultGet

   .. oe:api::

      unsigned int BondOrderDefaultGet()
      
   Returns the default value of the bond order used when setting the order of a
   bond through a mouse action.

.. oe:function:: BondOrderDefaultSet

   .. oe:api::

      void BondOrderDefaultSet(unsigned int)

   Sets the default value of the bond order used when setting the order of a
   bond through a mouse action.

.. oe:function:: BondOrderGet

   .. oe:api::

      unsigned int BondOrderGet(const OEPropDB::OEKey &k)
      unsigned int BondOrderGet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2)

   Returns the order of the specified bond. The bond can be specified as a
   distinct bond key or two keys corresponding to the endpoint atoms.

.. oe:function:: BondOrderSet

   .. oe:api::

      void BondOrderSet(const OEPropDB::OEKey &k, unsigned int order)
      void BondOrderSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                        unsigned int order)

   Sets the order of the specified bond. The bond can be specified as a
   distinct bond key or two keys corresponding to the endpoint atoms.

.. oe:function:: BondOrderSetScoped

   .. oe:api::

      void BondOrderSetScoped(unsigned int order, unsigned int scope)

   Scoped version of
   :oe:func:`BondOrderSet`.

.. oe:function:: BondStereoDefaultGet

   .. oe:api::

      std::string BondStereoDefaultGet()
 
   Returns the default value for bond stereochemistry setting to be used when
   setting the stereochemistry via a mouse action. Allowed values include:
  
   * "E"
   * "Z"
   * "Invert"  

.. oe:function:: BondStereoDefaultSet

   .. oe:api::

      void BondStereoDefaultSet(const std::string &)

   Sets the default value for bond stereochemistry setting to be used when
   setting the stereochemistry via a mouse action. Allowed values include:
  
   * "E"
   * "Z"
   * "Invert"  

.. oe:function:: BondStereoSet

   .. oe:api::

      void BondStereoSet(const OEPropDB::OEKey &k, const std::string &s)
      void BondStereoSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                         const std::string &s)

   Sets the CIP stereochemistry for the specified bond. The bond can be 
   specified as a distinct bond key or by two atom keys corresponding to the
   endpoint atoms. Allowed values for stereochemistry include:
  
   * "E"
   * "Z"

.. oe:function:: BondStereoSetScoped

   .. oe:api::

      void BondStereoSetScoped(const std::string &s, 
                               unsigned int scope = SelectedScope)

   Scoped version of
   :oe:func:`BondStereoSet`.

.. oe:function:: BondStereoToggle

   .. oe:api::

      void BondStereoToggle(const OEPropDB::OEKey &k)
      void BondStereoToggle(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2)

   Toggles the stereochemistry for the specified bond. The bond can be specified
   as a distinct bond key or by two atom keys corresponding to the endpoint 
   atoms.

.. oe:function:: BondStereoToggleScoped

   .. oe:api::

      void BondStereoToggleScoped(unsigned int scope = SelectedScope)

   Scoped version of :oe:func:`BondStereoToggle`.

.. oe:function:: BondTorsionGet

   .. oe:api::

      double BondTorsionGet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                            const OEPropDB::OEKey &k3)
      double BondTorsionGet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                            const OEPropDB::OEKey &k3, const OEPropDB::OEKey &k4)

   Returns the torsion (dihedral) angle specified by either three bonds or four
   atoms. The order of specification is important in the determination of the
   angle.

.. oe:function:: BondTorsionModify

   .. oe:api::

      void BondTorsionModify(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                             const OEPropDB::OEKey &k3, double t, unsigned int rmode)
      void BondTorsionModify(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                             const OEPropDB::OEKey &k3, const OEPropDB::OEKey &k4, 
                             double torsion, unsigned int rmode)

   Modifies the torsion (dihedral) angle specified by either three bonds or four
   atoms. The amount the angle is modified by is specified by the *torsion* 
   parameter. The portion of the molecule which is moved by this function is
   specified by the *rmode* parameter. Available values include:
  
   * 0 - the smaller portion of the molecule moves
   * 1 - the larger portion of the molecule moves

.. oe:function:: BondTorsionSet

   .. oe:api::

      void BondTorsionSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                          const OEPropDB::OEKey &k3, double t, unsigned int rmode)
      void BondTorsionSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                          const OEPropDB::OEKey &k3, const OEPropDB::OEKey &k4, 
                          double torsion, unsigned int rmode)

   Sets the torsion (dihedral) angle specified by either three bonds or four
   atoms. The desired angle is specified by the *torsion* parameter. The portion 
   of the molecule which is moved by this function is specified by the *rmode* 
   parameter. Available values include:
  
   * 0 - the smaller portion of the molecule moves
   * 1 - the larger portion of the molecule moves

.. oe:function:: BuilderActiveGet

   .. oe:api::

      bool BuilderActiveGet()

   Returns whether or not VIDA is in molecule editing mode.

.. oe:function:: BuilderActiveSet

   .. oe:api::

      void BuilderActiveSet(bool)

   Sets whether or not VIDA is in molecule editing mode.

.. oe:function:: BuilderAlternateConfModeGet

   .. oe:api::

      bool BuilderAlternateConfModeGet()

   Returns whether or not VIDA is in ring alternate conformation
   exploration mode.

.. oe:function:: BuilderAlternateConfModeSet

   .. oe:api::

      void BuilderAlternateConfModeSet(bool)

   Sets whether or not VIDA is in ring alternate conformation exploration
   mode.

.. oe:function:: BuilderAlternateConfSet

   .. oe:api::

      void BuilderAlternateConfSet(unsigned int)

   Applies the specified alternate ring conformation to the molecule currently
   being edited. This is intended for internal use only.

.. oe:function:: BuilderCancel

   .. oe:api::

      void BuilderCancel()

   Cancels all modifications made to the molecule currently being edited and
   exits editing mode.

.. oe:function:: BuilderEdit

   .. oe:api::

      void BuilderEdit(const OEPropDB::OEKey &, bool force3D)

   Puts VIDA into editing mode for the specified molecule.  If the molecule
   is a 2D molecule, setting the *force3D* parameter to True will ensure that 3D
   coordinates will be generated, even if the user cancels out of editing mode.

.. oe:function:: BuilderFinish

   .. oe:api::

      void BuilderFinish()

   Commits all modifications made to the molecule currently being edited and
   exits editing mode.

.. oe:function:: BuilderFragmentGet

   .. oe:api::

      std::string BuilderFragmentGet()

   Returns a hexadecimal encoded OEB string representation of the current
   fragment being used in the builder component.

.. oe:function:: BuilderFragmentSet

   .. oe:api::

      void BuilderFragmentSet(const std::string &oeb)
      void BuilderFragmentSet(const std::string &smiles, int)

   Sets the default fragment to be used in mouse actions in the builder. The
   first implementation takes a hexadecimal encoded OEB string representation
   of the molecule fragment (this is primarily intended for internal use). The
   second implementation takes a SMILES string with an additional index 
   parameter which specifies the index of the atom to be used as the attachment
   point.

.. oe:function:: BuilderMinimize

   .. oe:api::

      void BuilderMinimize()

   Minimizes the molecule currently being edited using the MMFF forcefield.

.. oe:function:: BuilderMinimizeScoped

   .. oe:api::

      void BuilderMinimizeScoped(unsigned int scope = SelectedScope)

   Minimizes a portion of the molecule currently being edited as determined by 
   the atoms in the specified scope. Valid values for the scope parameter are:
  
   * MarkedScope
   * SelectedScope
   * ScratchScope

.. oe:function:: BuilderPropertiesGet

   .. oe:api::

      std::vector<string> BuilderPropertiesGet()

   Returns a list of the properties displayed in the Property table of the
   Builder window.

.. oe:function:: BuilderPropertyAdd

   .. oe:api::

      void BuilderPropertyAdd(const std::string &name, const std::string &command, unsigned int flags = CalculateForSmallMols)

   Adds a user-defined property calculator to the Properties table of the 
   Builder window.  The *name* parameter is the name of the property to be 
   calculated.  The *command* parameter is a string containing a Python command
   to be executed to calculate the property.  The return value of the command
   is displayed in the property table.  The *flags* parameter specifies what
   types of molecules the property will be calculated for, and whether a change
   to a molecule's coordinates requires the property to be recalculated.  Valid
   values for this parameter are:

   * UpdateOnCoordChange
   * CalculateForSmallMols
   * CalculateForProteins

   These values can be OR'ed together to be used in combinations.  The property
   is always recalculated when the chemical graph of the active molecule 
   changes.  

   To add one of |product's| default properties (*e.g.*, 'LogP') to the 
   property table, use its name and leave the *command* string empty.

.. oe:function:: BuilderPropertyRemove

   .. oe:api::

      void BuilderPropertyRemove(const std::string &propertyToRemove)

   Removes a property from the Property table of the Builder window.

.. oe:function:: BuilderPropertySetValue

   .. oe:api::

      void BuilderPropertySetValue(const std::string &propertyName, const std::string &value)

   Directly sets a value in the Property table of the Builder window.  The 
   value will be overwritten when the property is updated.

.. oe:function:: BuilderTorsionActivate

   .. oe:api::

      void BuilderTorsionActivate(const OEPropDB::OEKey &key)

   Activates an existing torsion monitor, specified by key, so that it can be
   rotated interactively while in Editing mode.  Activating a torsion will 
   temporarily display two torsion measurements, one for each end of the bond.
   When one of these measurements is selected, the corresponding end of the 
   molecule will be moved when the mouse wheel or up/down arrows are used.  If 
   this command is used outside of Editing mode, the double measurements will be
   displayed but will not be activated.

.. oe:function:: BuilderTorsionsDeactivate

   .. oe:api::

      void BuilderTorsionsDeactivate()

   Returns all active torsion monitors to their inactive state.
  
.. oe:function:: BuilderUseMMFF94sSet

   .. oe:api::

      void BuilderUseMMFF94sSet(bool useMMFF94s)

   Causes the builder geometry optimizations to use the MMFF94s force field,
   which provides more nearly planar geometries for delocalized trigonal
   nitrogens than the MMFF94 force field.  Calling this function with
   *useMMFF94s* = False will cause the builder to revert to using MMFF94.

.. oe:function:: BuilderUseMMFF94sGet

   .. oe:api::

      bool BuilderUseMMFF94sGet()

   Returns True if the builder is currently set to use the MMFF94s force field,
   or False if the builder is using the MMFF94 force field.

.. oe:function:: MoleculeAddExplicitHydrogens

   .. oe:api::

      void MoleculeAddExplicitHydrogens(const OEPropDB::OEKey &k, 
                                        bool polarOnly=false)

   Adds explicit hydrogens to the specified molecule. If the *polarOnly* 
   parameter is specified, only polar hydrogens will be added.

.. oe:function:: MoleculeAddHydrogens

   .. oe:api::

      void MoleculeAddHydrogens(const OEPropDB::OEKey &k, bool polarOnly=false)

   This function adds hydrogens to the molecule associated with the specified
   key. If the *polarOnly* parameter is set, only polar hydrogens will be added.

.. oe:function:: MoleculeAddHydrogensScoped

   .. oe:api::

      void MoleculeAddHydrogensScoped(bool polarOnly=false, 
                                      unsigned int scope = BestScope)

   This function adds hydrogens to the molecules int the specified scope. If the 
   *polarOnly* parameter is set, only polar hydrogens will be added.

.. oe:function:: MoleculeDeleteHydrogens

   .. oe:api::

      void MoleculeDeleteHydrogens(const OEPropDB::OEKey &k, bool nonpolar=false)

   Deletes hydrogens off of the specified molecule. If the *nonpolar* parameter
   is True, it will only delete non-polar hydrogens, leaving the molecule with
   only polar hydrogens still attached.

.. oe:function:: MoleculeGenerateCoords

   .. oe:api::

      void MoleculeGenerateCoords(const OEPropDB::OEKey &k, 
                                  unsigned int maxconfs=1, 
                                  bool strict=false)

   Generates new coordinates for the specified molecule. The maximum number of 
   conformations can be specified using the *maxconfs* parameter. Strict stereo 
   can be turn on using the *strict* parameter.

.. oe:function:: MoleculeGenerateCoordsFixed

   .. oe:api::

      void MoleculeGenerateCoordsFixed(const OEPropDB::OEKey &k, 
                                       const std::vector<OEPropDB::OEKey> &fixed, 
                                       bool match=true, unsigned int maxconfs=1, 
                                       bool strict=false)

   Generates new coordinates for the specified molecule while holding fixed
   either the specified atoms (if the *match* parameter is True) or all the
   unspecified atoms (if the *match* parameter is False). The maximum number of
   conformations can be specified use the *maxconfs* parameter. Strict stereo 
   can be turn on using the *strict* parameter.

.. oe:function:: MoleculeGenerateCoordsFixedScoped

   .. oe:api::

      void MoleculeGenerateCoordsFixedScoped(const OEPropDB::OEKey &k, 
                                             bool match=true, unsigned int maxconfs=1, 
                                             unsigned int scope = SelectedScope,
                                             bool strict)

   Generates new coordinates for the specified molecule while holding fixed
   either all the atoms in the specified scope (if the *match* parameter is 
   True) or all the atoms not in specified scope (if the *match* parameter is 
   False). The maximum number of conformations can be specified use the 
   *maxconfs* parameter. Strict stereo can be turn on using the *strict* parameter.

.. oe:function:: MoleculeNew

   .. oe:api::

      OEPropDB::OEKey MoleculeNew(const std::string &text, unsigned int listid=0)

   Creates a new molecule from the specified text representation. Allowed text 
   representations include SMILES as well as IUPAC and common names. A FASTA
   sequence can also be specified if preceded by an angle bracket character 
   ('>'). 
   
   Assuming that the molecule can be created from the specified text, it will 
   be added to the specified list (*listid*). If the list ID is zero, a new 
   list will be created.
   
   Returns the key corresponding to this molecule.

.. oe:function:: MoleculeRotate

   .. oe:api::

      void MoleculeRotate(const OEPropDB::OEKey &key,
                          int oldx, oldy, int newx, int newy)

   Rotates a molecule's coordinates corresponding to a mouse move in the 3D
   display window.

.. oe:function:: SketcherInputSet

   .. oe:api::

      void SketcherInputSet(const std::string &smilesString)
      void SketcherInputSet(OEMol &molecule)

   Sets the molecule in the Sketcher from the provided SMILES string or 
   molecule.  If an existing 3D molecule is already in build mode, this 
   method will throw an exception.

.. oe:function:: SketcherLookupFunctionSet

   .. oe:api::

      void SketcherLookupFunctionSet(const std::string &functionString)

   Sets a Python function to be called for compound name lookups.  The lookup
   function should accept a string, convert that to either SMILES or a
   molecule, and call :oe:func:`SketcherInputSet` to put the resulting molecule
   into the Sketcher.  The ``functionString`` argument should include only
   the name of the lookup function, without parentheses or arguments, *e.g.*, 
   'MyLookupFunction'.
   


Deprecated Functions
********************

The functions detailed in this section have been deprecated. They are still
available for use, but are scheduled to be removed from the API in a future
version. Most of these functions have been deprecated in order to create a
more consistently named API, but some have been deprecated as the 
functionality they provided is no longer available, obsolete, or unnecessary. 
If an alternate function is available, it will be referenced in the documentation
below.

.. oe:function:: ContourCurrentGridGet

   .. oe:api::

      unsigned int ContourCurrentGridGet()

   This function has been deprecated.

.. oe:function:: ContourCurrentGridSet

   .. oe:api::

      unsigned int ContourCurrentGridSet(unsigned int id)

   This function has been deprecated.

.. oe:function:: CreateAngleMonitor

   .. oe:api::

      unsigned int CreateAngleMonitor(const OEPropDB::OEKey &k1, 
                                      const OEPropDB::OEKey &k2, 
                                      const OEPropDB::OEKey &k3)
  
   This function has been deprecated. Please use 
   :ref:`MonitorAngleCreate <vida_MonitorAngleCreate>` instead.

.. oe:function:: CreateDistanceMonitor

   .. oe:api::

      unsigned int CreateDistanceMonitor(const OEPropDB::OEKey &k1, 
                                         const OEPropDB::OEKey &k2)

   This function has been deprecated. Please use 
   :oe:func:`MonitorDistanceCreate` instead.

.. oe:function:: CreateSphereMonitor

   .. oe:api::

      unsigned int CreateSphereMonitor(const OEPropDB::OEKey &k, 
                                       const std::string &name, 
                                       const OESystem::OEColor &c, float rad=0.0f)
      unsigned int CreateSphereMonitor(const OEPropDB::OEKey &k, 
                                       const std::string &name, float x, float y, 
                                       float z, float rad, const OESystem::OEColor &c)

   This function has been deprecated. Please use 
   :oe:func:`MonitorSphereCreate` instead.

.. oe:function:: CreateTorsionMonitor

   .. oe:api::

      unsigned int CreateTorsionMonitor(const OEPropDB::OEKey &k1, 
                                        const OEPropDB::OEKey &k2, 
                                        const OEPropDB::OEKey &k3, 
                                        const OEPropDB::OEKey &k4)

   This function has been deprecated. Please use 
   :oe:func:`MonitorTorsionCreate` instead.

.. oe:function:: CustomViewDocking
   :project: VIDA

   .. oe:api::

      void CustomViewDocking()
      void CustomViewDocking(const std::string &protein, const std::string &reference, 
                             const std::string &results="")
      void CustomViewDocking(const std::string &protein, const std::string &reference, 
                             const std::string &results, bool showRibbons, 
                             bool showLabels, bool showHBonds, bool showSurface, 
                             float residueWithin, float surfaceWithin, 
                             const std::string &surfaceColor)

   This function has been deprecated. Please use 
   :oe:func:`CustomViewFRED` instead.

.. oe:function:: DatatableCurrent

   .. oe:api::

      std::string DatatableCurrent()

   This function has been deprecated. Please use 
   :oe:func:`DatatableCurrentGet` instead.

.. oe:function:: DeleteAngleMonitor

   .. oe:api::

      void DeleteAngleMonitor(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                              const OEPropDB::OEKey &k3)

   This function has been deprecated. Please use 
   :oe:func:`MonitorAngleDelete` instead.

.. oe:function:: DeleteDistanceMonitor

   .. oe:api::

      void DeleteDistanceMonitor(const OEPropDB::OEKey &k1, 
                                 const OEPropDB::OEKey &k2)

   This function has been deprecated. Please use 
   :oe:func:`MonitorDistanceDelete` instead.

.. oe:function:: DeleteTorsionMonitor

   .. oe:api::

      void DeleteTorsionMonitor(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                                const OEPropDB::OEKey &k3, const OEPropDB::OEKey &k4)

   This function has been deprecated. Please use 
   :oe:func:`MonitorTorsionDelete` instead.

.. oe:function:: DeleteVisibleMonitors

   .. oe:api::

      void DeleteVisibleMonitors()
      
   This function has been deprecated. Please use 
   :oe:func:`MonitorsVisibleDelete` instead.     

.. oe:function:: ExistsAngleMonitor

   .. oe:api::

      unsigned int ExistsAngleMonitor(const OEPropDB::OEKey &k1, 
                                      const OEPropDB::OEKey &k2, 
                                      const OEPropDB::OEKey &k3)

   This function has been deprecated. Please use 
   :oe:func:`MonitorAngleExists` instead.     

.. oe:function:: ExistsDistanceMonitor

   .. oe:api::

      unsigned int ExistsDistanceMonitor(const OEPropDB::OEKey &k1, 
                                         const OEPropDB::OEKey &k2)

   This function has been deprecated. Please use 
   :oe:func:`MonitorDistanceExists` instead.     

.. oe:function:: ExistsTorsionMonitor

   .. oe:api::

      unsigned int ExistsTorsionMonitor(const OEPropDB::OEKey &k1, 
                                        const OEPropDB::OEKey &k2, 
                                        const OEPropDB::OEKey &k3, 
                                        const OEPropDB::OEKey &k4)

   This function has been deprecated. Please use 
   :oe:func:`MonitorTorsionExists` instead.

.. oe:function:: GetAtomsByScope

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetAtomsByScope(unsigned int scope)

   This function has been deprecated. Please use 
   :oe:func:`GetAtomsScoped` instead.

.. oe:function:: GetBondsByScope

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetBondsByScope(unsigned int scope)

   This function has been deprecated. Please use 
   :oe:func:`GetBondsScoped` instead.

.. oe:function:: GetContoursByScope

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetContoursByScope(unsigned int scope)

   This function has been deprecated. Please use 
   :oe:func:`GetContoursScoped` instead.

.. oe:function:: GetGridsByScope

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetGridsByScope(unsigned int scope)

   This function has been deprecated. Please use 
   :oe:func:`GetGridsScoped` instead.

.. oe:function:: GetKey

   .. oe:api::

      OEPropDB::OEKey GetKey(const OESystem::OEBase &base)
      OEPropDB::OEKey GetKey(const OESystem::OEBase &base, 
                             const OEPropDB::OEKey &parentKey)

   This function has been deprecated. Please use 
   :oe:func:`KeyGet` instead.

.. oe:function:: GetKeyType

   .. oe:api::

      std::string GetKeyType(const OEPropDB::OEKey &key)

   This function has been deprecated. Please use 
   :oe:func:`KeyTypeGet` instead.

.. oe:function:: GetKeysByScope

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetKeysByScope(unsigned int scope, 
                                                  unsigned int type)

   This function has been deprecated. Please use 
   :oe:func:`GetScoped` instead.

.. oe:function:: GetKeysForID

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetKeysForID(unsigned int id)

   This function has been deprecated. Please use 
   :oe:func:`KeysGet` instead.

.. oe:function:: GetMoleculesByScope

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetMoleculesByScope(unsigned int scope)

   This function has been deprecated. Please use 
   :oe:func:`GetMoleculesScoped` instead.

.. oe:function:: GetName

   .. oe:api::

      std::string GetName(const OEPropDB::OEKey &key)

   This function has been deprecated. Please use 
   :oe:func:`NameGet` instead.

.. oe:function:: GetPropertyType

   .. oe:api::

      unsigned int GetPropertyType(const std::string &type)

   This function has been deprecated. Please use 
   :oe:func:`PropertyTypeGet` instead.

.. oe:function:: GetSurfacesByScope

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetSurfacesByScope(unsigned int scope)

   This function has been deprecated. Please use 
   :oe:func:`GetSurfacesScoped` instead.

.. oe:function:: GotoStylePage

   .. oe:api::

      void GotoStylePage(const std::string &page)

   This function has been deprecated.

.. oe:function:: InitializeObject

   .. oe:api::

      void InitializeObject(unsigned int id)

   This function has been deprecated. Please use 
   :oe:func:`Initialize` instead.

.. oe:function:: InterpreterInteractiveGet

   .. oe:api::

      bool InterpreterInteractiveGet()

   This function has been deprecated.

.. oe:function:: InterpreterInteractiveSet

   .. oe:api::

      void InterpreterInteractiveSet(bool interactive)

   This function has been deprecated.

.. oe:function:: MarkObjectsByScope

   .. oe:api::

      bool MarkObjectsByScope(unsigned int scope)

   This function has been deprecated. Please use 
   :oe:func:`MarkScoped` instead.

.. oe:function:: MarkState

   .. oe:api::

      int MarkState()
      
   This function has been deprecated. Please use 
   :oe:func:`StateMark` instead.     

.. oe:function:: MenuAddLabel

   .. oe:api::

      std::string MenuAddLabel(const std::string &menu, const std::string &name, 
                               bool last)

   This function has been deprecated. 

.. oe:function:: MenuUseTearoffsGet

   .. oe:api::

      bool MenuUseTearoffsGet()

   This function has been deprecated. 
  
.. oe:function:: MenuUseTearoffsSet

   .. oe:api::

      bool MenuUseTearoffsSet(bool b)

   This function has been deprecated. 
  
.. oe:function:: OEGetKey

   .. oe:api::

      OEPropDB::OEKey OEGetKey(const OESystem::OEBase &b)
      OEPropDB::OEKey OEGetKey(const OESystem::OEBase &b, const OEPropDB::OEKey &k)

   This function has been deprecated. Please use 
   :oe:func:`KeyGet` instead.

.. oe:function:: OEKeyToID

   .. oe:api::

      unsigned int OEKeyToID(const OEPropDB::OEKey &k)

   This function has been deprecated. Please use 
   :oe:func:`KeyIDGet` instead.

.. oe:function:: OEKeyToLabelString

   .. oe:api::

      std::string OEKeyToLabelString(const OEPropDB::OEKey &k, bool full=false, 
                                     bool coords=true)

   This function has been deprecated. Please use 
   :oe:func:`LabelGet` instead.

.. oe:function:: OEKeyToParentID

   .. oe:api::

      unsigned int OEKeyToParentID(const OEPropDB::OEKey &k)

   This function has been deprecated. Please use 
   :oe:func:`KeyParentIDGet` instead.

.. oe:function:: OEKeyToSourceID

   .. oe:api::

      unsigned int OEKeyToSourceID(const OEPropDB::OEKey &k)

   This function has been deprecated. Please use 
   :oe:func:`KeySourceIDGet` instead.

.. oe:function:: OEPyClearActive

   .. oe:api::

      void OEPyClearActive()

   This function has been deprecated. Please use 
   :oe:func:`ClearActive` instead.

.. oe:function:: OEPyClearLocked

   .. oe:api::

      void OEPyClearLocked()

   This function has been deprecated. Please use 
   :oe:func:`ClearLocked` instead.

.. oe:function:: OEPyClearMarked

   .. oe:api::

      void OEPyClearMarked()

   This function has been deprecated. Please use 
   :oe:func:`ClearMarked` instead.

.. oe:function:: OEPyClearSelected

   .. oe:api::

      void OEPyClearSelected()

   This function has been deprecated. Please use 
   ClearSelected instead.

.. oe:function:: OEPyClearVisible

   .. oe:api::

      void OEPyClearVisible()

   This function has been deprecated. Please use 
   :oe:func:`ClearVisible` instead.

.. oe:function:: OEPyGetActive

   .. oe:api::

      OEPropDB::OEKey OEPyGetActive()

   This function has been deprecated. Please use 
   :oe:func:`ActiveKey` instead.

.. oe:function:: OEPyGetIDForKey

   .. oe:api::

      unsigned int OEPyGetIDForKey(const OEPropDB::OEKey &k)

   This function has been deprecated. Please use 
   :oe:func:`KeyIDGet` instead.

.. oe:function:: OEPyGetSelectedAtoms

   .. oe:api::

      std::vector<OEPropDB::OEKey> OEPyGetSelectedAtoms()

   This function has been deprecated. Please use 
   :oe:func:`GetSelectedAtoms` instead.

.. oe:function:: OEPyHide

   .. oe:api::

      bool OEPyHide(unsigned int scope, bool value)

   This function has been deprecated. Please use 
   :oe:func:`HideScoped` instead.

.. oe:function:: OEPyHideNone

   .. oe:api::

      bool OEPyHideNone(unsigned int scope)

   This function has been deprecated. Please use 
   HideNonScoped instead.

.. oe:function:: OEPyHideOthers

   .. oe:api::

      bool OEPyHideOthers(const std::vector<OEPropDB::OEKey> &keys, bool hide)

   This function has been deprecated. Please use 
   :oe:func:`HideOthers` instead.

.. oe:function:: OEPyIsActive

   .. oe:api::

      bool OEPyIsActive(const OEPropDB::OEKey &k)

   This function has been deprecated. Please use 
   :oe:func:`IsActive` instead.

.. oe:function:: OEPyIsLocked

   .. oe:api::

      bool OEPyIsLocked(const OEPropDB::OEKey &k)

   This function has been deprecated. Please use 
   :oe:func:`IsLocked` instead.

.. oe:function:: OEPyIsMarked

   .. oe:api::

      bool OEPyIsMarked(const OEPropDB::OEKey &k)

   This function has been deprecated. Please use 
   :oe:func:`IsMarked` instead.

.. oe:function:: OEPyIsSelected

   .. oe:api::

      bool OEPyIsSelected(const OEPropDB::OEKey &k)

   This function has been deprecated. Please use 
   :oe:func:`IsSelected` instead.

.. oe:function:: OEPyIsTrulyVisible

   .. oe:api::

      bool OEPyIsTrulyVisible(const OEPropDB::OEKey &k)

   This function has been deprecated. Please use 
   :oe:func:`IsTrulyVisible` instead.

.. oe:function:: OEPyIsVisible

   .. oe:api::

      bool OEPyIsVisible(const OEPropDB::OEKey &k)

   This function has been deprecated. Please use 
   :oe:func:`IsVisible` instead.

.. oe:function:: OEPySetActive

   .. oe:api::

      bool OEPySetActive(const OEPropDB::OEKey &k)

   This function has been deprecated. Please use 
   :oe:func:`Active` instead.

.. oe:function:: OEPySetLocked

   .. oe:api::

      bool OEPySetLocked(const OEPropDB::OEKey &k, bool state)
      bool OEPySetLocked(const std::vector<OEPropDB::OEKey> &keys, bool state)

   This function has been deprecated. Please use 
   :oe:func:`Lock` instead.

.. oe:function:: OEPySetMarked

   .. oe:api::

      bool OEPySetMarked(const OEPropDB::OEKey &k, bool state)
      bool OEPySetMarked(const std::vector<OEPropDB::OEKey> &keys, bool state)

   This function has been deprecated. Please use 
   :oe:func:`Mark` instead.

.. oe:function:: OEPySetSelected

   .. oe:api::

      bool OEPySetSelected(const OEPropDB::OEKey &k, bool state)
      bool OEPySetSelected(const std::vector<OEPropDB::OEKey> &keys, bool state)

   This function has been deprecated. Please use 
   :oe:func:`Select` instead.

.. oe:function:: OEPySetVisible

   .. oe:api::

      bool OEPySetVisible(const OEPropDB::OEKey &k, bool state)
      bool OEPySetVisible(const std::vector<OEPropDB::OEKey> &keys, bool state)

   This function has been deprecated. Please use 
   :oe:func:`Visible` instead.

.. oe:function:: ObjectNameGet

   .. oe:api::

      std::string ObjectNameGet(unsigned int id)
      std::string ObjectNameGet(const OEPropDB::OEKey &k)

   This function has been deprecated. Please use 
   :oe:func:`NameGet` instead.

.. oe:function:: ObjectNameSet

   .. oe:api::

      void ObjectNameSet(unsigned int id, const std::string &name)
      void ObjectNameSet(const OEPropDB::OEKey &k, const std::string &name)

   This function has been deprecated. Please use 
   :oe:func:`NameSet` instead.

.. oe:function:: ObservableOEKey

   .. oe:api::

      OEGUI::OEObservableBase<OEPropDB::OEKey> &
        ObservableOEKey(const std::string &name, bool create=false)

   This function has been deprecated. Please use 
   :oe:func:`ObservableKey` instead.

.. oe:function:: PopState

   .. oe:api::

      int PopState(bool load=true)

   This function has been deprecated. Please use 
   :oe:func:`StatePop` instead.

.. oe:function:: PopupAddLabel

   .. oe:api::

      std::string PopupAddLabel(const std::string &label, bool once=false)

   This function has been deprecated. 

.. oe:function:: ResponseVectMulti

   .. oe:api::

      void ResponseVectMulti(const std::string &s, 
                             const std::vector<OEInterpreter::OEMultiTypeVar> &var, 
                             bool b=false)

   This function has been deprecated. Please use 
   :oe:func:`PromptResponseVectMulti` instead.

.. oe:function:: SDataGet

   .. oe:api::

      std::string SDataGet(unsigned int id, const std::string &tag)
      std::string SDataGet(const OEPropDB::OEKey &k, const std::string &tag)

   This function has been deprecated. Please use 
   :oe:func:`SDDataGet` instead.

.. oe:function:: SDataHas

   .. oe:api::

      bool SDataHas(unsigned int id, const std::string &tag)
      bool SDataHas(const OEPropDB::OEKey &k, const std::string &tag)

   This function has been deprecated. Please use 
   :oe:func:`SDDataHas` instead.

.. oe:function:: SDataSet

   .. oe:api::

      void SDataSet(unsigned int id, const std::string &tag, const std::string &v)
      void SDataSet(const OEPropDB::OEKey &k, const std::string &tag, 
                    const std::string &v)

   This function has been deprecated. Please use 
   :oe:func:`SDDataSet` instead.

.. oe:function:: ScratchList

   .. oe:api::

      std::vector<OEPropDB::OEKey> ScratchList()

   This function has been deprecated. Please use 
   :oe:func:`ScratchGet` instead.

.. oe:function:: SpreadsheetCurrent

   .. oe:api::

      std::string SpreadsheetCurrent()

   This function has been deprecated, please use 
   :oe:func:`SpreadsheetCurrentGet` instead.

.. oe:function:: SpreadsheetDisableUpdates

   .. oe:api::

      void SpreadsheetDisableUpdates(const std::string &spreadsheet)

   This function has been deprecated.

.. oe:function:: SpreadsheetEnableUpdates

   .. oe:api::

      void SpreadsheetEnableUpdates(const std::string &spreadsheet)

   This function has been deprecated.

.. oe:function:: SpreadsheetMarkHighlighted

   .. oe:api::

      void SpreadsheetMarkHighlighted(const std::string &spreadsheet, bool marked)

   This function has been deprecated.

.. oe:function:: SpreadsheetUpdateContents

   .. oe:api::

      void SpreadsheetUpdateContents(const std::string &spreadsheet)

   This function has been deprecated.

.. oe:function:: SurfacePotentialColorAuto

   .. oe:api::

      void SurfacePotentialColorAuto()

   This function has been deprecated.

.. oe:function:: SurfacePotentialColorValuesSet

   .. oe:api::

      void SurfacePotentialColorValuesSet(float min, float mid, float max)

   This function has been deprecated.

.. oe:function:: VFCopyFile

   .. oe:api::

      bool VFCopyFile(const std::string &src, const std::string &dst)

   This function has been deprecated. 
  
.. oe:function:: VFGetMol

   .. oe:api::

      bool VFGetMol(OEChem::OEMCMolBase &m, unsigned int id)
      bool VFGetMol(OEChem::OEMCMolBase &m, const OEPropDB::OEKey &key)

   This function has been deprecated. Please use 
   :oe:func:`MoleculeGet` instead.



Display Functions
*****************

The functions detailed in this section enable the customization of how the 
application itself as well as the currently loaded objects are displayed.

.. oe:function:: AnnotationGet

   .. oe:api::

      std::string AnnotationGet(const OEPropDB::OEKey &key)

   Returns the text annotation associated with the object specified by ``key``.

.. oe:function:: AnnotationHas

   .. oe:api::

      bool AnnotationHas(const OEPropDB::OEKey &key)

   Returns whether or not the object specified by ``key`` has a text annotation.

.. oe:function:: AnnotationSet

   .. oe:api::

      void AnnotationSet(const OEPropDB::OEKey &key, const std::string &txt, 
                         bool notify=true)

   Sets a text annotation on the object specified by ``key`` containing the text
   specified by ``txt``. If ``notify`` is set to ``True``, VIDA will be
   notified to update the user interface to reflect this change.

.. oe:function:: AtomClearColorScoped

   .. oe:api::

      void AtomClearColorScoped(unsigned int scope = BestScope)

   This function restores the default atom coloring to those atoms within the
   specified scope.

.. oe:function:: AtomColorPaletteUpdate

   .. oe:api::

      void AtomColorPaletteUpdate()

   This function updates the default atom coloring palette based on whether or
   not the application is using a dark or light colored background scheme. This
   function is called internally and should not be called by the user.

.. oe:function:: AtomColorReferenceScoped

   .. oe:api::

      void AtomColorReferenceScoped(unsigned int scope = BestScope)

   This function provides a quick way to mark a molecule (or set of atoms) as a
   reference structure. The coloring function that is applied colors all carbon 
   atoms the current application 'reference' color (default is green). The 
   'reference' color can be changed in the preferences.

.. oe:function:: AtomColorResidueScoped

   .. oe:api::

      void AtomColorResidueScoped(unsigned int scope = BestScope)

   This function provides a quick way to color a molecule (or set of atoms) based 
   on associated residue information. The default coloring that is applied uses 
   the 'Shapely' color scheme for coloring residues. The residue colors can be 
   changed in the preferences::

    * ALA     Medium Green  [140,255,140]
    * GLY     White         [255,255,255]
    * LEU     Olive Green   [ 69, 94, 69]
    * SER     Medium Orange [255,112, 66]
    * VAL     Light Purple  [255,140,255]
    * THR     Dark Orange   [184, 76,  0]
    * LYS     Royal Blue    [ 71, 71,184]
    * ASP     Dark Rose     [160,  0, 66]
    * ILE     Dark Green    [  0, 76,  0]
    * ASN     Light Salmon  [255,124,112]
    * GLU     Dark Brown    [102,  0,  0]
    * PRO     Dark Grey     [ 82, 82, 82]
    * ARG     Dark Blue     [  0,  0,124]
    * PHE     Olive Grey    [ 83, 76, 66]
    * GLN     Dark Salmon   [255, 76, 76]
    * TYR     Medium Brown  [140,112, 76]
    * HIS     Medium Blue   [112,112,255]
    * CYS     Medium Yellow [255,255,112]
    * MET     Light Brown   [184,160, 66]
    * TRP     Olive Brown   [ 79, 70,  0]
    * ASX     Medium Purple [255,  0,255]
    * GLX     Medium Purple [255,  0,255]
    * PCA     Medium Purple [255,  0,255]
    * HYP     Medium Purple [255,  0,255]
    * A       Light Blue    [160,160,255]
    * C       Light Orange  [255,140, 75]
    * G       Medium Salmon [255,112,112]
    * T       Light Green   [160,255,160]
    * Default Medium Purple [255,  0,255]

.. oe:function:: AtomColorSetScoped

   .. oe:api::

      void AtomColorSetScoped(const OESystem::OEColor &color, 
                              unsigned int scope = BestScope)
      void AtomColorSetScoped(unsigned int element, const OESystem::OEColor &color, 
                              unsigned int scope = BestScope)

   This function sets the color of the atoms in the specified scope to be the
   specified color.

.. oe:function:: AtomDarkColorsGet

   .. oe:api::

      bool AtomDarkColorsGet()

   Returns whether or not the application is using the atom color palette designed 
   for dark colored backgrounds. Otherwise, the application is using the atom color 
   palette designed for light colored backgrounds. Both of these palettes can be
   edited in the preferences.

.. oe:function:: AtomDarkColorsSet

   .. oe:api::

      void AtomDarkColorsSet(bool dark)

   Sets whether or not the application is using the atom color palette designed 
   for dark colored backgrounds. Otherwise, the application is using the atom color 
   palette designed for light colored backgrounds. Both of these palettes can be
   edited in the preferences.
   
.. oe:function:: AtomDefaultColorGet

   .. oe:api::

      OESystem::OEColor AtomDefaultColorGet()
      OESystem::OEColor AtomDefaultColorGet(unsigned int elem)

   Returns the current default atom color. The default atom color is applied to
   every atom that does not have its own specific default color assigned. Calling
   this function with the *elem* parameter returns the specific default color 
   associated with the passed element number (e.g. carbon = 6).

.. oe:function:: AtomDefaultColorSet

   .. oe:api::

      void AtomDefaultColorSet(const OESystem::OEColor &color)
      void AtomDefaultColorSet(unsigned int elem, const OESystem::OEColor &color)

   Sets the current default atom color. The default atom color is applied to
   every atom that does not have its own specific default color assigned. Calling
   this function with the *elem* parameter sets the specific default color 
   associated with the passed element number (e.g. carbon = 6).

.. oe:function:: AtomHaloRadiusGet

   .. oe:api::

      float AtomHaloRadiusGet()

   Returns the current radius of atom selection halo. The atom selection halo is
   a transparent white surface with the specified radius drawn around the current
   selected set of atoms. If the DistanceControlsVisibility property is set (see
   DistanceControlsVisibilitySet/Get functions), only atoms falling within this
   radius will be displayed.

.. oe:function:: AtomHaloRadiusSet

   .. oe:api::

      float AtomHaloRadiusSet(float radius, bool notify=true)

   Sets the current radius of atom selection halo. The atom selection halo is
   a transparent white surface with the specified radius drawn around the current
   selected set of atoms. If the DistanceControlsVisibility property is set (see
   DistanceControlsVisibilitySet/Get functions), only atoms falling within this
   radius will be displayed.

.. oe:function:: AtomHydrogenStyleGet

   .. oe:api::

      unsigned int AtomHydrogenStyleGet()
      unsigned int AtomHydrogenStyleGet(const OEPropDB::OEKey &key)

   Returns the current default hydrogen display style - 0 for no hydrogens, 1 for 
   polar hydrogens only, and 2 for all hydrogens.

.. oe:function:: AtomHydrogenStyleSet

   .. oe:api::

      void AtomHydrogenStyleSet(unsigned int style)

   Sets the current default hydrogen display style. Valid *style* parameter values
   are 0 for no hydrogens, 1 for polar hydrogens only, and 2 for all hydrogens.

.. oe:function:: AtomHydrogenStyleSetScoped

   .. oe:api::

      void AtomHydrogenStyleSetScoped(unsigned int style, 
                                      unsigned int scope = BestScope)

   Sets the hydrogen display style for all the  molecules in the specified scope.
   Valid *style* parameter values are 0 for no hydrogens, 1 for polar hydrogens 
   only, and 2 for all hydrogens.

.. oe:function:: AtomLabelDefaultGet

   .. oe:api::

      std::string AtomLabelDefaultGet()

   Returns the default label displayed on atoms. The default is "None". See the
   AtomLabelSetScoped function for more information about label types.

.. oe:function:: AtomLabelDefaultSet

   .. oe:api::

      void AtomLabelDefaultSet(const std::string &label)

   Sets the default label displayed on atoms. The default is "None".  See the
   AtomLabelSetScoped function for more information about label types.

.. oe:function:: AtomLabelGet

   .. oe:api::

      std::string AtomLabelGet(const OEPropDB::OEKey &k)

   Returns the current label set on the specified atom.

.. oe:function:: AtomLabelSet

   .. oe:api::

      bool AtomLabelSet(const OEPropDB::OEKey &k, const std::string &label)

   Sets the label on the specified atom. The parameter *label* contains
   the text of the label and the parameter *key* specifies which atom this label 
   should apply to. See the AtomLabelSetScoped function for more information 
   about label types.

.. oe:function:: AtomLabelSetScoped

   .. oe:api::

      bool AtomLabelSetScoped(const std::string &label, 
                              unsigned int scope = BestScope)

   Sets the current label displayed on the atoms in the specified scope. Label 
   types include::

    * "none"               or ""
    * "index"              or "%i"
    * "element"            or "%e"
    * "name"               or "%n"
    * "type"               or "%t"
    * "inttype"            or "%it"
    * "implicit hcount"    or "%h"
    * "formal charge"      or "%f"
    * "partial charge"     or "%p"
    * "residue info"       or "%r"
    * "degree"             or "%d"
    * "ischiral"           or "%c"
    * "chirality"          or "%chi"
    * "hasstereospecified" or "%sts"
    * "symmetry class"     or "%sy"
    * "isinring"           or "%rng"
    * "oechem idx"         or "%oei"
    * "map index"          or "%m"
    * "read order"         or "%ro"
    * "isotope"            or "%iso"
    * "hcount"             or "%h"
    * "residue info (ca)"  or "%car"
    * "bfactor"            or "%cab"
    * "degree"             or "%d"
    * "hybrid"             or "%hyb"
    * "comment"            or "%cm"
    * "%gd(x)" - where x specifies the desired piece of generic data to use as the label

.. oe:function:: AtomStyleGet

   .. oe:api::

      std::string AtomStyleGet()

   Returns the default atom style. The default is "small". See the 
   AtomStyleSetScoped function for more information about atom styles.

.. oe:function:: AtomStyleGetScoped

   .. oe:api::

      unsigned int AtomStyleGetScoped(unsigned int scope = BestScope)

   Returns the style of the atoms in the specified scope. If there are multiple
   styles present, the return type is "mixed". See the AtomStyleSetScoped function 
   for more information about atom styles.

.. oe:function:: AtomStyleLargeGet

   .. oe:api::

      std::string AtomStyleLargeGet()

   Returns the default atom style for large molecules, where large is determined
   by whether or not the number of atoms in the molecule exceeds the specified 
   cutoff. For more information on this cutoff, see the MoleculeSizeCutoff 
   function. The default is "none". See the AtomStyleSetScoped function for more
   information about atom styles.

.. oe:function:: AtomStyleLargeSet

   .. oe:api::

      void AtomStyleLargeSet(unsigned int style)
      void AtomStyleLargeSet(const std::string &atomStyle)

   Sets the default atom style for large molecules, where large is determined
   by whether or not the number of atoms in the molecule exceeds the specified 
   cutoff. This function accepts either a string or an enumerated representation
   as its parameter. The default is "none". For more information on this large 
   molecule atom cutoff, see the MoleculeSizeCutoff function. See the 
   AtomStyleSetScoped function for more information about atom styles.

.. oe:function:: AtomStyleNucleicGet

   .. oe:api::

      std::string AtomStyleNucleicGet()

   Returns the default atom style for nucleic acids. The default is to mirror the
   large molecule atom style. See the AtomStyleLargeSet function for more 
   information about large molecules and see the AtomStyleSetScoped function for 
   more information about atom styles.

   Note: this function is a placeholder for a future implementation and therefore 
   does not currently have any effect.

.. oe:function:: AtomStyleNucleicSet

   .. oe:api::

      void AtomStyleNucleicSet(unsigned int style)
      void AtomStyleNucleicSet(const std::string &atomStyle)

   Sets the default atom style for nucleic acids. This function accepts either a 
   string or an enumerated representation as its parameter. The default is to 
   mirror the large molecule atom style. See the AtomStyleLargeSet function for 
   more information about large molecules and see the AtomStyleSetScoped function
   for more information about atom styles.

   Note: this function is a placeholder for a future implementation and therefore 
   does not currently have any effect.

.. oe:function:: AtomStyleProteinGet

   .. oe:api::

      std::string AtomStyleProteinGet()

   Returns the default atom style for proteins. The default is to mirror the large 
   molecule atom style. See the AtomStyleLargeSet function for more information 
   about large molecules and see the AtomStyleSetScoped function for more 
   information about atom styles.

   Note: this function is a placeholder for a future implementation and therefore 
   does not currently have any effect.

.. oe:function:: AtomStyleProteinSet

   .. oe:api::

      void AtomStyleProteinSet(unsigned int style)
      void AtomStyleProteinSet(const std::string &atomStyle)

   Sets the default atom style for proteins. The default is to mirror the large 
   molecule atom style. See the AtomStyleLargeSet function for more information 
   about large molecules and see the AtomStyleSetScoped function for more 
   information about atom styles.

   Note: this function is a placeholder for a future implementation and therefore 
   does not currently have any effect.

.. oe:function:: AtomStyleSet

   .. oe:api::

      void AtomStyleSet(unsigned int style)
      void AtomStyleSet(const std::string &atomStyle)

   Sets the default atom style. This function accepts either a string or an
   enumerated representation as its parameter. The default is "small". See the 
   AtomStyleSetScoped function for more information about atom styles.

.. oe:function:: AtomStyleSetScoped

   .. oe:api::

      void AtomStyleSetScoped(unsigned int style, 
                              unsigned int scope = BestScope)
      void AtomStyleSetScoped(const std::string &atomStyle, 
                              unsigned int scope = BestScope)

   Sets the display style for the specified atoms. This function accepts either a 
   string or an enumerated representation as its parameter. Available atom styles
   include::

    * "small"   atoms are drawn as small sized spheres
    * "medium"  atoms are drawn as medium sized spheres
    * "large"   atoms are drawn as large sized spheres
    * "stars"   atoms are drawn as stars
    * "radii"   atoms are drawn as spheres with radii equivalent to their VDW radii
    * "none"    atoms are not drawn, but are still considered visible and thus selectable
    * "hidden"  atoms are not drawn and are not considered visible and thus are not selectable

.. oe:function:: AtomStyleToEnum

   .. oe:api::

      unsigned int AtomStyleToEnum(const std::string &style)

   This function returns the enumerated type associated the specified string 
   atoms style representation. See the AtomStyleSetScoped function for more 
   information about atom styles.

.. oe:function:: AtomStyleToText

   .. oe:api::

      std::string AtomStyleToText(unsigned int style)

   This function returns the text string associated with the specified enumerated
   atom style representation. See the AtomStyleSetScoped function for more 
   information about atom styles.

.. oe:function:: BondBallToStickRatioGet

   .. oe:api::

      float BondBallToStickRatioGet()

   This function is currently a placeholder for future functionality.

.. oe:function:: BondBallToStickRatioSet

   .. oe:api::

      float BondBallToStickRatioSet(float ballStickRatio)

   This function is currently a placeholder for future functionality.

.. oe:function:: BondClearColorScoped

   .. oe:api::

      void BondClearColorScoped(unsigned int scope = BestScope)

   This function restores the default bond coloring to those bonds within the
   specified scope.

.. oe:function:: BondColorSetScoped

   .. oe:api::

      void BondColorSetScoped(const OESystem::OEColor &color, 
                              unsigned int scope = BestScope)

   This function sets the color of the bonds in the specified scope to be the
   specified color *c*.

.. oe:function:: BondDrawAromaticGet

   .. oe:api::

      bool BondDrawAromaticGet(unsigned int id)

   Returns whether or not aromatic bonds should be drawn as aromatic or instead
   in Kekule format for the molecule with the specified *id*.

.. oe:function:: BondDrawAromaticSet

   .. oe:api::

      bool BondDrawAromaticSet(unsigned int id, bool aromatic)

   Sets whether or not aromatic bonds should be drawn as aromatic or instead
   in kekule format for the molecule with the specified *id*.

.. oe:function:: BondHideHydrogenGet

   .. oe:api::

      bool BondHideHydrogenGet()

   Returns the global property which specifies whether or not explicit hydrogens
   should be displayed.

.. oe:function:: BondHideHydrogenSet

   .. oe:api::

      bool BondHideHydrogenSet(bool hide)

   Sets the global property which specifies whether or not explicit hydrogens
   should be displayed.

.. oe:function:: BondHideNonbondedGet

   .. oe:api::

      bool BondHideNonbondedGet()

   Returns the global property which specifies whether or not explicit non-bonded
   atoms should be displayed.

.. oe:function:: BondHideNonbondedSet

   .. oe:api::

      bool BondHideNonbondedSet(bool hide)

   Sets the global property which specifies whether or not explicit non-bonded 
   atoms should be displayed.

.. oe:function:: BondLabelDefaultGet

   .. oe:api::

      std::string BondLabelDefaultGet()

   Returns the default label displayed on bonds. The default is "None". See the
   BondLabelSetScoped function for more information about label types.

.. oe:function:: BondLabelDefaultSet

   .. oe:api::

      void BondLabelDefaultSet(const std::string &label)

   Sets the default label displayed on bonds. The default is "None".  See the
   BondLabelSetScoped function for more information about label types.

.. oe:function:: BondLabelGet

   .. oe:api::

      std::string BondLabelGet(const OEPropDB::OEKey &k)

   Returns the current label on the specified bond.

.. oe:function:: BondLabelSet

   .. oe:api::

      bool BondLabelSet(const OEPropDB::OEKey &k, const std::string &label)

   Sets the label on the specified bond. The parameter *label* contains
   the text of the label and the parameter *key* specifies which bond this label 
   should apply to. See the BondLabelSetScoped function for more information 
   about label types.

.. oe:function:: BondLabelSetScoped

   .. oe:api::

      bool BondLabelSetScoped(const std::string &label, 
                              unsigned int scope = BestScope)

   Sets the current label displayed on the bonds in the specified scope. Label 
   types include::

    * "none"               or ""
    * "index"              or "%i"
    * "order"              or "%o"
    * "length"             or "%l"
    * "type"               or "%t"
    * "inttype"            or "%it"
    * "ischiral"           or "%c"
    * "chirality"          or "%chi"
    * "hasstereospecified" or "%sts"
    * "oechem idx"         or "%oei"
    * "%gd(x)" - where x specifies the desired piece of generic data to use as the label

.. oe:function:: BondLineWidthGet

   .. oe:api::

      float BondLineWidthGet()

   Returns the line width (in pixels) to be used when drawing bonds in "line" or
   "wireframe" styles.

.. oe:function:: BondLineWidthSet

   .. oe:api::

      float BondLineWidthSet(float width)
      bool BondLineWidthSet(const OEPropDB::OEKey &k, float width)

   Sets the line width (in pixels) to be used when drawing bonds in "line" or
   "wireframe" styles.

.. oe:function:: BondRadiusGet

   .. oe:api::

      float BondRadiusGet()

   Returns the radius of the cylinders to be used when drawing bonds in "cylinder"
   style.

.. oe:function:: BondRadiusSet

   .. oe:api::

      float BondRadiusSet(float radius)
      bool BondRadiusSet(const OEPropDB::OEKey &k, float radius)

   Sets the radius of the cylinders to be used when drawing bonds in "cylinder" 
   style.

.. oe:function:: BondShowAromaticGet

   .. oe:api::

      bool BondShowAromaticGet()

   Returns the global property which specifies whether or not aromatic bonds 
   should be drawn as aromatic or instead in kekule format.

.. oe:function:: BondShowAromaticSet

   .. oe:api::

      bool BondShowAromaticSet(bool show)

   Sets the global property which specifies whether or not aromatic bonds 
   should be drawn as aromatic or instead in kekule format.

.. oe:function:: BondShowDipolarGet

   .. oe:api::

      bool BondShowDipolarGet()

   Returns the global property which specifies whether or not dipolar bonds 
   should be drawn as directed bonds.

.. oe:function:: BondShowDipolarSet

   .. oe:api::

      bool BondShowDipolarSet(bool show)

   Sets the global property which specifies whether or not dipolar bonds 
   should be drawn as directed bonds.

.. oe:function:: BondShowOrdersGet

   .. oe:api::

      bool BondShowOrdersGet()

   Returns the global property which specifies whether or not bond orders should
   be displayed.

.. oe:function:: BondShowOrdersSet

   .. oe:api::

      bool BondShowOrdersSet(bool show)

   Sets the global property which specifies whether or not bond orders should be 
   displayed.

.. oe:function:: BondStyleGet

   .. oe:api::

      std::string BondStyleGet()

   Returns the default bond style. The default is "cylinders". See the 
   BondStyleSetScoped function for more information about bond styles.

.. oe:function:: BondStyleGetScoped

   .. oe:api::

      unsigned int BondStyleGetScoped(unsigned int scope = BestScope)

   Returns the style of the bonds in the specified scope. If there are multiple
   styles present, the return type is "mixed". See the BondStyleSetScoped function 
   for more information about bond styles.

.. oe:function:: BondStyleLargeGet

   .. oe:api::

      std::string BondStyleLargeGet()

   Returns the default bond style for large molecules, where large is determined
   by whether or not the number of atoms in the molecule exceeds the specified 
   cutoff. For more information on this cutoff, see the MoleculeSizeCutoff 
   function. The default is "lines". See the BondStyleSetScoped function for more
   information about bond styles.

.. oe:function:: BondStyleLargeSet

   .. oe:api::

      void BondStyleLargeSet(unsigned int style)
      void BondStyleLargeSet(const std::string &bondstyle)

   Sets the default bond style for large molecules, where large is determined
   by whether or not the number of atoms in the molecule exceeds the specified 
   cutoff. This function accepts either a string or an enumerated representation
   as its parameter. The default is "lines". For more information on this large 
   molecule atom cutoff, see the MoleculeSizeCutoff function. See the 
   BondStyleSetScoped function for more information about bond styles.

.. oe:function:: BondStyleNucleicGet

   .. oe:api::

      std::string BondStyleNucleicGet()

   Returns the default bond style for nucleic acids. The default is to mirror the
   large molecule bond style. See the BondStyleLargeSet function for more 
   information about large molecules and see the BondStyleSetScoped function for 
   more information about bond styles.

   Note: this function is a placeholder for a future implementation and therefore 
   does not currently have any effect.

.. oe:function:: BondStyleNucleicSet

   .. oe:api::

      void BondStyleNucleicSet(unsigned int style)
      void BondStyleNucleicSet(const std::string &bondstyle)

   Sets the default bond style for nucleic acids. This function accepts either a 
   string or an enumerated representation as its parameter. The default is to 
   mirror the large molecule atom style. See the AtomStyleLargeSet function for 
   more information about large molecules and see the AtomStyleSetScoped function
   for more information about atom styles.

   Note: this function is a placeholder for a future implementation and therefore 
   does not currently have any effect.

.. oe:function:: BondStyleProteinGet

   .. oe:api::

      std::string BondStyleProteinGet()

   Returns the default bond style for proteins. The default is to mirror the large 
   molecule bond style. See the BondStyleLargeSet function for more information 
   about large molecules and see the BondStyleSetScoped function for more 
   information about bond styles.

   Note: this function is a placeholder for a future implementation and therefore 
   does not currently have any effect.

.. oe:function:: BondStyleProteinSet

   .. oe:api::

      void BondStyleProteinSet(unsigned int style)
      void BondStyleProteinSet(const std::string &bondstyle)

   Sets the default bond style for proteins. The default is to mirror the large 
   molecule bond style. See the BondStyleLargeSet function for more information 
   about large molecules and see the BondStyleSetScoped function for more 
   information about bond styles.

   Note: this function is a placeholder for a future implementation and therefore 
   does not currently have any effect.

.. oe:function:: BondStyleSet

   .. oe:api::

      void BondStyleSet(unsigned int style)
      void BondStyleSet(const std::string &bondstyle)

   Sets the default bond style. This function accepts either a string or an
   enumerated representation as its parameter. The default is "cylinders". See the 
   BondStyleSetScoped function for more information about bond styles.

.. oe:function:: BondStyleSetScoped

   .. oe:api::

      void BondStyleSetScoped(unsigned int style, 
                              unsigned int scope = BestScope)
      void BondStyleSetScoped(const std::string &bondstyle, 
                              unsigned int scope = BestScope)

   Sets the display style for the specified bonds. This function accepts either a 
   string or an enumerated representation as its parameter. Available bonds styles
   include::

    * "lines"     bonds are drawn as lines
    * "cylinders" bonds are drawn as cylinders
    * "none"      bonds are not drawn, but are still considered visible and thus selectable
    * "hidden"    bonds are not drawn and are not considered visible and thus are not selectable

.. oe:function:: BondStyleToEnum

   .. oe:api::

      unsigned int BondStyleToEnum(const std::string &style)

   This function returns the enumerated type associated the specified string 
   bond style representation. See the BondStyleSetScoped function for more 
   information about bond styles.

.. oe:function:: BondStyleToText

   .. oe:api::

      std::string BondStyleToText(unsigned int style)

   This function returns the text string associated with the specified enumerated
   bond style representation. See the BondStyleSetScoped function for more 
   information about bond styles.

.. oe:function:: BookmarkDelete

   .. oe:api::

      bool BookmarkDelete(const std::string &name)

   Deletes the bookmark specified by *name*.

.. oe:function:: BookmarkExists

   .. oe:api::

      bool BookmarkExists(const std::string &name)

   Returns whether or not the specified bookmark exists.

.. oe:function:: BookmarkLoad

   .. oe:api::

      bool BookmarkLoad(const std::string &name)

   Loads the specified bookmark.

.. oe:function:: BookmarkMoveDown

   .. oe:api::

      bool BookmarkMoveDown(const std::string &name)

   Moves the specified bookmark down in the order of the current set of bookmarks.

.. oe:function:: BookmarkMoveUp

   .. oe:api::

      bool BookmarkMoveUp(const std::string &name)

   Moves the specified bookmark up in the order of the current set of bookmarks.

.. oe:function:: BookmarkOrganizeDialog

   .. oe:api::

      std::string BookmarkOrganizeDialog(bool exec=false)

   Launches an interactive dialog which allows the user to delete, rename, and 
   reorder the current set of bookmarks.

.. oe:function:: PromptBookmarkAnimationTime

   .. oe:api::

      int PromptBookmarkAnimationTime( int originalTime )

   Launches an interactive dialog which allows the user to specify the animation
   duration when transitioning to a selected bookmark. Two options are provided::

    * "Use calculated animation time"          automatically calculated using limits on speed of rotation, scaling and translation.
    * "Specify animation time in milliseconds" specified by the user.

.. oe:function:: BookmarkRename

   .. oe:api::

      bool BookmarkRename(const std::string &oldName, const std::string &newName)

   Changes the name of the bookmark specified by *oldName* to the name specified
   by *newName*.

.. oe:function:: BookmarkSave

   .. oe:api::

      bool BookmarkSave(const std::string &name)

   Saves the current state of the application to a named bookmark specified by 
   the parameter *name*.

.. oe:function:: Bookmarks

   .. oe:api::

      std::vector<std::string> Bookmarks()

   Returns a list of the current set of bookmarks.

.. oe:function:: BookmarksClear

   .. oe:api::

      void BookmarksClear()

   Clears the current list of bookmarks.

.. oe:function:: BookmarksLastLoaded

   .. oe:api::

      unsigned int BookmarksLastLoaded()

   Returns the index (in the order of the current set of bookmarks) of the last
   bookmark that was loaded.

.. oe:function:: CATraceRadiusGet

   .. oe:api::

      float CATraceRadiusGet()

   Returns the global property which specifies the width of CA Traces.

.. oe:function:: CATraceRadiusSet

   .. oe:api::

      float CATraceRadiusSet(float radius)

   Sets the global property which specifies the width of CA Traces.

.. oe:function:: CATraceStyleGet

   .. oe:api::

      std::string CATraceStyleGet()
      std::string CATraceStyleGet(const OEPropDB::OEKey &k)

   Returns the global property which specifies the style in which CA Traces are
   drawn. Available styles include: "lines" and "cylinders".

.. oe:function:: CATraceStyleSet

   .. oe:api::

      std::string CATraceStyleSet(const std::string &style)
      std::string CATraceStyleSet(const OEPropDB::OEKey &k, const std::string &style)

   Sets the global property which specifies the style in which CA Traces are
   drawn. Available styles include: "lines" and "cylinders".

.. oe:function:: CATraceStyleSetScoped

   .. oe:api::

      std::string CATraceStyleSetScoped(const std::string &str, 
                                        unsigned int scope = BestScope)

   Sets the property which specifies the style in which CA Traces are
   drawn. Available styles include: "lines" and "cylinders".

.. oe:function:: CenterSet

   .. oe:api::

      void CenterSet(const OEPropDB::OEKey &)
      void CenterSet(const std::vector<OEPropDB::OEKey> &)

   Sets the center of the scene to be at the center of the object(s) referenced
   by the specified key(s).

.. oe:function:: CenterSetScoped

   .. oe:api::

      void CenterSetScoped(unsigned int scope)

   Scoped version of :oe:func:`CenterSet`.

.. oe:function:: ColorGet

   .. oe:api::

      OESystem::OEColor ColorGet(const OEPropDB::OEKey &)

   Returns the color of the object specified by the OEKey parameter *key*.

.. oe:function:: ColorSet

   .. oe:api::

      void ColorSet(const OEPropDB::OEKey &, const OESystem::OEColor &)

   Sets the color of the object specified by the OEKey parameter *key* to be
   the specified *color*.

.. oe:function:: ColorSetScoped

   .. oe:api::

      void ColorSetScoped(const OESystem::OEColor &, 
                          unsigned int scope = BestScope)

   Sets the color for all of the objects in the specified scope to be the 
   specified *color*.

.. oe:function:: ColorUniqueScoped

   .. oe:api::

      void ColorUniqueScoped(unsigned int scope = BestScope)

   Assigns a "unique" color to each individual object found in the specified
   *scope*. For large numbers of objects in the scope, the colors used may 
   eventually repeat.

.. oe:function:: ContourAutoCenterGet

   .. oe:api::

      bool ContourAutoCenterGet(unsigned int id=0)

   Returns whether or not reentrant grids are automatically contoured at the 
   center of the scene.

.. oe:function:: ContourAutoCenterSet

   .. oe:api::

      bool ContourAutoCenterSet(unsigned int id, bool center)

   Sets whether or not reentrant grids are automatically contoured at the 
   center of the scene. If this is set to true, translating the center of the
   scene will cause the grids to be recontoured as the scene moves.

.. oe:function:: ContourAutoContourGet

   .. oe:api::

      bool ContourAutoContourGet()

   Returns whether or not reentrant grids are automatically recontoured when
   the center of the scene is changed.

.. oe:function:: ContourAutoContourRadiusScaleSet

   .. oe:api::

      bool ContourAutoContourRadiusScaleSet(float radius, float scale)

   Sets the radius and scale parameters used in determining how to contour a 
   reentrant grid around the center of the scene.

.. oe:function:: ContourAutoContourSet

   .. oe:api::

      void ContourAutoContourSet(bool autocontour)

   Sets whether or not reentrant grids are automatically recontoured when
   the center of the scene is changed.

.. oe:function:: ContourCenter

   .. oe:api::

      std::vector<float> ContourCenter(unsigned int id=0)
      std::vector<float> ContourCenter(unsigned int id, std::vector<float>)

   Returns the scene center position associated with the specified contour.

.. oe:function:: ContourColorForIndexGet

   .. oe:api::

      OESystem::OEColor ContourColorForIndexGet(unsigned int id, unsigned int index)

   Return the color of the grid contour specified by the grid *id* and 
   contour *index*.

.. oe:function:: ContourColorForIndexGetScoped

   .. oe:api::

      OESystem::OEColor ContourColorForIndexGetScoped(unsigned int index, 
                                                      unsigned int scope = BestScope)

   Returns the color of the grid contours in the specified scope at 
   contour index *index*. This color is determined by looking at the first
   contour found in the specified scope.

.. oe:function:: ContourColorForIndexSet

   .. oe:api::

      OESystem::OEColor ContourColorForIndexSet(unsigned int id, unsigned int index, 
                                                const OESystem::OEColor &color)

   For grid *id* set the color of contour *index* to *color*.

.. oe:function:: ContourColorForIndexSetScoped

   .. oe:api::

      OESystem::OEColor ContourColorForIndexSetScoped(unsigned int index, 
                                                      const OESystem::OEColor &color, 
                                                      unsigned int scope = BestScope)

   For all grids in *scope* set the color of contour *index* to *color*.

.. oe:function:: ContourColorSet

   .. oe:api::

      void ContourColorSet(const OEPropDB::OEKey &, const OESystem::OEColor &)

   This function sets the color of the contour associated with the specified key.

.. oe:function:: ContourColorSetScoped

   .. oe:api::

      void ContourColorSetScoped(const OESystem::OEColor &, 
                                 unsigned int scope = BestScope)

   This function sets the color of the contours in the specified scope.

.. oe:function:: ContourDrawAsSurfaceGet

   .. oe:api::

      bool ContourDrawAsSurfaceGet(unsigned int id=0)

   Returns whether or not the contour should be drawn as a solid surface or as a 
   mesh.

.. oe:function:: ContourDrawAsSurfaceSet

   .. oe:api::

      bool ContourDrawAsSurfaceSet(unsigned int id, bool draw)

   Sets whether or not the contour should be drawn as a solid surface or as a 
   mesh.

.. oe:function:: ContourDrawAsSurfaceSetScoped

   .. oe:api::

      void ContourDrawAsSurfaceSetScoped(bool draw, 
                                         unsigned int scope = BestScope)

   Returns the style of contour drawing for the surfaces in scope; essentially
   it returns the state of the first grid found in scope.

   See :oe:func:`ContourDrawAsSurfaceGet`.

.. oe:function:: ContourDrawStyleGet

   .. oe:api::

      std::string ContourDrawStyleGet(unsigned int id=0)

   If "surface" the contours are drawn as a surface, otherwise the contour is
   drawn as a mesh.

.. oe:function:: ContourDrawStyleSet

   .. oe:api::

      void ContourDrawStyleSet(unsigned int id, const std::string &)

   If set to "surface" the contours are drawn as a surface, otherwise the contour is
   drawn as a mesh.

.. oe:function:: ContourDrawStyleSetScoped

   .. oe:api::

      void ContourDrawStyleSetScoped(const std::string &style, 
                                     unsigned int scope = BestScope)

   Set the drawstyle to all contours in scope.

.. oe:function:: ContourEntireGridGet

   .. oe:api::

      bool ContourEntireGridGet(unsigned int id=0)

   Returns True if grid *id* is contoured over the whole grid. Returns False 
   if only the portion near the center of the scene is contoured.

.. oe:function:: ContourEntireGridSet

   .. oe:api::

      bool ContourEntireGridSet(unsigned int id, bool entire)

   If true contour the entire extent of grid *id*, otherwise only contour the
   portion near the center of the drawing scene.

.. oe:function:: ContourHideIndex

   .. oe:api::

      void ContourHideIndex(unsigned int index, bool hide)
      void ContourHideIndex(unsigned int id, unsigned int index, bool hide)

   This function controls the visibility of the contour specified by the grid *id*
   and contour *index*. If the *hide* parameter is set to true, the contour is 
   hidden, otherwise the contour is shown.

.. oe:function:: ContourHideIndexGet

   .. oe:api::

      bool ContourHideIndexGet(unsigned int id, unsigned int index)

   This function returns whether or not the contour specified by the grid *id*
   and contour *index* is hidden or not.

.. oe:function:: ContourHideIndexSet

   .. oe:api::

      void ContourHideIndexSet(unsigned int index, bool hide)
      void ContourHideIndexSet(unsigned int id, unsigned int index, bool hide)

   This function controls the visibility of the contour specified by the grid *id*
   and contour *index*. If the *hide* parameter is set to true, the contour is 
   hidden, otherwise the contour is shown.

.. oe:function:: ContourLineWidthGet

   .. oe:api::

      float ContourLineWidthGet(unsigned int id=0)

   Returns the line width for drawing mesh contours.

.. oe:function:: ContourLineWidthSet

   .. oe:api::

      float ContourLineWidthSet(unsigned int id, float rad)

   Set the line width to *width* for drawing mesh contours.

.. oe:function:: ContourPickIsoSurfacesGet

   .. oe:api::

      bool ContourPickIsoSurfacesGet()

   Returns whether or not contours are selectable by picking.

.. oe:function:: ContourPickIsoSurfacesSet

   .. oe:api::

      void ContourPickIsoSurfacesSet(bool pickable)

   Sets whether or not contours are selectable by picking.

.. oe:function:: ContourTransparencySet

   .. oe:api::

      void ContourTransparencySet(const OEPropDB::OEKey &, unsigned int)

   Sets the transparency of the contour associated with the specified key. The 
   transparency is determined by the *alpha* parameter which corresponds to the
   color alpha value which can range from 0 (completely transparent) to 255 
   (completely opaque).

.. oe:function:: CustomViewEON
   :project: VIDA

   .. oe:api::

      void CustomViewEON()
      void CustomViewEON(const std::string &results, const std::string &reference="")
      void CustomViewEON(const std::string &results, const std::string &reference, 
                         bool refIsFirst, bool tiled, bool showSpreadsheet, 
                         bool showStyleControl,
                         unsigned int maxTiles)

   This function sets up the display for optimal visualization of output from the
   application EON.

.. oe:function:: CustomViewFRED
   :project: VIDA

   .. oe:api::

      void CustomViewFRED()
      void CustomViewFRED(const std::string &protein, const std::string &reference, 
                          const std::string &results="")
      void CustomViewFRED(const std::string &protein, const std::string &reference, 
                          const std::string &results, bool showRibbons, bool showLabels, 
                          bool showHBonds, bool showSurface, float residueWithin, 
                          float surfaceWithin, const std::string &surfaceColor)

   This function sets up the display for optimal visualization of output from the
   application FRED.

.. oe:function:: CustomViewROCS
   :project: VIDA

   .. oe:api::

      void CustomViewROCS()
      void CustomViewROCS(const std::string &results, 
                          const std::string &reference="")
      void CustomViewROCS(const std::string &results, const std::string &reference, 
                          bool refIsFirst, bool tiled, bool showSpreadsheet, 
                          bool unused, bool showStyleControl,
                          unsigned int maxTiles)

   This function sets up the display for optimal visualization of output from the
   application ROCS.

.. oe:function:: DefaultColorLabelGet

   .. oe:api::

      OESystem::OEColor DefaultColorLabelGet()

   Returns the default color for a label.

.. oe:function:: DefaultColorLabelSet

   .. oe:api::

      OESystem::OEColor DefaultColorLabelSet(const OESystem::OEColor &)

   Returns the default color for a label.

.. oe:function:: DefaultColorMarkedGet

   .. oe:api::

      OESystem::OEColor DefaultColorMarkedGet()

   Returns the default color used when displaying marked objects.

.. oe:function:: DefaultColorMarkedSet

   .. oe:api::

      OESystem::OEColor DefaultColorMarkedSet(const OESystem::OEColor &)

   Sets the default color used when displaying marked objects.

.. oe:function:: DefaultColorReferenceGet

   .. oe:api::

      OESystem::OEColor DefaultColorReferenceGet()

   Returns the default reference molecule color.

.. oe:function:: DefaultColorReferenceSet

   .. oe:api::

      OESystem::OEColor DefaultColorReferenceSet(const OESystem::OEColor &)

   Sets the default reference molecule color.

.. oe:function:: DefaultColorSelectedGet

   .. oe:api::

      OESystem::OEColor DefaultColorSelectedGet()

   Returns the default selection color.

.. oe:function:: DefaultColorSelectedSet

   .. oe:api::

      OESystem::OEColor DefaultColorSelectedSet(const OESystem::OEColor &)

   Sets the default selection color.

.. oe:function:: DefaultColorTitleGet

   .. oe:api::

      OESystem::OEColor DefaultColorTitleGet()

   Returns the default title color.
  
.. oe:function:: DefaultColorTitleSet

   .. oe:api::

      OESystem::OEColor DefaultColorTitleSet(const OESystem::OEColor &)

   Sets the default title color.

.. oe:function:: DefaultMonitorColorGet

   .. oe:api::

      OESystem::OEColor DefaultMonitorColorGet()

   Returns the default monitor color.

.. oe:function:: DefaultMonitorColorSet

   .. oe:api::

      OESystem::OEColor DefaultMonitorColorSet(const OESystem::OEColor &)

   Sets the default monitor color.
  
.. oe:function:: DistanceControlsVisibilityGet

   .. oe:api::

      bool DistanceControlsVisibilityGet()

   Returns whether or not an atom's or bond's distance from the selected set will
   affect its visibility. The distance cutoff is specified by the AtomHaloSet 
   function.

.. oe:function:: DistanceControlsVisibilitySet

   .. oe:api::

      void DistanceControlsVisibilitySet(bool state)

   Sets whether or not an atom's or bond's distance from the selected set will
   affect its visibility. The distance cutoff is specified by the AtomHaloSet 
   function.

.. oe:function:: DrawAtomsAndBondsGet

   .. oe:api::

      bool DrawAtomsAndBondsGet()

   Returns whether or not the application has drawing of atoms and bonds enabled.
   Ordinarily, this function should not need to be called by the user.

.. oe:function:: DrawAtomsAndBondsSet

   .. oe:api::

      bool DrawAtomsAndBondsSet(bool draw)

   Sets whether or not the application has drawing of atoms and bonds enabled.
   Ordinarily, this function should not need to be called by the user.

.. oe:function:: DrawAxesGet

   .. oe:api::

      bool DrawAxesGet()

   Returns whether or not axes should be drawn in the application's 3D display.

.. oe:function:: DrawAxesSet

   .. oe:api::

      bool DrawAxesSet(bool draw)

   Sets whether or not axes should be drawn in the application's 3D display.

.. oe:function:: DrawCATracesGet

   .. oe:api::

      bool DrawCATracesGet()
      bool DrawCATracesGet(const OEPropDB::OEKey &k)

   Returns whether or not the application has drawing of CA Traces enabled.
   Ordinarily, this function should not need to be called by the user.

.. oe:function:: DrawCATracesSet

   .. oe:api::

      bool DrawCATracesSet(bool draw)
      bool DrawCATracesSet(const OEPropDB::OEKey &, bool draw)

   Sets whether or not the application has drawing of CA Traces enabled.
   Ordinarily, this function should not need to be called by the user.

.. oe:function:: DrawCATracesSetScoped

   .. oe:api::

      bool DrawCATracesSetScoped(bool, unsigned int scope = BestScope)

   Sets whether or not a CA Trace should be drawn the proteins in the specified
   scope.

.. oe:function:: DrawContoursGet

   .. oe:api::

      bool DrawContoursGet()

   Returns true if the contours are being drawn.  Returns false if no contours
   are being drawn.

.. oe:function:: DrawContoursSet

   .. oe:api::

      bool DrawContoursSet(bool draw)

   If *draw* is true, then draw all contours for each visible grid.  Otherwise
   no contours are drawn.

.. oe:function:: DrawLabelsGet

   .. oe:api::

      bool DrawLabelsGet()

   Returns whether or not the application has drawing of labels enabled.

.. oe:function:: DrawLabelsSet

   .. oe:api::

      bool DrawLabelsSet(bool draw)

   Sets whether or not the application has drawing of labels enabled.

.. oe:function:: DrawMatrixGet

   .. oe:api::

      bool DrawMatrixGet()

   Returns whether or not the application has matrix (or tiled) displays enabled.

.. oe:function:: DrawMatrixSet

   .. oe:api::

      bool DrawMatrixSet(bool draw)

   Sets whether or not the application has matrix (or tiled) displays enabled.

.. oe:function:: DrawRibbonsGet

   .. oe:api::

      bool DrawRibbonsGet()
      bool DrawRibbonsGet(const OEPropDB::OEKey &k)

   Returns whether or not the application has drawing of protein ribbons enabled.
   Ordinarily, this function should not need to be called by the user.

.. oe:function:: DrawRibbonsSet

   .. oe:api::

      bool DrawRibbonsSet(bool draw)
      bool DrawRibbonsSet(const OEPropDB::OEKey &k, bool draw)

   Sets whether or not the application has drawing of protein ribbons enabled.
   Ordinarily, this function should not need to be called by the user.

.. oe:function:: DrawRibbonsSetScoped

   .. oe:api::

      bool DrawRibbonsSetScoped(bool draw, 
                                unsigned int scope = BestScope)

   Sets whether or not a ribbon display should be shown for the proteins in the
   specified scope.

.. oe:function:: DrawSurfacesGet

   .. oe:api::

      bool DrawSurfacesGet()

   Returns true if surfaces are being drawn, false if not.

.. oe:function:: DrawSurfacesSet

   .. oe:api::

      bool DrawSurfacesSet(bool draw)

   If parameter *draw* if false, surface objects are not drawn.  If *draw* is
   true surfaces are drawn.

.. oe:function:: DrawSymmetryGet

   .. oe:api::

      bool DrawSymmetryGet()

   Returns whether or not the application has drawing of symmetry enabled.

.. oe:function:: DrawSymmetrySet

   .. oe:api::

      bool DrawSymmetrySet(bool draw)

   Sets whether or not the application has drawing of symmetry enabled.

.. oe:function:: DrawTitlesGet

   .. oe:api::

      bool DrawTitlesGet()

   Returns whether or not the application has drawing of titles enabled.

.. oe:function:: DrawTitlesSet

   .. oe:api::

      bool DrawTitlesSet(bool draw)

   Sets whether or not the application has drawing of symmetry enabled.

.. oe:function:: DrawUnitCellGet

   .. oe:api::

      bool DrawUnitCellGet()

   Returns whether or not the application has drawing of unit cells enabled.

.. oe:function:: DrawUnitCellSet

   .. oe:api::

      bool DrawUnitCellSet(bool draw)

   Sets whether or not the application has drawing of symmetry enabled.

.. oe:function:: GridDefaultContourColorByIndexGet

   .. oe:api::

      OESystem::OEColor GridDefaultContourColorByIndexGet(unsigned int gridType, 
                                                          unsigned int index)

   Returns the default contour color for contour *index* for grids of type *gridType*.

.. oe:function:: GridDefaultContourColorByIndexSet

   .. oe:api::

      void GridDefaultContourColorByIndexSet(unsigned int gridType, 
                                             unsigned int index, 
                                             const OESystem::OEColor &color)

   Set the default contour *color* for contour *index* for grids of type *gridType*.

.. oe:function:: GridDefaultDrawAsSurfaceGet

   .. oe:api::

      bool GridDefaultDrawAsSurfaceGet(unsigned int gridType)

   Returns the default drawing style for contours of grid with type *gridType*.

   If true, then the surface is drawn as a solid surface, otherwise the surface
   is drawn as a mesh.

.. oe:function:: GridDefaultDrawAsSurfaceSet

   .. oe:api::

      void GridDefaultDrawAsSurfaceSet(unsigned int gridType, bool asSurf)

   Set the default drawing style *asSurf* for contours of grid with type *gridType*.

   If *asSurf* is true, then the surface is drawn as a solid surface, otherwise the surface
   is drawn as a mesh.

.. oe:function:: GridShowCornersGet

   .. oe:api::

      bool GridShowCornersGet()

   Returns true if grid corners are being shown false if not.

   Grid corners are indicators of the extent of visible grids.  They are
   useful for displaying uncontoured grids and showing whether grid space 
   and molecules intersect.

.. oe:function:: GridShowCornersSet

   .. oe:api::

      void GridShowCornersSet(bool show)

   Set *show* to true to show grid corners, false if not.

   Grid corners are indicators of the extent of visible grids.  They are
   useful for displaying uncontoured grids and showing whether grid space 
   and molecules intersect.

.. oe:function:: GridShowLastMaskedGrid

   .. oe:api::

      unsigned int GridShowLastMaskedGrid(bool show=true)

   Reserved for internal use.

.. oe:function:: HBondAddTarget

   .. oe:api::

      void HBondAddTarget(const OEPropDB::OEKey &key)

   This function adds the molecule corresponding to the specified *key* to the
   list of targets to be considered when displaying hydrogen bonds. Calling 
   this function on a molecule will cause hydrogens to be added to that molecule
   if they are not already present.

.. oe:function:: HBondAddTargetsScoped

   .. oe:api::

      void HBondAddTargetsScoped(unsigned int scope = BestScope)

   This function adds of the molecules in the specified *scope* to the list of
   targets to be considered when displaying hydrogen bonds. Calling this function 
   on a molecule will cause hydrogens to be added to that molecule if they are not 
   already present.

.. oe:function:: HBondClearTargets

   .. oe:api::

      void HBondClearTargets()

   This function clears the list of molecule targets to be considered when 
   displaying hydrogen bonds.

.. oe:function:: HBondColorGet

   .. oe:api::

      OESystem::OEColor HBondColorGet()

   Returns the current color being used when drawing hydrogen bonds.

.. oe:function:: HBondColorSet

   .. oe:api::

      void HBondColorSet(const OESystem::OEColor &)

   Sets the color to be used when drawing hydrogen bonds.

.. oe:function:: HBondRemoveTarget

   .. oe:api::

      void HBondRemoveTarget(const OEPropDB::OEKey &key)

   This function removes the molecule corresponding to the specified *key* from 
   the list of molecule targets to be considered when displaying hydrogen bonds.

.. oe:function:: HBondRemoveTargetsScoped

   .. oe:api::

      void HBondRemoveTargetsScoped(unsigned int scope = BestScope)

   This function removes all of the molecules in the specified *scope* from 
   the list of molecule targets to be considered when displaying hydrogen bonds.

.. oe:function:: HBondShowExternalGet

   .. oe:api::

      bool HBondShowExternalGet()

   Returns whether or not external hydrogen bonds (those between two separate
   molecules) should be displayed if present.

.. oe:function:: HBondShowExternalSet

   .. oe:api::

      void HBondShowExternalSet(bool show)

   Sets whether or not external hydrogen bonds (those between two separate
   molecules) should be displayed if present.

.. oe:function:: HBondShowInternalGet

   .. oe:api::

      bool HBondShowInternalGet()

   Returns whether or not internal hydrogen bonds should be displayed if present.

.. oe:function:: HBondShowInternalSet

   .. oe:api::

      void HBondShowInternalSet(bool show)

   Sets whether or not internal hydrogen bonds should be displayed if present.

.. oe:function:: HaloColorDefaultGet

   .. oe:api::

      OESystem::OEColor HaloColorDefaultGet()

   Returns the default color to be used when displaying halos.

.. oe:function:: HaloColorDefaultSet

   .. oe:api::

      void HaloColorDefaultSet(const OESystem::OEColor &c)

   Sets the default color to be used when displaying halos.

.. oe:function:: HaloColorGet

   .. oe:api::

      OESystem::OEColor HaloColorGet(const OEPropDB::OEKey &)

   Returns the color of the halo associated with the specified atom key.

.. oe:function:: HaloColorSet

   .. oe:api::

      void HaloColorSet(const OEPropDB::OEKey &k, const std::string &)
      void HaloColorSet(const OEPropDB::OEKey &k, const OESystem::OEColor &c)

   Sets the color of the halo associated with the specified atom key.

.. oe:function:: HaloColorSetScoped

   .. oe:api::

      void HaloColorSetScoped(const std::string &, 
                              unsigned int scope = BestScope)
      void HaloColorSetScoped(const OESystem::OEColor &, 
                              unsigned int scope = BestScope)

   Sets the color of the halos associated with the atoms in the specified scope.

.. oe:function:: HaloRadiusGet

   .. oe:api::

      float HaloRadiusGet(const OEPropDB::OEKey &)

   Returns the radius of the halo associated with the specified atom key.

.. oe:function:: HaloRadiusSet

   .. oe:api::

      void HaloRadiusSet(const OEPropDB::OEKey &, float)
      void HaloRadiusSet(const OEPropDB::OEKey &, const std::string &)

   Sets the radius of the halo associated with the specified atom key.

.. oe:function:: HaloRadiusSetScoped

   .. oe:api::

      void HaloRadiusSetScoped(float, unsigned int scope = BestScope)
      void HaloRadiusSetScoped(const std::string &, 
                               unsigned int scope = BestScope)

   Sets the radius of the halos associated with the atoms in the specified scope.

.. oe:function:: HaloScaleGet

   .. oe:api::

      float HaloScaleGet(const OEPropDB::OEKey &)

   Returns the scaling factor for the size of the halo associated with the 
   specified atom key.

.. oe:function:: HaloScaleSet

   .. oe:api::

      void HaloScaleSet(const OEPropDB::OEKey &, float)
      void HaloScaleSet(const OEPropDB::OEKey &, const std::string &)

   Sets the scaling factor for the size of the halo associated with the 
   specified atom key.

.. oe:function:: HaloScaleSetScoped

   .. oe:api::

      void HaloScaleSetScoped(float, unsigned int scope = BestScope)
      void HaloScaleSetScoped(const std::string &, 
                              unsigned int scope = BestScope)

   Sets the scaling factor for the size of the halo associated with the 
   atoms in the specified scope.

.. oe:function:: HideNoneScoped

   .. oe:api::

      void HideNoneScoped(unsigned int scope = BestScope)

  Makes visible any hidden atoms or bonds on all the molecules in the specified
  scope.

.. oe:function:: HideOthers

   .. oe:api::

      void HideOthers(const std::vector<OEPropDB::OEKey> &keys, bool value)

  Hides everything except the objects specified by list of keys passed as a
  parameter to this function.

.. oe:function:: HideScoped

   .. oe:api::

      void HideScoped(bool value, unsigned int scope = BestScope)

  Hides everything in the specified scope.

.. oe:function:: LabelClearColorScoped

   .. oe:api::

      void LabelClearColorScoped(unsigned int scope = BestScope)

   This function restores the default label coloring to those labels within the
   specified scope.

.. oe:function:: LabelClearScoped

   .. oe:api::

      void LabelClearScoped(unsigned int scope = BestScope)

   Clears the labels on all the atoms and bonds in the specified scope.

.. oe:function:: LabelColorScoped

   .. oe:api::

      void LabelColorScoped(const OESystem::OEColor &c, 
                            unsigned int scope = BestScope)

   This function sets the color of the labels in the specified scope to be the
   specified color *c*.

.. oe:function:: LabelDefaultColorGet

   .. oe:api::

      OESystem::OEColor LabelDefaultColorGet()

   This function returns the default color for labels.

.. oe:function:: LabelDefaultColorSet

   .. oe:api::

      void LabelDefaultColorSet(const OESystem::OEColor &c)

   This function sets the default color for labels.

.. oe:function:: LabelFixedSizeGet

   .. oe:api::

      bool LabelFixedSizeGet()

   Returns whether or not labels are drawn using a fixed size on the screen or 
   whether they scale with zooming of the scene.

.. oe:function:: LabelFixedSizeSet

   .. oe:api::

      void LabelFixedSizeSet(bool fixed)

   Sets whether or not labels are drawn using a fixed size on the screen or 
   whether they scale with zooming of the scene.

.. oe:function:: LabelGet

   .. oe:api::

      std::string LabelGet(const OEPropDB::OEKey &key, bool full=false, 
                           bool coords=true)

   Returns a description of the specified object. If the *full* parameter is
   True, it will also include information from the parent object (if one 
   exists). The *coords* parameter specifies whether or not coordinates should
   be included in the description (primarily for atoms and vertices).

.. oe:function:: MoleculeAltLocationShow

   .. oe:api::

      bool MoleculeAltLocationShow(const OEPropDB::OEKey &, unsigned int, bool)
      bool MoleculeAltLocationShow(const OEPropDB::OEKey &, unsigned int, unsigned int, 
                                   unsigned int)

   Sets the visibility of the specified alternate locations for the specified 
   molecule. This function is primarily intended for internal use only.

.. oe:function:: MoleculeAltLocationVisible

   .. oe:api::

      bool MoleculeAltLocationVisible(const OEPropDB::OEKey &, unsigned int)
      bool MoleculeAltLocationVisible(const OEPropDB::OEKey &, unsigned int, 
                                      unsigned int)

   Returns whether or the specified alternate locations on the specified 
   molecule are visible. This function is primarily intended for internal use
   only.

.. oe:function:: MoleculeAtomBondStyleSetScoped

   .. oe:api::

      void MoleculeAtomBondStyleSetScoped(const std::string &atomStyle, 
                                          const std::string &bondStyle, 
                                          unsigned int scope = BestScope)

   Set the combined style for atoms and bonds.

   * atomStyle is the style to set the atom , see AtomStyleSetScoped.
   * bondStyle is the style to set the bond, see BondStyleSetScoped.
   * scope is the default scope to use.

.. oe:function:: MoleculeColorByScoped

   .. oe:api::

      void MoleculeColorByScoped(const std::string &property, 
                                 const std::string &params="", 
                                 unsigned int scope = BestScope)

   This color colors all the molecules in the specified scope according to the
   scheme specified by the *property* parameter. Valid properties include::

    * "amino"
    * "bfactor"
    * "chain"
    * "charge"
    * "cpk"
    * "cpknew"
    * "formal charge"
    * "group"
    * "hbond"
    * "hydrophobicity"
    * "partial charge"
    * "shapely"
    
   If the specified property is *hydrophobicity*, the specific scale to be used
   can be specified in the *params* parameter. Valid scale options include::

    * "charifson"
    * "eisenberg"
    * "kytedolittle"
    * "whiteoctanol"
    
   For more details on the specifics of these coloring scheme, please see the user
   manual.

.. oe:function:: MoleculeColorsResetScoped

   .. oe:api::

      void MoleculeColorsResetScoped(unsigned int scope = BestScope)

   This function restores the default atom and bond coloring to those atoms and
   bonds in the specified scope. It is essentially equivalent to calling 
   AtomClearColorScoped followed by BondClearColorScoped.

.. oe:function:: MoleculeDarkColorsGet

   .. oe:api::

      bool MoleculeDarkColorsGet()

   Returns whether or not the application is using either the atom or residue 
   color palette designed for dark colored backgrounds. Otherwise, the 
   application is using the atom color palettes designed for light colored 
   backgrounds. All of these palettes can be edited in the preferences. For more 
   information, see the functions AtomDarkColorsGet and ResidueDarkColorsGet.

.. oe:function:: MoleculeDarkColorsSet

   .. oe:api::

      void MoleculeDarkColorsSet(bool dark)

   Sets whether or not the application is using the atom and residue 
   color palettes designed for dark colored backgrounds. Otherwise, the 
   application is using the atom color palettes designed for light colored 
   backgrounds. All of these palettes can be edited in the preferences. For more 
   information, see the functions AtomDarkColorsSet and ResidueDarkColorsSet.

.. oe:function:: MoleculeShowfAntsyGet

   .. oe:api::

      bool MoleculeShowfAntsyGet()

   Returns whether or not the application is using the high quality molecule
   representations as opposed to standard models.

.. oe:function:: MoleculeShowfAntsySet

   .. oe:api::

      bool MoleculeShowfAntsySet(bool show)

   Sets whether or not the application is using the high quality molecule
   representations as opposed to standard models.

.. oe:function:: MoleculeStyleGet

   .. oe:api::

      std::string MoleculeStyleGet()

   Returns the default molecule style. The default is "stick". See the 
   MoleculeStyleSetScoped function for more information about molecule styles.

.. oe:function:: MoleculeStyleGetScoped

   .. oe:api::

      unsigned int 
        MoleculeStyleGetScoped(unsigned int scope = BestScope)

   Returns the style of the molecules in the specified scope. If there are 
   multiple styles present, the return type is "mixed". See the 
   MoleculeStyleSetScoped function for more information about molecule styles.

.. oe:function:: MoleculeStyleLargeGet

   .. oe:api::

      std::string MoleculeStyleLargeGet()

   Returns the default molecule style for large molecules, where large is 
   determined by whether or not the number of atoms in the molecule exceeds the 
   specified cutoff. For more information on this cutoff, see the 
   MoleculeSizeCutoff function. The default is "wireframe". See the 
   MoleculeStyleSetScoped function for more information about molecule styles.

.. oe:function:: MoleculeStyleLargeSet

   .. oe:api::

      void MoleculeStyleLargeSet(unsigned int style)
      void MoleculeStyleLargeSet(const std::string &style)

   Sets the default molecule style for large molecules, where large is 
   determined by whether or not the number of atoms in the molecule exceeds the 
   specified cutoff. For more information on this cutoff, see the 
   MoleculeSizeCutoff function. The default is "wireframe". See the 
   MoleculeStyleSetScoped function for more information about molecule styles.

.. oe:function:: MoleculeStyleNucleicGet

   .. oe:api::

      std::string MoleculeStyleNucleicGet()

   Returns the default molecule style for nucleic acids. The default is to mirror 
   the large molecule style. See the MoleculeStyleLargeSet function for more 
   information about large molecules and see the MoleculeStyleSetScoped function 
   for more information about molecule styles.

   Note: this function is a placeholder for a future implementation and therefore 
   does not currently have any effect.

.. oe:function:: MoleculeStyleNucleicSet

   .. oe:api::

      void MoleculeStyleNucleicSet(unsigned int style)
      void MoleculeStyleNucleicSet(const std::string &style)

   Sets the default molecule style for nucleic acids. The default is to mirror 
   the large molecule style. See the MoleculeStyleLargeSet function for more 
   information about large molecules and see the MoleculeStyleSetScoped function 
   for more information about molecule styles.

   Note: this function is a placeholder for a future implementation and therefore 
   does not currently have any effect.

.. oe:function:: MoleculeStyleProteinGet

   .. oe:api::

      std::string MoleculeStyleProteinGet()

   Returns the default molecule style for proteins. The default is to mirror the 
   large molecule style. See the MoleculeStyleLargeSet function for more 
   information about large molecules and see the MoleculeStyleSetScoped function 
   for more information about molecule styles.

   Note: this function is a placeholder for a future implementation and therefore 
   does not currently have any effect.

.. oe:function:: MoleculeStyleProteinSet

   .. oe:api::

      void MoleculeStyleProteinSet(unsigned int style)
      void MoleculeStyleProteinSet(const std::string &style)

   Sets the default molecule style for proteins. The default is to mirror the 
   large molecule style. See the MoleculeStyleLargeSet function for more 
   information about large molecules and see the MoleculeStyleSetScoped function 
   for more information about molecule styles.

   Note: this function is a placeholder for a future implementation and therefore 
   does not currently have any effect.

.. oe:function:: MoleculeStyleSet

   .. oe:api::

      void MoleculeStyleSet(unsigned int style)
      void MoleculeStyleSet(const std::string &atomStyle)

   Sets the default molecule style. This function accepts either a string or an
   enumerated representation as its parameter. The default is "stick". See the 
   MoleculeStyleSetScoped function for more information about molecule styles.

.. oe:function:: MoleculeStyleSetScoped

   .. oe:api::

      void MoleculeStyleSetScoped(unsigned int style, 
                                  unsigned int scope = BestScope)
      void MoleculeStyleSetScoped(const std::string &atomStyle, 
                                  unsigned int scope = BestScope)

   Sets the display style for the specified molecules. This function accepts 
   either a string or an enumerated representation as its parameter. Available 
   molecule styles include::

    * "ball and stick" molecules are drawn in ball and stick mode
    * "cpk"            molecules are drawn in CPK mode
    * "stars"          molecules are drawn in star mode
    * "stick"          molecules are drawn in stick mode
    * "wireframe"      molecules are drawn in wireframe mode
    * "none"           molecules are not drawn, but are still considered visible and thus selectable
    * "hidden"         molecules are not drawn and are not considered visible and thus are not selectable

.. oe:function:: MoleculeStyleToEnum

   .. oe:api::

      unsigned int MoleculeStyleToEnum(const std::string &style)

   This function returns the enumerated type associated the specified string 
   molecule style representation. See the MoleculeStyleSetScoped function for more 
   information about molecule styles.

.. oe:function:: MoleculeStyleToText

   .. oe:api::

      std::string MoleculeStyleToText(unsigned int style)

   This function returns the text string associated with the specified enumerated
   molecule style representation. See the MolStyleSetScoped function for more 
   information about molecule styles.

..  _vida_MonitorAngleCreate:

.. oe:function:: MonitorAngleCreate

   .. oe:api::

      unsigned int MonitorAngleCreate(const OEPropDB::OEKey &key1, 
                                      const OEPropDB::OEKey &key2, 
                                      const OEPropDB::OEKey &key3)

   Attempts to create an angle monitor between the atoms specified by the
   parameters *key1*, *key2*, and *key3*.
  
   Returns the ID of the created monitor or 0 if one could not be created.

.. oe:function:: MonitorAngleDelete

   .. oe:api::

      void MonitorAngleDelete(const OEPropDB::OEKey &key1, 
                              const OEPropDB::OEKey &key2, 
                              const OEPropDB::OEKey &key3)

   Deletes the monitor, if any, specified by atom keys: *key1*, *key2*, *key3*.

.. oe:function:: MonitorAngleExists

   .. oe:api::

      unsigned int MonitorAngleExists(const OEPropDB::OEKey &key1, 
                                      const OEPropDB::OEKey &key2, 
                                      const OEPropDB::OEKey &key3)

   Returns the ID of the angle monitor defined by the specified atom keys or
   zero if no such monitor exists.

.. oe:function:: MonitorColorGet

   .. oe:api::

      OESystem::OEColor MonitorColorGet(const OEPropDB::OEKey &monitor)

   Returns the color of the specified monitor.

.. oe:function:: MonitorColorSet

   .. oe:api::

      void MonitorColorSet(const OEPropDB::OEKey &monitor, 
                           const OESystem::OEColor &clr)

   Sets the color of the specified monitor.

.. oe:function:: MonitorDeleteScoped

   .. oe:api::

      void MonitorDeleteScoped(unsigned int scope = BestScope)

   Deletes all the monitors in the specified scope.

.. oe:function:: MonitorDistanceCreate

   .. oe:api::

      unsigned int MonitorDistanceCreate(const OEPropDB::OEKey &key1, 
                                         const OEPropDB::OEKey &key2)

   Attempts to create a distance monitor between the two atoms specified by the
   parameters *key1* and *key2*.
  
   Returns the ID of the created monitor or 0 if one could not be created.

.. oe:function:: MonitorDistanceDelete

   .. oe:api::

      void MonitorDistanceDelete(const OEPropDB::OEKey &key1, 
                                 const OEPropDB::OEKey &key2)

   Deletes the monitor specified by the two atom keys.

.. oe:function:: MonitorDistanceExists

   .. oe:api::

      unsigned int MonitorDistanceExists(const OEPropDB::OEKey &key1, 
                                         const OEPropDB::OEKey &key2)

   Returns the ID of the distance monitor determined by the two atom keys or
   zero if no such monitor exists.

.. oe:function:: MonitorSphereCreate

   .. oe:api::

      unsigned int MonitorSphereCreate(const OEPropDB::OEKey &key1, 
                                       const std::string &name, 
                                       const OESystem::OEColor &clr, float radius=0)
      unsigned int MonitorSphereCreate(const OEPropDB::OEKey &parent, 
                                       const std::string &name, float x, float y, 
                                       float z, float radius, 
                                       const OESystem::OEColor &color)

   Create a sphere monitor on an atom specified by *key1* or at the 
   coordinates specified by *x*, *y*, and *z*. The monitor is only visible when
   the specified atom key or parent key (in the case of coordinate 
   specification) is visible.
  
   Returns the ID of the newly created monitor or 0 if one could not be created.

.. oe:function:: MonitorTorsionCreate

   .. oe:api::

      unsigned int MonitorTorsionCreate(const OEPropDB::OEKey &key1, 
                                        const OEPropDB::OEKey &key2, 
                                        const OEPropDB::OEKey &key3, 
                                        const OEPropDB::OEKey &key4)

   Attempts to create a torsion monitor between the atoms specified by *key1*,
   *key2*, *key3*, and *key4*.
  
   Returns the ID of the created monitor or 0 if one could not be created.

.. oe:function:: MonitorTorsionDelete

   .. oe:api::

      void MonitorTorsionDelete(const OEPropDB::OEKey &key1, 
                                const OEPropDB::OEKey &key2, 
                                const OEPropDB::OEKey &key3, 
                                const OEPropDB::OEKey &key4)

   Deletes the torsion monitor, if any, specified by the atom keys: *key1*, 
   *key2*, *key3*, *key4*.

.. oe:function:: MonitorTorsionExists

   .. oe:api::

      unsigned int MonitorTorsionExists(const OEPropDB::OEKey &key1, 
                                        const OEPropDB::OEKey &key2, 
                                        const OEPropDB::OEKey &key3, 
                                        const OEPropDB::OEKey &key4)

   Returns the ID of the torsion monitor determined by the specified four atom
   keys or zero if no such monitor exists.

.. oe:function:: MonitorsVisible

   .. oe:api::

      bool MonitorsVisible()

   This function returns whether any monitors are currently visible.

.. oe:function:: MonitorsVisibleDelete

   .. oe:api::

      void MonitorsVisibleDelete()

   Deletes all monitors that are currently being displayed.

.. oe:function:: PaneActivated

   .. oe:api::

      void PaneActivated(unsigned int pane)

   In matrix (tiled) mode, sets the specified pane to be the active pane in the 
   display. Ordinarily, this function should not need to be called by the user.

.. oe:function:: ProteinColorByBFactor

   .. oe:api::

      void ProteinColorByBFactor(const OEPropDB::OEKey &key)

   Colors a protein referenced by key.  Atoms with the lowest temperature
   factors will be colored bright blue, while those with the highest will
   be colored bright red.

.. oe:function:: ProteinColorByBFactorScoped

   .. oe:api::

      void ProteinColorByBFactorScoped(unsigned int scope, int bins=10)
      void ProteinColorByBFactorScoped(unsigned int scope, 
                                       const std::vector<BFactorColor> &clrs)
      void ProteinColorByBFactorScoped(unsigned int scope, float min, float max, 
                                       const OESystem::OEColor &clr)

   Scoped versions of :oe:func:`ProteinColorByBFactor`.

.. oe:function:: ResidueColorPaletteUpdate

   .. oe:api::

      void ResidueColorPaletteUpdate()

   This function updates the default residue coloring palette based on whether or
   not the application is using a dark or light colored background scheme. This
   function is called internally and should not by called by the user.

.. oe:function:: ResidueDarkColorsGet

   .. oe:api::

      bool ResidueDarkColorsGet()

   Returns whether or not the application is using the residue color palette 
   designed for dark colored backgrounds. Otherwise, the application is using the 
   residue color palette designed for light colored backgrounds. Both of these 
   palettes can be edited in the preferences.

.. oe:function:: ResidueDarkColorsSet

   .. oe:api::

      void ResidueDarkColorsSet(bool dark)

   Sets whether or not the application is using the residue color palette 
   designed for dark colored backgrounds. Otherwise, the application is using the 
   residue color palette designed for light colored backgrounds. Both of these 
   palettes can be edited in the preferences.

.. oe:function:: ResidueDefaultColorGet

   .. oe:api::

      OESystem::OEColor ResidueDefaultColorGet()
      OESystem::OEColor ResidueDefaultColorGet(unsigned int res)

   Returns the current default residue color. The default residue color is applied
   to every residue that does not have its own specific default color assigned. 
   Calling this function with the *res* parameter returns the specific default 
   color associated with the passed residue index.

.. oe:function:: ResidueDefaultColorSet

   .. oe:api::

      void ResidueDefaultColorSet(const OESystem::OEColor &c)
      void ResidueDefaultColorSet(unsigned int res, const OESystem::OEColor &c)

   Sets the current default residue color. The default residue color is applied
   to every residue that does not have its own specific default color assigned. 
   Calling this function with the *res* parameter sets the specific default 
   color associated with the passed residue index.

.. oe:function:: RibbonClearColorScoped

   .. oe:api::

      void RibbonClearColorScoped(unsigned int scope = BestScope)

   This function restores the default ribbon coloring to those ribbons within the
   specified *scope*.

.. oe:function:: RibbonColorSetScoped

   .. oe:api::

      void RibbonColorSetScoped(const OESystem::OEColor &c, 
                                unsigned int scope = BestScope)

   This function sets the color of the ribbons in the specified *scope* to be the
   specified color *c*.

.. oe:function:: RibbonCrossResolutionGet

   .. oe:api::

      unsigned int RibbonCrossResolutionGet()

   Returns the cross resolution used in calculating protein ribbons.

.. oe:function:: RibbonCrossResolutionSet

   .. oe:api::

      unsigned int RibbonCrossResolutionSet(unsigned int res)

   Sets the cross resolution used in calculating protein ribbons.

.. oe:function:: RibbonGapGet

   .. oe:api::

      float RibbonGapGet()

   Returns the gap value used in calculating protein ribbons.

.. oe:function:: RibbonGapSet

   .. oe:api::

      float RibbonGapSet(float gap)

   Sets the gap value used in calculating protein ribbons.

.. oe:function:: RibbonHeightScaleGet

   .. oe:api::

      float RibbonHeightScaleGet()

   Returns the height scale used in calculating protein ribbons.

.. oe:function:: RibbonHeightScaleSet

   .. oe:api::

      float RibbonHeightScaleSet(float scale)

   Sets the height scale used in calculating protein ribbons.

.. oe:function:: RibbonRadiusGet

   .. oe:api::

      float RibbonRadiusGet()

   Returns the radius used in calculating protein ribbons.

.. oe:function:: RibbonRadiusSet

   .. oe:api::

      float RibbonRadiusSet(float radius)

   Sets the radius used in calculating protein ribbons.

.. oe:function:: RibbonResolutionGet

   .. oe:api::

      unsigned int RibbonResolutionGet()

   Returns the resolution used in calculating protein ribbons.

.. oe:function:: RibbonResolutionSet

   .. oe:api::

      unsigned int RibbonResolutionSet(unsigned int res)

   Sets the resolution used in calculating protein ribbons.

.. oe:function:: RibbonSplineTypeGet

   .. oe:api::

      std::string RibbonSplineTypeGet()

   Returns the spline type used in calculating protein ribbons. Available types
   include: "CubicHermite" and "Beta".

.. oe:function:: RibbonSplineTypeSet

   .. oe:api::

      std::string RibbonSplineTypeSet(const std::string &type)

   Sets the spline type used in calculating protein ribbons. Available types
   include: "CubicHermite" and "Beta".

.. oe:function:: RibbonStyleGet

   .. oe:api::

      std::string RibbonStyleGet()

   Returns the style used in displaying protein ribbons. Available types 
   include: "Round", "Lines", and "Cartoon". The default is "Cartoon".

.. oe:function:: RibbonStyleSet

   .. oe:api::

      std::string RibbonStyleSet(const std::string &style)
      std::string RibbonStyleSet(const OEPropDB::OEKey &k, const std::string &style)

   Sets the style used in displaying protein ribbons. Available types 
   include: "Round", "Lines", and "Cartoon". The default is "Cartoon".

.. oe:function:: RibbonStyleSetScoped

   .. oe:api::

      std::string RibbonStyleSetScoped(const std::string &style, 
                                       unsigned int scope = BestScope)

   Sets the style used in displaying ribbons for the proteins in the specified
   scope. Available types include: "Round", "Lines", and "Cartoon". The default
   is "Cartoon".

.. oe:function:: RibbonWidthScaleGet

   .. oe:api::

      float RibbonWidthScaleGet()

   Returns the width scale used in calculating protein ribbons.

.. oe:function:: RibbonWidthScaleSet

   .. oe:api::

      float RibbonWidthScaleSet(float scale)

   Sets the width scale used in calculating protein ribbons.

.. oe:function:: SceneDrawActiveBorderGet

   .. oe:api::

      bool SceneDrawActiveBorderGet()

   Returns whether or not a border is drawn (in matrix mode) around the cell
   containing the focused object.

.. oe:function:: SceneDrawActiveBorderSet

   .. oe:api::

      void SceneDrawActiveBorderSet(bool draw)

   Sets whether or not a border is drawn (in matrix mode) around the cell
   containing the focused object.

.. oe:function:: SceneMatrixModeGet

   .. oe:api::

      std::string SceneMatrixModeGet()

   Returns the display style for the individual cells when the application is in
   matrix mode. Available styles are: "OnePerView", "LockedOnAll", and 
   "LockedPerView".

.. oe:function:: SceneMatrixModeSet

   .. oe:api::

      std::string SceneMatrixModeSet(std::string mode)

   Sets the display style for the individual cells when the application is in
   matrix mode. Available styles are: "OnePerView", "LockedOnAll", and 
   "LockedPerView".

.. oe:function:: SelectionColorBlendFactorGet

   .. oe:api::

      float SelectionColorBlendFactorGet()

   Returns the alpha buffer coloring blending factor for selection colors. The
   default value is 1.0 which corresponds to zero blending with the selection
   color being the one displayed. A value of 0.0 also corresponds to zero blending
   but with the underlying color being the one displayed. A value of 0.5 
   corresponds to even blending of the underlying color and the selected color.

.. oe:function:: SelectionColorBlendFactorSet

   .. oe:api::

      float SelectionColorBlendFactorSet(float alpha)

   Sets the alpha buffer coloring blending factor for selection colors. The
   default value is 1.0 which corresponds to zero blending with the selection
   color being the one displayed. A value of 0.0 also corresponds to zero blending
   but with the underlying color being the one displayed. A value of 0.5 
   corresponds to even blending of the underlying color and the selected color.

.. oe:function:: ShowESGridScoped

   .. oe:api::

      void ShowESGridScoped(bool show=true, 
                            unsigned int scope = BestScope)

   If *show* is true, attach and show electrostatic grids to all
   molecules in *scope*.

   If *show* if false, hide all attached electrostatic grids to molecules
   in *scope*.

.. oe:function:: ShowSurface

   .. oe:api::

      void ShowSurface(const OEPropDB::OEKey &, const std::string &, bool show)

   Sets whether or not a property surface of the specified *type* is displayed for
   the molecule associated with the specified key. Valid types are "molecular" and
   "accessible".

.. oe:function:: ShowSurfaceScoped

   .. oe:api::

      void ShowSurfaceScoped(const std::string &type, bool show, 
                             unsigned int scope = BestScope)

   Scoped version of :oe:func:`ShowSurface`.

.. oe:function:: SurfaceAlterTransparency

   .. oe:api::

      void SurfaceAlterTransparency(unsigned int id, unsigned int alpha)

   Sets the transparency of the surface associated with the specified *id*. The
   transparency is specified by the *alpha* parameter which determines the alpha
   component of the surface color. The alpha values ranges from 0 (completely 
   transparent) to 255 (completely opaque).

.. oe:function:: SurfaceColorBy

   .. oe:api::

      std::string SurfaceColorBy(const std::string &mode="")
      void SurfaceColorBy(const OEPropDB::OEKey &key, const std::string &mode, 
                          const std::string &params="")

   This function colors the surface referenced by the specified *key* using the 
   specified *style*. Valid styles include:

   * atom - colors the surface based on the color of the nearest atom to the
            vertex being colored

   * concavity - colors the surface by concavity, red is high concavity.

   * curvature - colors the surface by curvature, green is positive curvature.

   * distance - colors the surface by its distance to the currently selected atoms.
                Each color band represents two angstroms.

   * electrostatics - colors the surface using a red-to-blue scheme based on the 
                      electrostatic potential observed at the surface.

   * hydrogen bonds - colors the surface by the underlying atom hydrogen-bond
                      donor/acceptor properties. Donors are red and acceptors are 
                      blue.

   * hydrophobicity - colors the surface using a hydrophobic color scale. There 
                      are four different hydrophobic scales available: charifson,
                      eisenberg, kytedolittle, and whiteoctanol. The desired scale
                      can be set in the application preferences.

   * potential - colors the surface based using a red-to-blue scheme (low to high)
                over the values in the surface's potential array. This is not the
                same as coloring by electrostatics.

.. oe:function:: SurfaceColorByScoped

   .. oe:api::

      void SurfaceColorByScoped(const std::string &colorby, 
                                const std::string &params="", 
                                unsigned int scope = BestScope)

   Scoped version of :oe:func:`SurfaceColorBy`.

.. oe:function:: SurfaceColorGet

   .. oe:api::

      OESystem::OEColor SurfaceColorGet(unsigned int id)

   Returns the color of the specified surface.

.. oe:function:: SurfaceColorGetScoped

   .. oe:api::

      OESystem::OEColor 
        SurfaceColorGetScoped(unsigned int scope = BestScope)

   Returns the color of the first surface found in the specified scope.

.. oe:function:: SurfaceColorSet

   .. oe:api::

      OESystem::OEColor SurfaceColorSet(unsigned int id, 
                                        const OESystem::OEColor &color)

   Set the color of the surface *id* to *color*.

.. oe:function:: SurfaceColorSetScoped

   .. oe:api::

      void SurfaceColorSetScoped(const OESystem::OEColor &color, 
                                 unsigned int scope = BestScope)

   Set the color of the surfaces in *scope* to *color*.

.. oe:function:: SurfaceGrowTriangle

   .. oe:api::

      void SurfaceGrowTriangle(unsigned int oerid, const OEPropDB::OEKey &trikey, 
                               bool addtriangle=false)

   Grow the surface selection when a triangle is double clicked. Ordinarily this 
   function does not need to be called.

.. oe:function:: SurfaceLineWidthGet

   .. oe:api::

      float SurfaceLineWidthGet(unsigned int id=0)

   Returns the line width used when drawing the surface specified by *id* in
   mesh mode.

.. oe:function:: SurfaceLineWidthSet

   .. oe:api::

      float SurfaceLineWidthSet(unsigned int id, float width)

   Sets the line width used when drawing the surface specified by *id* in 
   mesh mode.

.. oe:function:: SurfaceStyleGet

   .. oe:api::

      std::string SurfaceStyleGet(unsigned int id)

   Returns the default style of surfaces. The style is one of:

    * mesh - the surfaces are drawn as meshes.

    * points - the surfaces are drawn as points.

    * solid - the surfaces are drawn as solid objects.

.. oe:function:: SurfaceStyleGetScoped

   .. oe:api::

      std::string SurfaceStyleGetScoped(unsigned int scope = BestScope)

   Return the style for the surfaces in scope.  The value returned is from
   the first surface found in scope and is not indicative of all surfaces.

   See :oe:func:`SurfaceStyleGet` for a list of 
   surface styles.

.. oe:function:: SurfaceStyleSet

   .. oe:api::

      std::string SurfaceStyleSet(unsigned int id, const std::string &style)

   Set the surface *id* to on of the following styles:

    * mesh - the surface is drawn as a mesh.

    * points - the surface is drawn as points.

    * solid - the surface is drawn as a solid object.

.. oe:function:: SurfaceStyleSetScoped

   .. oe:api::

      void SurfaceStyleSetScoped(const std::string &style, 
                                 unsigned int scope = BestScope)

   Scoped version of :oe:func:`SurfaceStyleSet`.

.. oe:function:: SurfaceTransparencySet

   .. oe:api::

      void SurfaceTransparencySet(unsigned int id, unsigned int alpha)

   Set the transparency to all surfaces in *scope* to transparency.

.. oe:function:: SurfaceTransparencySetScoped

   .. oe:api::

      void SurfaceTransparencySetScoped(unsigned int transparency, 
                                        unsigned int scope = BestScope)

   Set the transparency to all surfaces in *scope* to transparency.

.. oe:function:: SurfaceVertexFloodScoped

   .. oe:api::

      int SurfaceVertexFloodScoped(unsigned int scope = BestScope)

   Get the surface vertex flood of all surfaces in scope.  This is essentially 
   the flood of the focused surface or the surface of the focused or first 
   visible molecule.

.. oe:function:: SymmetryColorModeGet

   .. oe:api::

      unsigned int SymmetryColorModeGet()

.. oe:function:: SymmetryColorModeSet

   .. oe:api::

      unsigned int SymmetryColorModeSet(unsigned int mode)

.. oe:function:: TitleDefaultColorGet

   .. oe:api::

      OESystem::OEColor TitleDefaultColorGet()

   Returns the default color for titles.

.. oe:function:: TitleDefaultColorSet

   .. oe:api::

      void TitleDefaultColorSet(const OESystem::OEColor &c)

   Sets the default color for titles.

.. oe:function:: TitlesDrawAboveGet

   .. oe:api::

      bool TitlesDrawAboveGet()

   Returns whether or not titles are drawn at the top of the scene or the bottom 
   of the scene.

.. oe:function:: TitlesDrawAboveSet

   .. oe:api::

      void TitlesDrawAboveSet(bool top)

   Sets whether or not titles are drawn at the top of the scene or the bottom of
   the scene.

.. oe:function:: TransparencySet

   .. oe:api::

      void TransparencySet(const OEPropDB::OEKey &, unsigned int alpha)

   This function sets the transparency of the object associated with the specified
   key. The transparency is determined by the specified parameter *alpha* which 
   corresponds to the desired alpha value of the object's color. Alpha can range 
   from 0 (completely transparent) to 255 (completely opaque).

.. oe:function:: TransparencySetScoped

   .. oe:api::

      void TransparencySetScoped(unsigned int alpha, 
                                 unsigned int scope = BestScope)

   This function sets the transparency of all the objects in the specified
   scope. The transparency is determined by the specified parameter *alpha* which 
   corresponds to the desired alpha value of the object's color. Alpha can range 
   from 0 (completely transparent) to 255 (completely opaque).

.. oe:function:: ViewerAmbientLightGet

   .. oe:api::

      OESystem::OEColor ViewerAmbientLightGet()

   Returns the OpenGL ambient light property.

.. oe:function:: ViewerAmbientLightSet

   .. oe:api::

      OESystem::OEColor ViewerAmbientLightSet(const OESystem::OEColor &color)

   Sets the OpenGL ambient light property.

.. oe:function:: ViewerAmbientMaterialGet

   .. oe:api::

      OESystem::OEColor ViewerAmbientMaterialGet()

   Returns the OpenGL ambient material property.

.. oe:function:: ViewerAmbientMaterialSet

   .. oe:api::

      OESystem::OEColor ViewerAmbientMaterialSet(const OESystem::OEColor &color)

   Sets the OpenGL ambient material property.

.. oe:function:: ViewerAnimate

   .. oe:api::

      void ViewerAnimate(const std::vector<float> &centers, 
                         const std::vector<float> &look, 
                         const std::vector<float> &up, 
                         unsigned int              msec, 
                         unsigned int              fps)

   Reserved for future use.

.. oe:function:: ViewerAnimateTo

   .. oe:api::

      void ViewerAnimateTo( const std::string &bookmark, 
                            unsigned int       msec, 
                            unsigned int       fps)
      void ViewerAnimateTo( const OEPropDB::OEKey &centerKey, 
                            const OEPropDB::OEKey &refKey, 
                            unsigned int           msec, 
                            unsigned int           fps, 
                            float                  zoom = 0.0 )
      void ViewerAnimateTo( const std::vector<float> &center, 
                            const std::vector<float> &look, 
                            const std::vector<float> &up, 
                            unsigned int              msec, 
                            unsigned int              fps, 
                            float                     zoom = 0.0 )

   Animates the scene from the current position to the specified position. All
   implementations of this function take an *msec* and *fps* parameters. The
   *msec* parameter specifies how long it should take the animation to be 
   performed. Please note that this time is only a suggestion, as many factors
   including CPU speed, GPU speed, and available memory will influence the 
   actual performance of the animation. The *fps* parameters specifies how many
   frames per second should be used in the animation.
  
   The first implementation takes a bookmark name as its only other parameter. 
   The second implementation takes two OEKey parameters corresponding to the 
   desired final center and viewing point positions for the scene. The third
   implementation takes three arrays corresponding to the center coordinates, 
   a vector defining the viewing angle, and a vector defining the up direction 
   for the scene.  

.. oe:function:: ViewerAntialiasGet

   .. oe:api::

      bool ViewerAntialiasGet()

   Returns whether or not antialiasing is turned on for line drawing.

.. oe:function:: ViewerAntialiasSet

   .. oe:api::

      bool ViewerAntialiasSet(bool state)

   Sets whether or not antialiasing is turned on for line drawing.

.. oe:function:: ViewerAutoCenterGet

   .. oe:api::

      bool ViewerAutoCenterGet()

   Returns whether or not the scene will automatically be recentered when a 
   change in the scene occurs (e.g. a new object is made active, objects are
   hidden or shown).

.. oe:function:: ViewerAutoCenterPanesGet

   .. oe:api::

      bool ViewerAutoCenterPanesGet()

   Returns whether or not the scene in each pane in multi-pane display mode is
   automatically centered or whether all panes observe the same center.

.. oe:function:: ViewerAutoCenterPanesSet

   .. oe:api::

      void ViewerAutoCenterPanesSet(bool center)

   Sets whether or not the scene in each pane in multi-pane display mode is
   automatically centered or whether all panes observe the same center.

.. oe:function:: ViewerAutoCenterSet

   .. oe:api::

      bool ViewerAutoCenterSet(bool ac)

   Sets whether or not the scene will automatically be recentered when a change 
   in the scene occurs (e.g. a new object is made active, objects are hidden or
   shown).

.. oe:function:: ViewerAutoFitGet

   .. oe:api::

      bool ViewerAutoFitGet()

   Returns whether or not the contents of the scene will automatically be fit to
   the screen when a scene change occurs.

.. oe:function:: ViewerAutoFitSet

   .. oe:api::

      bool ViewerAutoFitSet(bool af)

   Sets whether or not the contents of the scene will automatically be fit to the
   screen when a scene change occurs.

.. oe:function:: ViewerBackgroundColorGet

   .. oe:api::

      OESystem::OEColor ViewerBackgroundColorGet()

   Returns the background color of the 3D display.

.. oe:function:: ViewerBackgroundColorSet

   .. oe:api::

      OESystem::OEColor ViewerBackgroundColorSet(const OESystem::OEColor &color)

   Sets the background color of the 3D display.

.. oe:function:: ViewerBookmarkLoad

   .. oe:api::

      bool ViewerBookmarkLoad(std::string bm)

   Loads the specified bookmark.

.. oe:function:: ViewerBookmarksGetAnimated

   .. oe:api::

      bool ViewerBookmarksGetAnimated()

   Returns whether or not the transition between bookmarks is animated.

.. oe:function:: ViewerBookmarksGetAnimationTime

   .. oe:api::

      unsigned int ViewerBookmarksGetAnimationTime()

   Returns the default desired time for how long the transition between 
   bookmarks should take if animated.

.. oe:function:: ViewerBookmarksSetAnimated

   .. oe:api::

      void ViewerBookmarksSetAnimated(bool animated)

   Sets whether or not the transition between bookmarks is animated.

.. oe:function:: ViewerBookmarksSetAnimationTime

   .. oe:api::

      void ViewerBookmarksSetAnimationTime(unsigned int msecs)

   Sets the default desired time for how long the transition between
   bookmarks should take if animated.

.. oe:function:: ViewerCenterAndRadiusGet

   .. oe:api::

      std::vector<float> ViewerCenterAndRadiusGet()

   Returns the current center and radius of the scene in the 3D display in a 
   four-membered list. The first three values in the list are the x,y,z coordinates of
   the center. The fourth value is the radius.

.. oe:function:: ViewerCenterAndRadiusSet

   .. oe:api::

      std::vector<float> ViewerCenterAndRadiusSet(float x, float y, float z, 
                                                  float radius, bool redraw=true)

   Sets the current center and radius of the scene in the 3D display. The *redraw*
   parameter determines whether or not the scene should be redrawn immediately.

.. oe:function:: ViewerCenterGet

   .. oe:api::

      std::vector<float> ViewerCenterGet()

   Returns the current center of the scene as a list of three values corresponding
   to the x,y,z coordinates. If for some reason the 3D display is invalid, the
   list returned will be empty.

.. oe:function:: ViewerCenterSet

   .. oe:api::

      std::vector<float> ViewerCenterSet(unsigned int, bool redraw=true)
      std::vector<float> ViewerCenterSet(float x, float y, float z, bool redraw=true)

   Sets the current center of the scene. The function that takes three floating
   point parameters explicitly sets the center of the scene to the coordinates 
   specified by the *x*, *y*, and *z* parameters. The *redraw* parameter specifies
   whether or not the scene should be immediately redrawn. 

   The function that takes a single unsigned integer parameter (*id*) attempts to 
   center the scene based on the geometry of the object corresponding to the *id* 
   parameter. If for some reason, a center could not be calculated, this function
   will return an empty list, otherwise it will return the new center.

.. oe:function:: ViewerCenterSetScoped

   .. oe:api::

      std::vector<float> 
        ViewerCenterSetScoped(unsigned int scope = BestScope, 
                              bool redraw=true)

   Sets the current center of the scene based on the geometry of the objects 
   found within the specified scope. The *redraw* parameter specifies whether or
   not the scene should be immediately redrawn. If for some reason, a center could
   not be calculated, this function will return an empty list, otherwise it will 
   return the new center.
   

.. oe:function:: ViewerDepthCueFollowsSlab

   .. oe:api::

      bool ViewerDepthCueFollowsSlab()
      bool ViewerDepthCueFollowsSlab(bool enable)

   Sets whether or not the depthcue parameters should be adjusted as the 
   slabbing parameters change to maintain the best possible lighting for the scene.

.. oe:function:: ViewerDepthcueEndGet

   .. oe:api::

      float ViewerDepthcueEndGet()

   Returns the spatial end point used in depthcue calculations. Ordinarily, this 
   function should not need to be called by the user.

.. oe:function:: ViewerDepthcueEndSet

   .. oe:api::

      float ViewerDepthcueEndSet(float end, bool redraw=true)

   Sets the spatial end point used in depthcue calculations. Ordinarily, this 
   function should not need to be called by the user.

.. oe:function:: ViewerDepthcueGet

   .. oe:api::

      bool ViewerDepthcueGet()

   Returns whether or not depthcueing is currently enabled in the 3D display.

.. oe:function:: ViewerDepthcueSet

   .. oe:api::

      bool ViewerDepthcueSet(bool state)

   Sets whether or not depthcueing is currently enabled in the 3D display.

.. oe:function:: ViewerDepthcueStartGet

   .. oe:api::

      float ViewerDepthcueStartGet()

   Returns the spatial start point used in depthcue calculations. Ordinarily, this
   function should not need to be called by the user.

.. oe:function:: ViewerDepthcueStartSet

   .. oe:api::

      float ViewerDepthcueStartSet(float start, bool redraw=true)

   Sets the spatial start point used in depthcue calculations. Ordinarily, this
   function should not need to be called by the user.

.. oe:function:: ViewerDiffuseLightGet

   .. oe:api::

      OESystem::OEColor ViewerDiffuseLightGet()

   Returns the OpenGL diffuse light property.

.. oe:function:: ViewerDiffuseLightSet

   .. oe:api::

      OESystem::OEColor ViewerDiffuseLightSet(const OESystem::OEColor &color)

   Sets the OpenGL diffuse light property.

.. oe:function:: ViewerDiffuseMaterialGet

   .. oe:api::

      OESystem::OEColor ViewerDiffuseMaterialGet()

   Returns the OpenGL diffuse material property.

.. oe:function:: ViewerDiffuseMaterialSet

   .. oe:api::

      OESystem::OEColor ViewerDiffuseMaterialSet(const OESystem::OEColor &color)

   Set the OpenGL diffuse material property.

.. oe:function:: ViewerDrawDepictionsGet

   .. oe:api::

      bool ViewerDrawDepictionsGet()

   Returns whether or not a 2D depiction is drawn in the 3D display for the
   active molecule.

.. oe:function:: ViewerDrawDepictionsSet

   .. oe:api::

      bool ViewerDrawDepictionsSet(bool show)

   Sets whether or not a 2D depiction is drawn in the 3D display for the active
   molecule.

.. oe:function:: ViewerFit

   .. oe:api::

      void ViewerFit(float buffer=0.0f)
      void ViewerFit(const std::vector<OEPropDB::OEKey> &keys, float buffer=0.0f)

   This function ensures that the entire contents of the scene fit within the 3D
   display window. The *buffer* parameter allows specification of an additional
   buffer applied to the radius of the scene.

   The function that takes a list of keys as a parameter will perform the same 
   function as above, but will only ensure that those objects corresponding to the
   specified keys will be guaranteed to fit within the 3D display window.

.. oe:function:: ViewerFontSizeGet

   .. oe:api::

      unsigned int ViewerFontSizeGet()

   Return the size of the font used for text drawn in the 3D display.

.. oe:function:: ViewerFontSizeSet

   .. oe:api::

      void ViewerFontSizeSet(unsigned int sz)

   Sets the size of the font used for text drawn in the 3D display.

.. oe:function:: ViewerForwardGet

   .. oe:api::

      std::vector<float> ViewerForwardGet()

   Returns the forward facing vector for the OpenGL camera.

.. oe:function:: ViewerLODGet

   .. oe:api::

      int ViewerLODGet()

   Returns the level of display (rendering quality) being used in 3D display 
   window.

.. oe:function:: ViewerLODSet

   .. oe:api::

      int ViewerLODSet(unsigned int lod, bool redraw=true)

   Sets the level of display (rendering quality) being used in the 3D display.

.. oe:function:: ViewerLightPositionGet

   .. oe:api::

      std::vector<float> ViewerLightPositionGet()

   Returns the position of the OpenGL light source.

.. oe:function:: ViewerLightPositionSet

   .. oe:api::

      std::vector<float> ViewerLightPositionSet(const std::vector<float> &pos)

   Sets the position of the OpenGL light source.

.. oe:function:: ViewerLookAt

   .. oe:api::

      void ViewerLookAt(const OEPropDB::OEKey &centerKey, 
                        const OEPropDB::OEKey &refKey, bool redraw=true)
      void ViewerLookAt(const std::vector<float> &center, 
                        const std::vector<float> &look, 
                        const std::vector<float> &up, bool redraw=true)

   Sets up the display such that the object corresponding to *centerKey* is at the
   center of the display with the camera looking down the axis between *centerKey*
   and the object corresponding to *refKey*.

.. oe:function:: ViewerMirrorSlabsGet

   .. oe:api::

      bool ViewerMirrorSlabsGet()

   Returns whether or not the position of the front and back clipping planes mirror 
   each other.

.. oe:function:: ViewerMirrorSlabsSet

   .. oe:api::

      bool ViewerMirrorSlabsSet(bool mirror)

   Sets whether or not the position of the front and back clipping planes mirror 
   each other.
   

.. oe:function:: ViewerNiceFontsGet

   .. oe:api::

      bool ViewerNiceFontsGet()

   Returns whether or not text is rendered in the 3D display using high-quality
   fonts versus simple fonts. Some graphics cards cannot properly handle the 
   high-quality fonts and it is recommended in those situations not to use "nice"
   fonts.

.. oe:function:: ViewerNiceFontsSet

   .. oe:api::

      bool ViewerNiceFontsSet(bool nice)

   Sets whether or not text is rendered in the 3D display using high-quality
   fonts versus simple fonts. Some graphics cards cannot properly handle the 
   high-quality fonts and it is recommended in those situations not to use "nice"
   fonts.

.. oe:function:: ViewerOrientationGet

   .. oe:api::

      std::vector<float> ViewerOrientationGet()

   Returns the OpenGL camera orientation matrix.

.. oe:function:: ViewerOrientationSet

   .. oe:api::

      std::vector<float> ViewerOrientationSet(std::vector<float> orientationMatrix)

   Sets the OpenGL camera orientation matrix.

.. oe:function:: ViewerProjectorModeGet

   .. oe:api::

      bool ViewerProjectorModeGet()

   Returns whether or not the display is being drawn in "Projector Mode". 
   "Projector Mode" is a display mode which is designed to improve visibility
   when the application is projected using an LCD projector by using a lighter
   background and a different atom coloring scheme.

.. oe:function:: ViewerProjectorModeSet

   .. oe:api::

      void ViewerProjectorModeSet(bool state)

   Sets whether or not the display is being drawn in "Projector Mode". 
   "Projector Mode" is a display mode which is designed to improve visibility
   when the application is projected using an LCD projector by using a lighter
   background and a different atom coloring scheme.

.. oe:function:: ViewerRadiusGet

   .. oe:api::

      float ViewerRadiusGet()

   Returns the current radius of the scene in the 3D display window.

.. oe:function:: ViewerRadiusSet

   .. oe:api::

      float ViewerRadiusSet(float radius, bool redraw=true)

   Sets the current radius of the scene in the 3D display window. The *redraw*
   parameter specifies whether or not to immediately redraw the scene.

.. oe:function:: ViewerRecenter

   .. oe:api::

      void ViewerRecenter()

   This function recenters the scene based on the geometry of the contents of the
   scene.

.. oe:function:: ViewerReprobeStereo

   .. oe:api::

      bool ViewerReprobeStereo()

   This function rechecks to see whether hardware stereo is supported on the 
   current machine. Ordinarily, this function should not need to be called by
   the user.

.. oe:function:: ViewerRotate

   .. oe:api::

      void ViewerRotate(const std::string &axis, float angle, bool redraw=true)

   This function rotates the display around the specified axis (valid parameters:
   'x','y','z' for screen or trackball axis, 'X', 'Y', 'Z' for world axis) by *angle* degrees.  
   The center of rotation is the world center.  
   The *redraw* parameter specifies whether or not to immediately redraw the scene.

.. oe:function:: ViewerScaleGet

   .. oe:api::

      float ViewerScaleGet()

   Returns the scale of the scene in the 3D display window.

.. oe:function:: ViewerScaleSet

   .. oe:api::

      float ViewerScaleSet(float radius, bool redraw=true)

   Sets the scale of the scene in the 3D display window.

.. oe:function:: ViewerShininessMaterialGet

   .. oe:api::

      float ViewerShininessMaterialGet()

   Returns the OpenGL material shininess property.

.. oe:function:: ViewerShininessMaterialSet

   .. oe:api::

      float ViewerShininessMaterialSet(float shine)

   Sets the OpenGL material shininess property.

.. oe:function:: ViewerShowActiveBorderGet

   .. oe:api::

      bool ViewerShowActiveBorderGet()

   Returns whether or not a blue border is drawn around the active pane in 
   multi-pane display mode.

.. oe:function:: ViewerShowActiveBorderSet

   .. oe:api::

      void ViewerShowActiveBorderSet(bool show)

   Sets whether or not a blue border is drawn around the active pane in 
   multi-pane display mode.

.. oe:function:: ViewerShowGridGet

   .. oe:api::

      bool ViewerShowGridGet()

   Returns whether or not borders are drawn around individual panes in multi-pane
   display mode.

.. oe:function:: ViewerShowGridSet

   .. oe:api::

      void ViewerShowGridSet(bool show)

   Sets whether or not borders are drawn around individual panes in multi-pane 
   display mode.

.. oe:function:: ViewerShowTrackballGuideSet

   .. oe:api::

      void ViewerShowTrackballGuideSet(bool show)

   Sets whether or not a trackball guide will be displayed on the 3D display 
   window to help guide what is considered inside and outside with respect to 
   mouse actions. Please see ViewerMouseOutsideAwareGet/Set functions for more
   details.

.. oe:function:: ViewerSlabEnableGet

   .. oe:api::

      bool ViewerSlabEnableGet()

   Returns whether or not slabbing (clipping) of the 3D display is enabled.

.. oe:function:: ViewerSlabEnableSet

   .. oe:api::

      bool ViewerSlabEnableSet(bool enable)

   Sets whether or not slabbing (clipping) of the 3D display is enabled. The
   *redraw* parameter specifies whether or not the scene should be immediately
   redrawn.

.. oe:function:: ViewerSlabFarGet

   .. oe:api::

      float ViewerSlabFarGet()

   Returns the spatial position of the far clipping plane. Ordinarily, this 
   function should not need to be called by the user.

.. oe:function:: ViewerSlabFarSet

   .. oe:api::

      float ViewerSlabFarSet(float radius, bool redraw=true)

   Sets the spatial position of the far clipping plane. The *redraw* parameter 
   specifies whether or not the scene should be immediately redrawn. Ordinarily,
   this function should not need to be called by the user.

.. oe:function:: ViewerSlabNearGet

   .. oe:api::

      float ViewerSlabNearGet()

   Returns the spatial position of the near clipping plane. Ordinarily, this 
   function should not need to be called by the user.

.. oe:function:: ViewerSlabNearSet

   .. oe:api::

      float ViewerSlabNearSet(float radius, bool redraw=true)

   Sets the spatial position of the near clipping plane. The *redraw* parameter 
   specifies whether or not the scene should be immediately redrawn. Ordinarily,
   this function should not need to be called by the user.

.. oe:function:: ViewerSlabWidthGet

   .. oe:api::

      float ViewerSlabWidthGet()

   Returns the distance between the near and far clipping planes. Ordinarily, this 
   function should not need to be called by the user.

.. oe:function:: ViewerSlabWidthSet

   .. oe:api::

      float ViewerSlabWidthSet(float width, bool redraw=true)

   Sets the distance between the near and far clipping planes. The *redraw* 
   parameter specifies whether or not the scene should be immediately redrawn. 
   Ordinarily, this function should not need to be called by the user.

.. oe:function:: ViewerSpecularMaterialGet

   .. oe:api::

      OESystem::OEColor ViewerSpecularMaterialGet()

   Returns the OpenGL specular material property.

.. oe:function:: ViewerSpecularMaterialSet

   .. oe:api::

      OESystem::OEColor ViewerSpecularMaterialSet(const OESystem::OEColor &color)

   Sets the OpenGL specular material property.

.. oe:function:: ViewerStereoAngleGet

   .. oe:api::

      float ViewerStereoAngleGet()

   Returns the angle used when calculating stereographic display offsets.

.. oe:function:: ViewerStereoAngleSet

   .. oe:api::

      float ViewerStereoAngleSet(float angle)

   Sets the angle used when calculating stereographic display offsets.

.. oe:function:: ViewerStereoCrossEyedGet

   .. oe:api::

      bool ViewerStereoCrossEyedGet()

   Returns whether or not the stereographic display is in cross-eyed mode.

.. oe:function:: ViewerStereoCrossEyedSet

   .. oe:api::

      bool ViewerStereoCrossEyedSet(bool cross)

   Sets whether or not the stereographic display is in cross-eyed mode.

.. oe:function:: ViewerStereoEnableGet

   .. oe:api::

      bool ViewerStereoEnableGet()

   Returns whether or not stereographic display is enabled.

.. oe:function:: ViewerStereoEnableSet

   .. oe:api::

      bool ViewerStereoEnableSet(bool enabled)

   Sets whether or not stereographic display is enabled.

.. oe:function:: ViewerStereoSeparationGet

   .. oe:api::

      float ViewerStereoSeparationGet()

   Returns the eye separation used in stereographic display mode.

.. oe:function:: ViewerStereoSeparationSet

   .. oe:api::

      float ViewerStereoSeparationSet(float separation)

   Sets the eye separation used in stereographic display mode.

.. oe:function:: ViewerStereoStyleGet

   .. oe:api::

      unsigned char ViewerStereoStyleGet()

   Sets the stereographic display mode (hardware, splitscreen, or none).

.. oe:function:: ViewerStereoStyleSet

   .. oe:api::

      unsigned char ViewerStereoStyleSet(unsigned char style)

   Sets the stereographic display mode (hardware, stencil, splitscreen, or none).

.. oe:function:: ViewerStyleControlVisibleGet

   .. oe:api::

      bool ViewerStyleControlVisibleGet(const std::string &style)

   Returns whether or not the specified style control widget is currently visible
   above the 3D display. Available style widgets include: "color", "selection", 
   "style", "contours", and "graphics".

.. oe:function:: ViewerStyleControlVisibleSet

   .. oe:api::

      void ViewerStyleControlVisibleSet(const std::string &style, bool vis)

   Sets whether or not the specified style control widget is currently visible
   above the 3D display. Available style widgets include: "color", "selection", 
   "style", "contours", and "graphics".

.. oe:function:: ViewerSupportsHWStereo

   .. oe:api::

      bool ViewerSupportsHWStereo()

   Returns whether or not the machine the application is being run on supports
   the use hardware stereo.

.. oe:function:: ViewerTextFontGet

   .. oe:api::

      std::string ViewerTextFontGet()

   Returns the font currently being used when rendering text in the 3D display.
   This font only applies when using "nice" fonts.

.. oe:function:: ViewerTextFontSet

   .. oe:api::

      void ViewerTextFontSet(const std::string &)

   Sets the font currently being used when rendering text in the 3D display.
   This font only applies when using "nice" fonts.

.. oe:function:: ViewerTextScaleGet

   .. oe:api::

      float ViewerTextScaleGet()

   Returns the current global scale for text drawn in the 3D display window.

.. oe:function:: ViewerTextScaleSet

   .. oe:api::

      float ViewerTextScaleSet(float scale, bool redraw=true)

   Sets the current global scale for text drawn in the 3D display window.

.. oe:function:: ViewerToggleRenderFeatures

   .. oe:api::

      void ViewerToggleRenderFeatures(unsigned int features, bool on)

   Toggles the use of certain advanced visualization features.

.. oe:function:: ViewerTranslateX

   .. oe:api::

      void ViewerTranslateX(float val)

   Translates the display along the X axis by the specified amount (in Angstroms).

.. oe:function:: ViewerTranslateY

   .. oe:api::

      void ViewerTranslateY(float val)

   Translates the display along the Y axis by the specified amount (in Angstroms).

.. oe:function:: ViewerTranslateZ

   .. oe:api::

      void ViewerTranslateZ(float val)

   Translates the display along the Z axis by the specified amount (in Angstroms).

.. oe:function:: ViewerUpGet

   .. oe:api::

      std::vector<float> ViewerUpGet()

   Returns the OpenGL camera up vector.

.. oe:function:: ViewerUseDisplayListGet

   .. oe:api::

      bool ViewerUseDisplayListGet()

   Returns whether or not the 3D renderer uses a display list to encapsulate
   the master scene. The default is false. Ordinarily, this function does not
   need to be called by the user.

.. oe:function:: ViewerUseDisplayListSet

   .. oe:api::

      bool ViewerUseDisplayListSet(bool use)

   Sets whether or not the 3D renderer uses a display list to encapsulate
   the master scene. The default is false. Ordinarily, this function does not
   need to be called by the user. Setting this property to true may have 
   cause significant negative performance on certain machines.

.. oe:function:: ViewerUseSystemFontsGet

   .. oe:api::

      bool ViewerUseSystemFontsGet()

   Returns whether or not the 3D renderer uses system fonts when displaying text.

.. oe:function:: ViewerUseSystemFontsSet

   .. oe:api::

      bool ViewerUseSystemFontsSet(bool state)

   Sets whether or not the 3D renderer uses system fonts when display text.

.. oe:function:: ViewerSetShowObjectToolbar

   .. oe:api::

      void ViewerSetShowObjectToolbar(bool state)

   Sets whether or not the style & color buttons are shown in the bottom toolbar
   for the active object

.. oe:function:: ViewerGetShowObjectToolbar

   .. oe:api::

      bool ViewerGetShowObjectToolbar()

   Sets whether or not the style & color buttons are shown in the bottom toolbar
   for the active object

   



Object Functions
****************

The functions detailed in this section provide a mechanism to add, delete, 
modify, and organize the many types of objects (e.g. molecules, grids, and 
surfaces) available in VIDA.

.. oe:function:: Add

   .. oe:api::

      unsigned int Add(OESystem::OEBase &, unsigned int listID = 0)

   Adds the specified object to the application and returns a unique ID 
   associated with that object.  If the optional listID argument is provided, 
   then the object is added to the specified list.  Otherwise, 
   a new list is created and the object is added to it.

.. oe:function:: AddCSVSmiles

   .. oe:api::

      unsigned int AddCSVSmiles( const std::string &smiles, 
                                 const std::vector<std::string> &headers, 
                                 const std::vector<std::string> &values, 
                                 const std::string &filename = "", 
                                 unsigned int       listid   = 0)

   Adds a new molecule from SMILES with the optional associated data. *smiles*
   species the SMILES string to parse, *headers* is a list of column names 
   corresponding to the data specified in *values*, *filename* is an optional
   filename to attribute this molecule to, and *listid* is the ID of the list to
   which this molecule will be added. If *listid* is zero, a new list will be
   created.
  
   Returns the ID of the list to which the molecule was added.

.. oe:function:: AddURLMol

   .. oe:api::

      unsigned int AddURLMol( const std::string              &url, 
                              const std::string              &urlFunc, 
                              const std::vector<std::string> &headers, 
                              const std::vector<std::string> &values, 
                              const std::string              &filename, 
                              unsigned int                    listid)

   Reserved for future implementation.

.. oe:function:: AtomDataGet

   .. oe:api::

      AtomData AtomDataGet(const OEPropDB::OEKey &key )

   Returns an AtomData object populated with information about the atom 
   specified by the parameter *key*.

.. oe:function:: CheckIn

   .. oe:api::

      bool CheckIn(OESystem::OEBase &)

   Checks the specified Python accessible object back into the main VIDA
   application which will synchronize any changes made to the object in Python
   with the object in VIDA. The object in question must have been checked
   out of VIDA prior to being checked back in.

   See :ref:`GridCheckOut <vida_GridCheckOut>`,
   :oe:func:`MoleculeCheckOut`, and
   :oe:func:`SurfaceCheckOut`.
  
.. oe:function:: ChildrenGet

   .. oe:api::

      std::vector<OEPropDB::OEKey> ChildrenGet(unsigned int id)
      std::vector<OEPropDB::OEKey> ChildrenGet(const OEPropDB::OEKey &)

   Returns a list of keys corresponding to any child objects associated with the
   specified object.

.. oe:function:: ContourCloudJitterDefaultGet

   .. oe:api::

      float ContourCloudJitterDefaultGet()

   Returns the value (between 0.0 and 1.0) indicated by the Jitter slider on
   the Contours panel.

.. oe:function:: ContourCloudJitterGet

   .. oe:api::

      float ContourCloudJitterGet(unsigned int id)

   Returns the jitter value assigned to grid *id*.  The jitter value is used
   when the contour is displayed with the "cloud" style, and represents the
   degree to which the grid vertex positions are to be randomized.  Jitter 
   values range from 0.0 (no jitter) to 1.0 (jitter equal to the grid spacing).

.. oe:function:: ContourCloudJitterSet

   .. oe:api::

      float ContourCloudJitterSet(unsigned int id, float jitter)

   Sets the jitter value to be used when grid *id* is displayed with the
   "cloud" style. Jitter values range from 0.0 (no jitter) to 1.0 (jitter equal
   to the grid spacing).

.. oe:function:: ContourCountScoped

   .. oe:api::

      int ContourCountScoped(unsigned int scope = BestScope)

   Returns the number of contours for all grids in *scope*.

   This returns the number of contours for the focused grid or the first grid found
   in the given scope.

.. oe:function:: ContourCreate

   .. oe:api::

      void ContourCreate(unsigned int id=0)
      void ContourCreate(unsigned int id, float threshold)
      void ContourCreate(unsigned int id, float threshold, 
                         const OESystem::OEColor &color)

   Create a new contour for grid *id*.

.. oe:function:: ContourCreateSurface

   .. oe:api::

      unsigned int ContourCreateSurface(unsigned int id, unsigned int contourIndex)

   Create a contour surface for the surface defined by the repository id *id* for
   the contour referenced by *contourIndex*.

.. oe:function:: ContourDeleteAll

   .. oe:api::

      void ContourDeleteAll(unsigned int id)

   Delete all contours for grid *id*.

.. oe:function:: ContourDeleteByIndex

   .. oe:api::

      void ContourDeleteByIndex(unsigned int id, unsigned int index)

   Delete contour *index* for grid *id*.  All contours with indices greater
   than *index* will now be at their current index - 1.

.. oe:function:: ContourDeleteByThreshold

   .. oe:api::

      void ContourDeleteByThreshold(unsigned int id, float threshold)

   Delete all contours above *threshold* for grid *id*. Contour indices will 
   be reassigned.

.. oe:function:: ContourExtractIsoSurface

   .. oe:api::

      unsigned int ContourExtractIsoSurface(unsigned int id, unsigned int vertex, 
                                            bool maskVis=true)

   Reserved for internal use.

.. oe:function:: ContourFixAsSurfaceScoped

   .. oe:api::

      std::vector<unsigned int> 
        ContourFixAsSurfaceScoped(unsigned int scope = BestScope)

   Creates an actual surface object for each contour in the specified scope.
   Returns a list of IDs corresponding to the generated surfaces.

.. oe:function:: ContourGetAll

   .. oe:api::

      std::vector<float> ContourGetAll(unsigned int id=0)

   Get all contour levels from each contour drawn for grid *id*.

.. oe:function:: ContourLevelForIndexGet

   .. oe:api::

      float ContourLevelForIndexGet(unsigned int id, unsigned int index)

   Returns the contour level for grid *id* at index *id*.

.. oe:function:: ContourLevelForIndexGetScoped

   .. oe:api::

      float ContourLevelForIndexGetScoped(int index, 
                                          unsigned int scope = BestScope)

   Returns the contour level for index *id* for the first grid in *scope*.

.. oe:function:: ContourLevelForIndexSet

   .. oe:api::

      float ContourLevelForIndexSet(unsigned int id, unsigned int index, float thresh)

   Set the level for the contour at index *index* to *thresh* for grid *id*.

.. oe:function:: ContourLevelForIndexSetScoped

   .. oe:api::

      void ContourLevelForIndexSetScoped(unsigned int index, float thresh, 
                                         unsigned int gridType=UINT_MAX, 
                                         unsigned int scope = BestScope)

   Set the level for the contour at index *index* to *thresh* for all grids
   in *scope*.

.. oe:function:: ContourLevelNudgeScoped

   .. oe:api::

      void ContourLevelNudgeScoped(bool increase, 
                                   unsigned int scope = BestScope)

   This function increases or decreases the contour value for the contours in the
   specified scope by 0.1 depending on whether the *increase* parameter is set to
   true or false.

.. oe:function:: ContourLevelSetScoped

   .. oe:api::

      void ContourLevelSetScoped(float level, 
                                 unsigned int scope = BestScope)

   This function sets the contour level of all the contours in the specified scope
   to the value specified by the parameter *level*.

.. oe:function:: ContourMax

   .. oe:api::

      float ContourMax(unsigned int oerid)

   Returns the maximum allowable contour threshold for grid *id*.

.. oe:function:: ContourMaxScoped

   .. oe:api::

      float ContourMaxScoped(unsigned int scope = BestScope)

   Returns the maximum allowable contour threshold for the first grid found in *scope*.

.. oe:function:: ContourMin

   .. oe:api::

      float ContourMin(unsigned int oerid)

   Returns the minimum allowable contour threshold for grid *id*.

.. oe:function:: ContourMinScoped

   .. oe:api::

      float ContourMinScoped(unsigned int scope = BestScope)

   Returns the minimum allowable contour threshold for the first grid found in *scope*.

.. oe:function:: ContourRadiusGet

   .. oe:api::

      float ContourRadiusGet(unsigned int id=0)

   Returns the radius used when generating contours for crystallographic grids.

.. oe:function:: ContourRadiusSet

   .. oe:api::

      float ContourRadiusSet(unsigned int id, float rad)

   Sets the radius used when generating contours for crystallographic grids.

.. oe:function:: ContourResolutionGet

   .. oe:api::

      float ContourResolutionGet(unsigned int id=0)

   Return the contouring resolution for drawing the contours in Angstroms.  A 
   lower resolution samples more grid points, but requires more memory.

.. oe:function:: ContourResolutionSet

   .. oe:api::

      float ContourResolutionSet(unsigned int id, float rad)

   Set the contouring resolution in Angstroms.  Lower values sample more grid points
   and generate finer visualizations but require more memory.

.. oe:function:: ContourTypedAddScoped

   .. oe:api::

      void ContourTypedAddScoped(unsigned int scope = BestScope)

   Add a single contour to all grids of type *type* in *scope*.

.. oe:function:: ContourTypedCountScoped

   .. oe:api::

      int ContourTypedCountScoped(unsigned int scope = BestScope)

   Return the number of contours of all grids of type *type* in *scope*.  This essentially
   returns the number of contours of the first grid found.

.. oe:function:: ContourTypedMaxScoped

   .. oe:api::

      float ContourTypedMaxScoped(unsigned int scope = BestScope)

   Returns the maximum allowable threshold for the first grid found of type *type* in
   *scope*.

.. oe:function:: ContourTypedMinScoped

   .. oe:api::

      float ContourTypedMinScoped(unsigned int scope = BestScope)

   Returns the minimum allowable threshold for the first grid found of type *type* in
   *scope*.

.. oe:function:: ContourTypedRemoveScoped

   .. oe:api::

      void ContourTypedRemoveScoped(unsigned int scope = BestScope)

   Remove the last contour from all grids of type *type* in *scope*.

.. oe:function:: ContourTypedSetLevelForIndexScoped

   .. oe:api::

      void ContourTypedSetLevelForIndexScoped(unsigned int index, float thresh, 
                                              unsigned int scope = BestScope)

   Set the contour *level* for the contour at *index* for all grids of type *type*
   in *scope*.

.. oe:function:: ContourVolume

   .. oe:api::

      float ContourVolume(unsigned int id, unsigned int contourIndex)

   Return the enclosed volume of Grid *id*'s contour at index *contourIndex*.

.. oe:function:: Delete

   .. oe:api::

      void Delete(unsigned int id)
      void Delete(const std::vector<unsigned int> &)
      void Delete(const std::vector<OEPropDB::OEKey> &)
      void Delete(const OEPropDB::OEKey &, bool all=false)

   Deletes the specified object(s) from the current session. It is important
   to note that this does NOT delete the actual files (or entries within files)
   associated with the specified objects.

.. oe:function:: DeleteAll

   .. oe:api::

      void DeleteAll(bool force=false)

   Clears the application back to a clean state with nothing loaded.

.. oe:function:: DeleteScoped

   .. oe:api::

      void DeleteScoped(unsigned int scope, bool inScope)

   Scoped version of :oe:func:`Delete<Delete>` but with the 
   additional option to specify whether to delete everything within the scope
   or everything not within the scope using the *inScope* parameter.  

.. oe:function:: FindByDataScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> FindByDataScoped(const std::string &query, 
                                                    unsigned int scope = AllScope)

   Reserved for future implementation.  

.. oe:function:: FindByQueryScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> FindByQueryScoped(const OEPropDB::OEKey &query, 
                                                     unsigned int scope = AllScope)
      std::vector<OEPropDB::OEKey> FindByQueryScoped(const OEPropDB::OEKey &query, 
                                                     unsigned int atoms, 
                                                     unsigned int bonds, 
                                                     unsigned int scope = AllScope)

   Uses the specified molecule as a query to search the specified scope. 
   Returns a list of keys corresponding to molecules that match the specified
   query.

.. oe:function:: FindBySMARTSScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> FindBySMARTSScoped(const std::string &smarts, 
                                                      unsigned int scope = AllScope)

   Uses the specified SMARTS pattern as a query to search the specified scope.
   Returns a list of keys corresponding to molecules that match the specified
   SMARTS pattern.

.. oe:function:: FindBySimilarityScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> FindBySimilarityScoped(const OEPropDB::OEKey &query, 
                                                          float similarity, 
                                                          unsigned int scope = AllScope)

   Searches the specified scope for molecules with a Lingo similarity greater 
   than the specified *similarity* cutoff with the specified molecule *query*.

.. oe:function:: FindByTitleScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> FindByTitleScoped(const std::string &expr, 
                                                     unsigned int scope = AllScope)

   Uses the specified title query as a regular expression to search the 
   specified scope for molecules whose title match the expression.

.. oe:function:: FindInRepository

   .. oe:api::

      void FindInRepository()

   This function prompts the user to specify a query to search the contents of
   the application repository. The user then has the option to select some, 
   none, or all of the hits to be placed in a new list.

.. oe:function:: FindOnDisk

   .. oe:api::

      void FindOnDisk()
      
   This function prompts the user to specify a query to search a specific region
   of the user's hard drive for molecules matching the query. The user then has
   the option to load some, none, or all of the files containing the hits. This
   function will load the entire file where a hit was discovered as opposed to 
   just the hits in that file.

.. oe:function:: GridAdd

   .. oe:api::

      unsigned int GridAdd(OESystem::OESkewGrid &grd, unsigned int listID = 0)
      unsigned int GridAdd(OESystem::OEScalarGrid &grd, unsigned int listID = 0)

   Adds the specified Python grid object to VIDA.
   If the optional listID argument is provided, then the grid is added 
   to the specified list.  Otherwise, a new list is created and the grid 
   is added to it.

.. oe:function:: GridCheckIn

   .. oe:api::

      bool GridCheckIn(OESystem::OESkewGrid &grd, 
                       unsigned int checkInType = OECheckInType_UnknownChange)
      bool GridCheckIn(OESystem::OEScalarGrid &grd, 
                       unsigned int checkInType = OECheckInType_UnknownChange)

   Checks the specified Python accessible grid back into the main VIDA
   application which will synchronize any changes made to the grid in Python
   with the grid in VIDA. The grid in question must have been checked
   out of VIDA prior to being checked back in.
  
   The *checkInType* parameter tells VIDA what type of changes were made
   to the grid in order to optimize the check in process. There are multiple
   allowable values for this parameter which can be OR'd together if 
   necessary:
  
   * OECheckInType_ConformerChange
   * OECheckInType_CoordinateChange
   * OECheckInType_DataChange
   * OECheckInType_GraphChange
   * OECheckInType_NoChange
   * OECheckInType_RenderChange
   * OECheckInType_AnnotationChange
   * OECheckInType_UnknownChange

..  _vida_GridCheckOut:

.. oe:function:: GridCheckOut

   .. oe:api::

      bool GridCheckOut(OESystem::OESkewGrid &grd, unsigned int id)
      bool GridCheckOut(OESystem::OEScalarGrid &grd, unsigned int id)

   Checks out a copy of the grid specified by *id* into the specified Python
   grid object (*grd*). Returns whether or not the check out process succeeded.
  
   The checked out grid can be modified in Python, but those changes will not be
   applied to the original grid in VIDA until the modified grid is
   checked back in using the 
   :oe:func:`GridCheckIn` command.

.. oe:function:: GridClear

   .. oe:api::

      void GridClear(unsigned int id)

   Clears the data on the specified grid.

.. oe:function:: GridCopy

   .. oe:api::

      unsigned int GridCopy(unsigned int id)
      
   Creates a copy of the specified grid and returns the ID of the newly created
   copy.

.. oe:function:: GridCreateElectrostaticsGrid

   .. oe:api::

      unsigned int GridCreateElectrostaticsGrid(OEPropDB::OEKey k, 
                                                bool property=false)

   Create an electrostatics grid for molecule *id*.  

   If *property* is true, then this grid is attached to *id* and does not show 
   up in the list window.  These grids cannot be saved to disk.

   If *property* is false, then this grid is created as a separate entity from
   *id*.

.. oe:function:: GridCreateGaussian

   .. oe:api::

      unsigned int GridCreateGaussian(const OEPropDB::OEKey &k, float res)

   Creates a gaussian grid representation for the molecule associated with the
   specified key at the specified resolution.

.. oe:function:: GridCreateGaussianProduct

   .. oe:api::

      unsigned int GridCreateGaussianProduct(const OEPropDB::OEKey &k, float res)

   Creates a gaussian product grid representation for the molecule associated with
   the specified key at the specified resolution.
   
.. oe:function:: GridDefaultContourLevelByIndexGet

   .. oe:api::

      float GridDefaultContourLevelByIndexGet(unsigned int gridType, 
                                              unsigned int index)

   Returns the default contour level for contour *index* for grids of type *gridType*.

.. oe:function:: GridDefaultContourLevelByIndexSet

   .. oe:api::

      void GridDefaultContourLevelByIndexSet(unsigned int gridType, 
                                             unsigned int index, float thresh)

   Set the default contour level *thresh* for contour *index* for grids of type *gridType*.

.. oe:function:: GridDefaultNumContoursGet

   .. oe:api::

      unsigned int GridDefaultNumContoursGet(unsigned int gridType)

   Returns the default number of contours for grids of type *gridType*.

.. oe:function:: GridDefaultNumContoursSet

   .. oe:api::

      void GridDefaultNumContoursSet(unsigned int gridType, unsigned int count)

   Set the default number of contours for grids of type *gridType* to *count*.

.. oe:function:: GridInitializeContours

   .. oe:api::

      void GridInitializeContours(unsigned int id, bool update=true)

   Initialize a grid to its default contours, colors and levels.

.. oe:function:: GridNormalize

   .. oe:api::

      bool GridNormalize(unsigned int id)

   Normalizes a grid. This finds the sigma for the grid and divides all grid points
   by that value.

.. oe:function:: GridRegularize

   .. oe:api::

      unsigned int GridRegularize(unsigned int id)

  Regularizes the specified skew grid. Returns the ID of the newly created 
  regular scalar grid.

.. oe:function:: GridToGaussianGrid

   .. oe:api::

      unsigned int GridToGaussianGrid(unsigned int id)

   Creates a gaussian grid representation for the specified grid.

.. oe:function:: GridTypeGet

   .. oe:api::

      unsigned int GridTypeGet(unsigned int oerid)

   Returns the type of grid for grid *id*.

.. oe:function:: GridTypeGetScoped

   .. oe:api::

      unsigned int GridTypeGetScoped(unsigned int scope = BestScope)

   Returns the type of grid for the first grid found in *scope*.

.. oe:function:: GridTypeSet

   .. oe:api::

      void GridTypeSet(unsigned int id, unsigned int gridType)

   Set the grid type of grid *id* to *gridType*.

.. oe:function:: GridTypeSetScoped

   .. oe:api::

      void GridTypeSetScoped(unsigned int gridType, 
                             unsigned int scope = BestScope)

   Scoped version of GridTypeSet.

.. oe:function:: GridWorkingGetScoped

   .. oe:api::

      unsigned int GridWorkingGetScoped(unsigned int scope = BestScope)

   Returns the ID for the "working grid" which is determined in the following 
   order: grid associated with selected contour, grid which is currently focused,
   grid which is a child object of the currently focused object, or lastly the 
   first grid found in the current default scope.

.. oe:function:: HasGridChildrenScoped

   .. oe:api::

      int HasGridChildrenScoped(unsigned int scope = BestScope)

   Returns whether or not any of the molecules in the specified scope have visible
   grids attached to them. Returns 0 for none of the molecules have visible grids,
   1 for all molecules have visible grid, and 2 for at least one has a visible grid.

.. oe:function:: HasSurfaceChildrenScoped

   .. oe:api::

      int HasSurfaceChildrenScoped(const std::string &type, 
                                   unsigned int scope = BestScope)

   Returns whether or not any of the molecules in the specified scope have visible
   surfaces attached to them. Returns 0 for none of the molecules have visible 
   surfaces, 1 for all molecules have visible surface, and 2 for at least one has a 
   visible surface.

.. oe:function:: Initialize

   .. oe:api::

      void Initialize(unsigned int id)
      void Initialize(const OEPropDB::OEKey &)

   Initializes the specified object for display. This function is automatically
   called on objects that are loaded into VIDA and ordinarily should not
   need to be called by the user.

.. oe:function:: IsAGrid

   .. oe:api::

      bool IsAGrid(unsigned int id)
      bool IsAGrid(const OEPropDB::OEKey &k)

   Returns whether or not the specified object is a grid.

.. oe:function:: IsAList

   .. oe:api::

      bool IsAList(unsigned int id)
      
   Returns whether or not the specified object is a list.
  
.. oe:function:: IsAMolecule

   .. oe:api::

      bool IsAMolecule(unsigned int id)
      bool IsAMolecule(const OEPropDB::OEKey &k)

   Returns whether or not the specified object is a molecule.

.. oe:function:: IsAReflection

   .. oe:api::

      bool IsAReflection(unsigned int id)
      bool IsAReflection(const OEPropDB::OEKey &k)

   Returns whether or not the specified object is a reflection.

.. oe:function:: IsASmallMolecule

   .. oe:api::

      bool IsASmallMolecule(unsigned int id)
      bool IsASmallMolecule(const OEPropDB::OEKey &k)

   Returns whether or not the specified object is a small molecule.

.. oe:function:: IsASurface

   .. oe:api::

      bool IsASurface(unsigned int id)
      bool IsASurface(const OEPropDB::OEKey &k)

   Returns whether or not the specified object is a surface.

.. oe:function:: KeyGet

   .. oe:api::

      OEPropDB::OEKey KeyGet(const OESystem::OEBase &)
      OEPropDB::OEKey KeyGet(const OESystem::OEBase &, const OEPropDB::OEKey &pkey)

   Returns the key associated with the specified OEBase object. If the object's
   parent key is known, that can be passed as a parameter as well to aid the key
   determination process.

.. oe:function:: KeyIDGet

   .. oe:api::

      unsigned int KeyIDGet(const OEPropDB::OEKey &)

   Returns the ID associated with the specified key.

.. oe:function:: KeyParentIDGet

   .. oe:api::

      unsigned int KeyParentIDGet(const OEPropDB::OEKey &)

   Returns the ID of the parent object associated with the specified key. This 
   function should be used for child object types such as atoms, bonds, 
   triangles, and vertices.

.. oe:function:: KeySourceIDGet

   .. oe:api::

      unsigned int KeySourceIDGet(const OEPropDB::OEKey &)

   Returns the ID of the parent object associated with a specified key. This 
   function should be used for top-level object types such as molecules, grids,
   and surfaces in situations where these objects have been added as children to
   another object.

.. oe:function:: KeyTypeGet

   .. oe:api::

      std::string KeyTypeGet(const OEPropDB::OEKey &)

   Returns a string representation of the object type associated with the 
   specified key. Return values include:
  
    * "Atom"
    * "Bond"
    * "Grid"
    * "Mol"
    * "Surface"
    * "Triangle"
    * "Vertex"
    
.. oe:function:: KeysGet

   .. oe:api::

      std::vector<OEPropDB::OEKey> KeysGet(unsigned int id)

   Returns a list of all the keys for the specified ID. For most objects, the
   list returned will contain a single entry; however, for multi-conformer 
   molecules, the list will include a key for each individual conformer.

.. oe:function:: ListAddObject

   .. oe:api::

      bool ListAddObject(unsigned int listid, unsigned int objectid)

   Adds the object specified by *objectid* to the list specified by *listid*.

.. oe:function:: ListAddObjects

   .. oe:api::

      bool ListAddObjects(unsigned int listid, 
                          const std::vector<unsigned int> &ids)

   Adds the objects specified by the list of IDs (*ids*) to the list specified
   by *listid*.

.. oe:function:: ListGetNames

   .. oe:api::

      std::vector<std::string> ListGetNames()

   Returns a list of the names of all the current lists.

.. oe:function:: ListGetObjectLists

   .. oe:api::

      std::vector<unsigned int> ListGetObjectLists(unsigned int objectid)

   Returns a list of all the lists to which the object specified by *objectid* 
   belongs.

.. oe:function:: ListGetObjects

   .. oe:api::

      std::vector<unsigned int> ListGetObjects(unsigned int listid)

   Returns a list of IDs of all the objects contained within the list specified
   by *listid*.

.. oe:function:: ListMoveObject

   .. oe:api::

      bool ListMoveObject(unsigned int srclist, unsigned int dstlist, 
                          unsigned int objectid)
  
   Moves the object specified by *objectid* from the list specified by *srclist*
   to the list specified by *dstlist*.

.. oe:function:: ListMoveObjects

   .. oe:api::

      bool ListMoveObjects(unsigned int srclist, unsigned int dstlist, 
                           const std::vector<unsigned int> &ids)

   Moves the objects specified by list of IDs (*ids*) from the list specified by 
   *srclist* to the list specified by *dstlist*.

.. oe:function:: ListNew

   .. oe:api::

      unsigned int ListNew(const std::string &name)
      unsigned int ListNew(const std::string &name, 
                           const std::vector<unsigned int> &ids)
      unsigned int ListNew(const std::string &name, 
                           const std::vector<OEPropDB::OEKey> &keys)

   Creates a new list with the specified name. If a list of IDs or keys is 
   specified with this call, all of the objects corresponding to those IDs or 
   keys will be added to the list.
  
   Returns the ID of the created list.

.. oe:function:: ListNewAnd

   .. oe:api::

      unsigned int ListNewAnd(const std::vector<unsigned int> &ids)

   Creates a new list containing all of the objects that each appear in every 
   list specified by the list of IDs (*ids*).

   Returns the ID of the created list.

.. oe:function:: ListNewMarked

   .. oe:api::

      unsigned int ListNewMarked(const std::string &name="")
      
   Creates a new list containing all the currently marked objects. Objects will
   not be removed from this list if they are subsequently unmarked.
  
   Returns the ID of the created list.

.. oe:function:: ListNewOr

   .. oe:api::

      unsigned int ListNewOr(const std::vector<unsigned int> &ids)

   Creates a new list containing all of the objects in all of the lists 
   specified by the list of IDs (*ids*).
  
   Returns the ID of the created list.

.. oe:function:: ListNewXor

   .. oe:api::

      unsigned int ListNewXor(const std::vector<unsigned int> &ids)

   Creates a new list containing all of the objects that each appear only once 
   among all the lists specified by the list of IDs (*ids*).
  
   Returns the ID of the created list.

.. oe:function:: ListRemoveObject

   .. oe:api::

      bool ListRemoveObject(unsigned int listid, unsigned int objectid)

   Removes the object specified by *objectid* from the list specified by
   *listid*.

.. oe:function:: ListRemoveObjects

   .. oe:api::

      bool ListRemoveObjects( unsigned int listid, 
                              const std::vector<unsigned int> &ids )

   Removes the object(s) specified by the list of IDs (*ids*) from the list
   specified by *listid*.

.. oe:function:: ListRootList

   .. oe:api::

      unsigned int ListRootList()

   Returns the ID of the root list.

.. oe:function:: ListSubsetMarked

   .. oe:api::

      unsigned int ListSubsetMarked(unsigned int id, bool match)

   Creates a new list containing a subset of the objects contained within the
   list specified by *id*. If the *match* parameter is True, the subset will
   contain all of the marked objects in the source list, if *match* is False,
   the subset will contain all of the non-marked objects in the source list.
  
   Returns the ID of the created list.

.. oe:function:: ListSubsetQuery

   .. oe:api::

      unsigned int ListSubsetQuery(unsigned int id, const std::string &, bool match)

   Creates a new list containing a subset of the objects contained within the
   list specified by *id*. If the *match* parameter is True, the subset will
   contain all of the objects that match the specified query in the source list, 
   if *match* is Fale, the subset will contain all of the objects which fail to
   match the specified query in the source list. The query parameter can be 
   specified as a SMARTS, a SMILES, or an IUPAC name.
  
   Returns the ID of the created list.

.. oe:function:: MoleculeAdd

   .. oe:api::

      unsigned int MoleculeAdd(const std::string &, unsigned int listID = 0)
      unsigned int MoleculeAdd(OEChem::OEMCMolBase &, unsigned int listID  = 0)

   Adds a new molecule to VIDA. There are two implementations of this
   function. The first implementation expects a hexadecimal encoded OEB string
   specifying a molecule. The second implementation expects a Python molecule
   object.
  
   If the optional listID argument is provided, then the molecule is added 
   to the specified list.  Otherwise, a new list is created and the molecule 
   is added to it.

   Returns the ID assigned to the newly added molecule or zero if the add failed
   for any reason.
  
.. oe:function:: MoleculeCheckIn

   .. oe:api::

      bool MoleculeCheckIn(OEChem::OEMCMolBase &mol, 
                           unsigned int checkInType = OECheckInType_UnknownChange )

   Checks the specified Python accessible molecule back into the main VIDA
   application which will synchronize any changes made to the molecule in Python
   with the molecule in VIDA. The molecule in question must have been
   checked out of VIDA prior to being checked back in.
  
   The *checkInType* parameter tells VIDA what type of changes were made
   to the molecule in order to optimize the check in process. There are multiple
   allowable values for this parameter which can be OR'd together if 
   necessary:
  
   * OECheckInType_ConformerChange
   * OECheckInType_CoordinateChange
   * OECheckInType_DataChange
   * OECheckInType_GraphChange
   * OECheckInType_NoChange
   * OECheckInType_RenderChange
   * OECheckInType_AnnotationChange
   * OECheckInType_UnknownChange

.. oe:function:: MoleculeCheckOut

   .. oe:api::

      bool MoleculeCheckOut(OEChem::OEMCMolBase &mol, unsigned int id)

   Checks out a copy of the molecule specified by *id* into the specified Python
   molecule object (*mol*). Returns whether or not the check out process 
   succeeded.
  
   The checked out molecule can be modified in Python, but those changes will not
   be applied to the original molecule in VIDA until the modified molecule
   is checked back in using the 
   :oe:func:`MoleculeCheckIn` command.

.. oe:function:: MoleculeComponentNamesGet

   .. oe:api::

      std::vector<std::string> MoleculeComponentNamesGet(unsigned int id)

   Returns a list of names of the individual components of the molecule 
   specified by ``id`` based on PDB related subsets.

.. oe:function:: MoleculeExamine

   .. oe:api::

      bool MoleculeExamine(OEChem::OEMCMolBase &, unsigned int id)
      bool MoleculeExamine(OEChem::OEMCMolBase &, const OEPropDB::OEKey &key)

   Copies the molecule associated with the specified ID or key into the 
   specified Python molecule object. Returns True if the copy happened
   successfully.  In cases where a script needs read-only access to a
   molecule, MoleculeExamine provides a much faster way to retrieve
   molecules than MoleculeCheckOut or MoleculeGet.  Molecules retrieved using
   MoleculeExamine cannot be checked back in using MoleculeCheckIn.

.. oe:function:: MoleculeGet

   .. oe:api::

      bool MoleculeGet(OEChem::OEMCMolBase &, unsigned int id)
      bool MoleculeGet(OEChem::OEMCMolBase &, const OEPropDB::OEKey &key)
      OEChem::OEMol MoleculeGet(unsigned int id)
      OEChem::OEMol MoleculeGet(const OEPropDB::OEKey &key)

   Copies the molecule associated with the specified ID or key into the 
   specified Python molecule object. Returns whether or not the copy happened
   successfully.

.. oe:function:: MoleculeHasComponents

   .. oe:api::

      bool MoleculeHasComponents(unsigned int id)

   Returns whether or not the molecule specified by ``id`` contains multiple
   distinct components.

.. oe:function:: MoleculeMaxResidueGet

   .. oe:api::

      int MoleculeMaxResidueGet(unsigned int id)
  
   Returns the largest residue index of all the residues contained within the
   specified molecule.

.. oe:function:: MoleculeMergeScoped

   .. oe:api::

      unsigned int MoleculeMergeScoped(unsigned int scope = BestScope, 
                                       const std::string &name="Merged", 
                                       unsigned int listid=0)

   Merges all of the molecules in the specified scope into a single new molecule.
   The ``name`` parameter specifies the new molecule's name and the ``listid``
   parameter specifies in which list to place this new molecule. If ``listid``
   is 0, a new list will be created to contain the created molecule.

.. oe:function:: MoleculeNewSubset

   .. oe:api::

      std::vector<unsigned int> MoleculeNewSubset(unsigned int listid, 
                                                  unsigned int id, bool pdb)
      std::vector<unsigned int> MoleculeNewSubset(unsigned int listid, 
                                                  unsigned int id, unsigned int scope, 
                                                  bool unmatched)
      std::vector<unsigned int> MoleculeNewSubset(unsigned int listid, 
                                                  unsigned int id, 
                                                  const std::vector<std::vector<unsigned int> > &parts)

   This function creates a series of new molecules from the given molecule based on
   its internal components determined by OEChem using the OEDetermineComponents function.

.. oe:function:: MoleculeNewSubsetScoped

   .. oe:api::

      std::vector<unsigned int> MoleculeNewSubsetScoped(unsigned int listid, 
                                                        unsigned int scope, bool pdb)
      std::vector<unsigned int> MoleculeNewSubsetScoped(unsigned int listid, 
                                                        unsigned int mscope, 
                                                        unsigned int scope, 
                                                        bool unmatched)

   This function creates a series of new molecules from the given scope based on
   its internal components determined by OEChem using the OEDetermineComponents function.

.. oe:function:: MoleculeResidueNameSetScoped

   .. oe:api::

      void MoleculeResidueNameSetScoped(const std::string &name, 
                                        unsigned int scope = BestScope)

   Renames all the residues in the specified scope.

.. oe:function:: MoleculeResidueSet

   .. oe:api::

      int MoleculeResidueSet(unsigned int id, int residueNum, 
                             bool incrementPerRes=false)

   Sets the residue number of every residue in the specified molecule to the 
   specified value (*residueNum*). The *incrementPerRes* parameter is currently
   reserved for future expansion.

.. oe:function:: MoleculeSetProperty

   .. oe:api::

      void MoleculeSetProperty(const std::vector<OEPropDB::OEKey> &keys, 
                               unsigned char action, std::string prop, bool state)

   Reserved for internal use.

.. oe:function:: MoleculeSizeCutoffGet

   .. oe:api::

      unsigned int MoleculeSizeCutoffGet()

   Returns the atom number cutoff at which point a molecule is considered to be
   a "large" molecule. The default is 255.

.. oe:function:: MoleculeSizeCutoffSet

   .. oe:api::

      void MoleculeSizeCutoffSet(unsigned int size)

   Sets the atom number cutoff at which point a molecule is considered to be a 
   "large" molecule. The default is 255.

.. oe:function:: MoleculeUpdate

   .. oe:api::

      bool MoleculeUpdate(OEChem::OEMCMolBase &)

   Updates the original molecule stored in VIDA with any changes that may
   have been made to the specified Python molecule.

.. oe:function:: NameGet

   .. oe:api::

      std::string NameGet(unsigned int)
      std::string NameGet(const OEPropDB::OEKey &)

   Returns the name of the object specified by either its ID or key.

.. oe:function:: NameSet

   .. oe:api::

      void NameSet(unsigned int, const std::string &)
      void NameSet(const OEPropDB::OEKey &, const std::string &)

   Sets the name of the object specified by either its ID or key.

.. oe:function:: OEFuseKeyGroups

   .. oe:api::

      OEKeyGroup OEFuseKeyGroups(const std::vector<OEKeyGroup> &k1, 
                                 unsigned char type)

   Fuses the specified keys groups into a single key group.

.. oe:function:: OEKeyIterToVector

   .. oe:api::

      std::vector<OEPropDB::OEKey> 
        OEKeyIterToVector(OESystem::OEIterBase<const OEPropDB::OEKey> *iterbase)

   Converts a key iterator into a list of keys.

.. oe:function:: PropertyTypeGet

   .. oe:api::

      unsigned int PropertyTypeGet(const std::string &type)

   Returns the integer property type for the string *type*. See 
   :oe:func:`KeyTypeGet` for a list of types.

.. oe:function:: SDDataGet

   .. oe:api::

      std::string SDDataGet(unsigned int id, const std::string &tag)
      std::string SDDataGet(const OEPropDB::OEKey &key, const std::string &tag)

   Returns the SD data associated with the specified tag on the specified object.

.. oe:function:: SDDataHas

   .. oe:api::

      bool SDDataHas(unsigned int id, const std::string &tag)
      bool SDDataHas(const OEPropDB::OEKey &key, const std::string &tag)

   Returns whether or not the specified object contains SD data with the 
   specified tag.

.. oe:function:: SDDataSet

   .. oe:api::

      void SDDataSet(unsigned int id, const std::string &tag, const std::string &data)
      void SDDataSet(const OEPropDB::OEKey &key, const std::string &tag, 
                     const std::string &data)

   Sets the value of the SD data associated with the specified tag on the 
   specified object.

.. oe:function:: SurfaceAdd

   .. oe:api::

      unsigned int SurfaceAdd(OESpicoli::OESurface &surf, unsigned int listID = 0)

   Adds a new Python surface object to VIDA. Returns the ID assigned to
   the newly added surface or zero if the add failed for any reason.
   If the optional listID argument is provided, then the surface is added 
   to the specified list.  Otherwise, a new list is created and the surface 
   is added to it.

.. oe:function:: SurfaceBestFloodScoped

   .. oe:api::

      int SurfaceBestFloodScoped(unsigned int scope = BestScope)

   Return the largest flood value for all surfaces in the given scope. A flood value 
   defines the surface being scribed.

.. oe:function:: SurfaceCheckIn

   .. oe:api::

      bool SurfaceCheckIn(OESpicoli::OESurface &surf, 
                          unsigned int checkInType = OECheckInType_UnknownChange)

   Checks the specified Python accessible surface back into the main VIDA
   application which will synchronize any changes made to the surface in Python
   with the surface in VIDA. The surface in question must have been
   checked out of VIDA prior to being checked back in.
  
   The *checkInType* parameter tells VIDA what type of changes were made
   to the surface in order to optimize the check in process. There are multiple
   allowable values for this parameter which can be OR'd together if 
   necessary:
  
   * OECheckInType_ConformerChange
   * OECheckInType_CoordinateChange
   * OECheckInType_DataChange
   * OECheckInType_GraphChange
   * OECheckInType_NoChange
   * OECheckInType_RenderChange
   * OECheckInType_AnnotationChange
   * OECheckInType_UnknownChange

.. oe:function:: SurfaceCheckOut

   .. oe:api::

      bool SurfaceCheckOut(OESpicoli::OESurface &surf, unsigned int id)

   Checks out a copy of the surface specified by *id* into the specified Python
   surface object (*surf*). Returns whether or not the check out process 
   succeeded.
  
   The checked out surface can be modified in Python, but those changes will not 
   be applied to the original surface in VIDA until the modified surface is
   checked back in using the 
   :oe:func:`SurfaceCheckIn` command.

.. oe:function:: SurfaceCreate

   .. oe:api::

      unsigned int SurfaceCreate(const std::string &, const OEPropDB::OEKey &key, 
                                 bool property=false)

   Create a surface of type *type* based on the molecule represented by *key*.

   If *property* is true, then make the surface a property surface that is
   bound to the molecule.

.. oe:function:: SurfaceCreateScoped

   .. oe:api::

      bool SurfaceCreateScoped(const std::string &, bool single_surface=false, 
                               unsigned int scope = BestScope)

   Create a surface of type *type* for each molecule in *scope*.

   If *property* is true, then make the surface a property surface that is
   bound to the molecule.

.. oe:function:: SurfaceCropDistance

   .. oe:api::

      void SurfaceCropDistance(unsigned int id, float distance)

   Retains the section of the surface specified by *oerid* to a distance *dist*
   from the selected set of atoms.

.. oe:function:: SurfaceCropDistanceFrom

   .. oe:api::

      void SurfaceCropDistanceFrom(const OEPropDB::OEKey &s, const OEPropDB::OEKey &, 
                                   float distance)

   Retains the section of the surface specified by *s* based on its distance to
   another object. The reference object can be a molecule or another surface. The
   distance cutoff is measured in Angstroms.

.. oe:function:: SurfaceCropScribedScoped

   .. oe:api::

      void SurfaceCropScribedScoped(unsigned int scope = BestScope)

   Retains the section of all surfaces in *scope* to a distance *dist*
   from the selected set of atoms.

.. oe:function:: SurfaceCropUnscribedScoped

   .. oe:api::

      void SurfaceCropUnscribedScoped(unsigned int scope = BestScope)

   Remove the scribed sections of all scribed surfaces in *scope*.

.. oe:function:: SurfaceDelete

   .. oe:api::

      void SurfaceDelete(unsigned int id)

   Delete the surface specified by *id*.

.. oe:function:: SurfaceGenerateBox

   .. oe:api::

      unsigned int SurfaceGenerateBox(float x, float y, float z, float width, 
                                      float height, float depth)

   Creates and returns the id of a surface representing a box as determined by the
   parameters *x*, *y*, *z*, *width*, *height*, and *depth*.

.. oe:function:: SurfaceGenerateSphere

   .. oe:api::

      unsigned int SurfaceGenerateSphere(float x, float y, float z, float radius, 
                                         int level=10)

   Creates and returns the id of a surface representing a sphere as determined by the
   parameters *x*, *y*, *z*, and *radius*. The *level* parameter specifies how many
   iterations should be used in determining the quality of the surface.

.. oe:function:: SurfaceGenerateSpline

   .. oe:api::

      unsigned int SurfaceGenerateSpline(const std::vector<float> &coords, 
                                         int splineResolution, int seq_res, 
                                         int cross_res, float width, float thick, 
                                         int splineType, int style)

   Creates and returns the id of a surface representing a spline as determined by the
   parameters *coords*, *splineResolution*, *seq_res*, *cross_res*, *width*, *thick*,
   *splineType*, and *style*.

.. oe:function:: SurfacePickTriangle

   .. oe:api::

      void SurfacePickTriangle(unsigned int oerid, const OEPropDB::OEKey &trikey, 
                               bool addtriangle=false)

   Pick a surface triangle specified by *trikey*. Ordinarily, this function 
   does not need to be called.

.. oe:function:: SurfaceProbeRadiusGet

   .. oe:api::

      float SurfaceProbeRadiusGet()

   Get the probe radius used when creating surfaces.

.. oe:function:: SurfaceProbeRadiusSet

   .. oe:api::

      float SurfaceProbeRadiusSet(float radius)

   Set the probe radius to *radius* that is used when creating surfaces.

.. oe:function:: SurfaceResolutionGet

   .. oe:api::

      float SurfaceResolutionGet()

   Get the resolution used when creating surfaces.

.. oe:function:: SurfaceResolutionSet

   .. oe:api::

      float SurfaceResolutionSet(float res)

   Set the resolution used when creating surfaces.  The resolution is set to *resolution*.

.. oe:function:: SurfaceRestoreScoped

   .. oe:api::

      void SurfaceRestoreScoped(unsigned int scope = BestScope)

   Restore all surfaces in *scope* to their original states.

.. oe:function:: SurfaceScribeScoped

   .. oe:api::

      void SurfaceScribeScoped(int flood, 
                               unsigned int scope = BestScope)

   Scribe all scribed surfaces in scope to include all portions of the surface
   that fall within *flood*. Ordinarily, this function does not need to be called.

.. oe:function:: SurfaceSetPotentialFromGrid

   .. oe:api::

      void SurfaceSetPotentialFromGrid(unsigned int id, unsigned int gridid)

   Sets the surface potential for the specified surface using the values in the
   specified grid.

.. oe:function:: SurfaceSetPotentialFromGridScoped

   .. oe:api::

      void SurfaceSetPotentialFromGridScoped(unsigned int gridid, 
                                             unsigned int scope = BestScope)

   Sets the surface potential for all the surfaces in the specified scope using
   the values in the specified grid.

.. oe:function:: SurfaceVolume

   .. oe:api::

      float SurfaceVolume(unsigned int id)

   Returns the enclosed volume of surface *id*.

.. oe:function:: SymmetryNumOperators

   .. oe:api::

      unsigned int SymmetryNumOperators(unsigned int id)

   This function returns the number of symmetry operators for the specified id.

.. oe:function:: SymmetryOperatorEnabledGet

   .. oe:api::

      bool SymmetryOperatorEnabledGet(unsigned int id, unsigned int operatorNumber)

.. oe:function:: SymmetryOperatorEnabledSet

   .. oe:api::

      bool SymmetryOperatorEnabledSet(unsigned int id, unsigned int operatorNumber, 
                                      bool enable)

.. oe:function:: SymmetryRadiusGet

   .. oe:api::

      float SymmetryRadiusGet()

.. oe:function:: SymmetryRadiusSet

   .. oe:api::

      float SymmetryRadiusSet(float r)

.. oe:function:: SymmetryRealize

   .. oe:api::

      unsigned int SymmetryRealize(unsigned int id, bool make_new_mol, 
                                   std::vector<float> center=std::vector<float>(), 
                                   float radius=0.0f)

.. oe:function:: XRayAutoMapCalculationPrefsSet

   .. oe:api::

      void XRayAutoMapCalculationPrefsSet()
      void XRayAutoMapCalculationPrefsSet(const std::string &map1, 
                                                        const std::string &map2="")

   Set the map types for maps which should be calculated automatically after
   reading a reflection file.

.. oe:function:: XRayCalculateMap

   .. oe:api::

      unsigned int XRayCalculateMap(unsigned int map_id, 
                                    unsigned int refln_id, 
                                    std::string map_type)
      unsigned int XRayCalculateMap(unsigned int map_id, 
                                    unsigned int refln_id, 
                                    unsigned int map_type)

   This set of overloaded functions calculates a map for the set of
   reflection data specified by 'refln_id'.  If 'map_id' is non-zero,
   then the map replaces the grid with that ID.  Otherwise, an entirely
   new map is created.  The string 'map_type' parameter may be one of\:
   Fo, Fc, 2Fo-Fc, Fo-Fc, 3Fo-2Fc, 5Fo-3Fc, Fo*Fo, or Fo*FOM, while the
   integer version may be one of\: 0 Fo, 1 Fc, 2 TwoFoFc, 3 FoFc, 4
   ThreeFoTwoFc, 5 FiveFoThreeFc, 8 FoSquared, 9 FoFom.

.. oe:function:: XRayCalculatePhases

   .. oe:api::

      bool XRayCalculatePhases(unsigned int refln_id, 
                               unsigned int model_id)

   This is experimental, and should not be called by the user.

.. oe:function:: XRayGetCell

   .. oe:api::

      std::vector<float> XRayGetCell(unsigned int id)

   Returns the cell constants for the given object in a list, in the
   order a, b, c, Alpha, Beta, Gamma.

.. oe:function:: XRayGetSpaceGroup

   .. oe:api::

      std::string XRayGetSpaceGroup(unsigned int id)

   Returns the spacegroup name for the given object.

.. oe:function:: XRayMTZColumnNamesCurrentDefaultsGet

   .. oe:api::

      std::vector<std::string> XRayMTZColumnNamesCurrentDefaultsGet()

.. oe:function:: XRayMTZColumnNamesGet

   .. oe:api::

      std::vector<std::string> XRayMTZColumnNamesGet()
      bool XRayMTZColumnNamesGet(std::vector<std::string> &names)

   Fills up the input list/vector with the MTZ file column names as specified
   by *XRayMTZColumnNamesSet*.  Unless *XRayMTZColumnNamesSet* was called
   with the *permanent* flag, this function will only work once per call to
   *XRayMTZColumnNamesSet*.

   This function returns True if it successfully filled out the list/vector,
   or False otherwise.

.. oe:function:: XRayMTZColumnNamesSet

   .. oe:api::

      void XRayMTZColumnNamesSet(const std::vector<std::string> &names, 
                                 bool permanent=false)

   Stores a list of column names for mtz files. The next time an MTZ file is
   read, instead of prompting the user, the column names are taken from the
   list/vector passed to this function. The column names are in the
   order Fo, Phi, Fc, PhiC, Sigma, FOM, RFree.  If the *permanent* flag is
   set to True, then these values are used instead of prompting until the
   program exits.  If *permanent* is false, then the values are only used
   once. 

   In a script, there's no reason to call this command instead of
   pre-specifying the prompt results with *PromptResponseVectMulti*, as shows
   up in the journal file.  However, if creating a function which will read
   an MTZ file directly then this command is needed since the
   *PromptResponse* commands don't work in interactive commands.

.. oe:function:: XRayMTZColumnNamesStandardDefaultsGet

   .. oe:api::

      std::vector<std::string> XRayMTZColumnNamesStandardDefaultsGet()

.. oe:function:: XRaySetCrystalParams

   .. oe:api::

      bool XRaySetCrystalParams(unsigned int id, 
                                unsigned int from_object_id)
      bool XRaySetCrystalParams(unsigned int id, 
                                std::vector<float> cell, 
                                unsigned int sg)
      bool XRaySetCrystalParams(unsigned int id, 
                                std::vector<float> cell, 
                                const std::string &sgname)
      bool XRaySetCrystalParams(unsigned int id, float a, float b, 
                                float c, float alpha, float beta, 
                                float gamma, unsigned int sg)
      bool XRaySetCrystalParams(unsigned int id, float a, float b, 
                                float c, float alpha, float beta, 
                                float gamma, const std::string &sgname)

   Set the crystal parameters for the given reflection.  The parameters may
   be specified in multiple ways, which are obvious from the names of the arguments.

.. oe:function:: XRayValidMaptypes

   .. oe:api::

      std::string XRayValidMaptypes(unsigned int refln_id)

   Not all map types are available for every reflection data set, since not
   all files have all required data for every possible map calculation.  For
   example, a reflection data set without Fc data will not be able to
   calculate any map types which require Fc.  This function returns (as a
   string), the valid map types for the given reflection data set.  The
   string is a concatenation of all available map types, with each type
   separated by the '|' character.



Scope Functions
***************************

The functions detailed in this section enable the user to access information
about and change the state of the application through the multiple different
available scopes.

.. oe:function:: Active

   .. oe:api::

      void Active(const OEPropDB::OEKey &k)
      void Active(unsigned int id, unsigned int conf=UINT_MAX)

   Makes the specified object the *Active* or *Focused* object in the 
   application. The object is specified by passing either an OEKey object or a 
   unique ID paired with a conformer index (if dealing with multiconformer 
   molecules). 

.. oe:function:: ActiveConformer

   .. oe:api::

      unsigned int ActiveConformer()

   Returns the index of the currently *Active* or *Focused* conformer.

.. oe:function:: ActiveID

   .. oe:api::

      unsigned int ActiveID()

   Returns the unique ID associated with the currently *Active* or *Focused* 
   object.

.. oe:function:: ActiveKey

   .. oe:api::

      OEPropDB::OEKey ActiveKey()

   Returns the unique key associated with the currently *Active* or *Focused* 
   object.

.. oe:function:: ClearActive

   .. oe:api::

      void ClearActive()

   Clears the *active* / *focused* property from the currently *active* object.

.. oe:function:: ClearLocked

   .. oe:api::

      void ClearLocked()

   Clears the locked property from all objects.

.. oe:function:: ClearMarked

   .. oe:api::

      void ClearMarked()

   Clears the marked property from all objects.

.. oe:function:: ClearSelection

   .. oe:api::

      void ClearSelection()

   Clears the selected property from all objects.

.. oe:function:: ClearVisible

   .. oe:api::

      void ClearVisible()

   Clears the visible property from all objects.

.. oe:function:: ContextClear

   .. oe:api::

      void ContextClear()

   Clears the context scope.

.. oe:function:: ContextGet

   .. oe:api::

      std::vector<OEPropDB::OEKey> ContextGet()

   Returns the list of keys currently contained in the context scope. The 
   "context" scope is used to determine which operations are appropriate 
   for display in the right-click popup menu.

.. oe:function:: ContextInsert

   .. oe:api::

      void ContextInsert(const OEPropDB::OEKey &)
      void ContextInsert(const std::vector<OEPropDB::OEKey> &)

   Inserts the specified key(s) into the context scope. The "context" scope is
   used to determine which operations are appropriate for display in the 
   right-click popup menu.

.. oe:function:: ContextKeysSet

   .. oe:api::

      void ContextKeysSet(const OEPropDB::OEKeyGroup &k)
      void ContextKeysSet(const std::vector<OEPropDB::OEKey> &keys)

   Sets the specified keys to be the "context" keys which are used to determine
   which operations are appropriate for display in the right-click popup menu.

.. oe:function:: ContextSet

   .. oe:api::

      void ContextSet(const OEPropDB::OEKey &)
      void ContextSet(const std::string &prop)
      void ContextSet(const std::vector<OEPropDB::OEKey> &)

   Sets the specified key(s) to be the "context" keys which are used to determine
   which operations are appropriate for display in the right-click popup menu.

.. oe:function:: DefaultScopeGet

   .. oe:api::

      unsigned int DefaultScopeGet()

   Returns the default scope of operations.

.. oe:function:: DefaultScopeSet

   .. oe:api::

      void DefaultScopeSet(unsigned int scope)

   Sets the default scope of operations. Valid parameters are:
  
    * ActiveScope - operations are performed on the *active* / *focused* 
                    object
    * ActiveThenVisibleScope - operations are performed only on the *active* /
                               *focused* object; however, if no object has that
                               property, the operations are performed on the
                               *visible* objects
    * AllScope - operations are performed on all of the currently loaded 
                 objects
    * BestScope - allows the application to determine the current best scope
                  for operations based on the context of the operation
    * MarkedScope - operations are performed on all of the *marked* objects
    * ScratchScope - operations are performed on all of the objects that were
                     added to the *scratch* scope using the 
                     :oe:func:`ScratchInsert` and the
                     :oe:func:`ScratchSet` functions.
    * SelectedScope - operations are performed only on *selected* objects
    * VisibleScope - operations are performed on all of the *visible* objects

.. oe:function:: GetAllContextKeys

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetAllContextKeys()

   Returns all of the relevant keys of interest corresponding to the current
   state of the application. 

.. oe:function:: GetAtomsScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetAtomsScoped(unsigned int scope)

   Returns a list of all the atom keys in the specified scope.

.. oe:function:: GetBondsScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetBondsScoped(unsigned int scope)

   Returns a list of all the bond keys in the specified scope.

.. oe:function:: GetContoursScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetContoursScoped(unsigned int scope)

   Returns a list of all the contour keys in the specified scope.

.. oe:function:: GetGridsScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetGridsScoped(unsigned int scope)

   Returns a list of all the grid keys in the specified scope.

.. oe:function:: GetMarkedAtoms

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetMarkedAtoms()

   Returns a list of keys corresponding to all of the currently marked atoms.

.. oe:function:: GetMarkedAtomsScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetMarkedAtomsScoped(unsigned int scope)

   Returns a list of keys corresponding to all of the currently marked atoms
   that are also in the specified scope.

.. oe:function:: GetMarkedBonds

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetMarkedBonds()

   Returns a list of keys corresponding to all of the currently marked bonds.

.. oe:function:: GetMarkedBondsScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetMarkedBondsScoped(unsigned int scope)

   Returns a list of keys corresponding to all of the currently marked bonds
   that are also in the specified scope.

.. oe:function:: GetMarkedContours

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetMarkedContours()

   Returns a list of keys corresponding to all of the currently marked contours.

.. oe:function:: GetMarkedGrids

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetMarkedGrids()

   Returns a list of keys corresponding to all of the currently marked grids.

.. oe:function:: GetMarkedMolecules

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetMarkedMolecules()

   Returns a list of keys corresponding to all of the currently marked 
   molecules.

.. oe:function:: GetMarkedMonitors

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetMarkedMonitors()

   Returns a list of keys corresponding to all of the currently marked 
   monitors.

.. oe:function:: GetMarkedSurfaces

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetMarkedSurfaces()

   Returns a list of keys corresponding to all of the currently marked 
   surfaces.

.. oe:function:: GetMoleculesScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetMoleculesScoped(unsigned int scope)

   Returns a list of all the molecule keys in the specified scope.

.. oe:function:: GetScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetScoped(unsigned int scope)
      std::vector<OEPropDB::OEKey> GetScoped(unsigned int scope, unsigned int type)

   Returns a list of all the keys in the specified scope. If a *type* parameter
   is specified, it will return a list of all keys of that type in the specified 
   scope. The type parameter can be retrieved by calling the ``GetType`` method 
   on an ``OEKey`` object.

.. oe:function:: GetSelectedAtom

   .. oe:api::

      OEPropDB::OEKey GetSelectedAtom()

   Returns a key corresponding to a single selected atom. If multiple atoms are 
   currently selected, this is equivalent to returning the first entry in list
   returned by :oe:func:`GetSelectedAtoms`.

.. oe:function:: GetSelectedAtoms

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetSelectedAtoms()

   Returns a list of keys corresponding to the currently selected atoms.

.. oe:function:: GetSelectedBond

   .. oe:api::

      OEPropDB::OEKey GetSelectedBond()

   Returns a key corresponding to a single selected bond. If multiple atoms are 
   currently selected, this is equivalent to returning the first entry in list
   returned by :oe:func:`GetSelectedBonds`.

.. oe:function:: GetSelectedBonds

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetSelectedBonds()

   Returns a list of keys corresponding to the currently selected bonds.

.. oe:function:: GetSelectedContours

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetSelectedContours()

   Returns a list of keys corresponding to the currently selected contours.

.. oe:function:: GetSelectedGrids

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetSelectedGrids()

   Returns a list of keys corresponding to the currently selected grids.

.. oe:function:: GetSelectedMolecules

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetSelectedMolecules()

   Returns a list of keys corresponding to the currently selected molecules.

.. oe:function:: GetSelectedMonitors

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetSelectedMonitors()

   Returns a list of keys corresponding to the currently selected monitors.

.. oe:function:: GetSelectedSurfaces

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetSelectedSurfaces()

   Returns a list of keys corresponding to the currently selected surfaces.

.. oe:function:: GetSurfacesScoped

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetSurfacesScoped(unsigned int scope)

   Returns a list of all the surface keys in the specified scope.

.. oe:function:: GetVisibleAtoms

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetVisibleAtoms()

   Returns a list of all the visible atom keys.

.. oe:function:: GetVisibleBonds

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetVisibleBonds()

   Returns a list of all the visible bond keys.

.. oe:function:: GetVisibleContours

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetVisibleContours()

   Returns a list of all the visible contour keys.

.. oe:function:: GetVisibleGrids

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetVisibleGrids()

   Returns a list of all the visible grid keys.

.. oe:function:: GetVisibleIDs

   .. oe:api::

      std::vector<unsigned int> GetVisibleIDs()

   Returns a list of all the IDs for the current set of visible objects.

.. oe:function:: GetVisibleMolecules

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetVisibleMolecules()

   Returns a list of all the visible molecule keys.

.. oe:function:: GetVisibleMonitors

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetVisibleMonitors()

   Returns a list of all the visible monitor keys.

.. oe:function:: GetVisibleSurfaces

   .. oe:api::

      std::vector<OEPropDB::OEKey> GetVisibleSurfaces()

   Returns a list of all the visible surface keys.

.. oe:function:: IDGet

   .. oe:api::

      unsigned int IDGet(const OESystem::OEBase &)

   Returns the ID associated with the specified Python object.

.. oe:function:: IDTypeGet

   .. oe:api::

      std::string IDTypeGet(unsigned int)

   Returns the name of the object type associated with the specified ID.

.. oe:function:: IsActive

   .. oe:api::

      bool IsActive(const OEPropDB::OEKey &k)
      bool IsActive(unsigned int id, unsigned int conf=UINT_MAX)

   Returns whether or not the specified object (key or ID with optional 
   conformer index) is active/focused.

.. oe:function:: IsLocked

   .. oe:api::

      bool IsLocked(const OEPropDB::OEKey &k)
      bool IsLocked(unsigned int id, unsigned int conf=UINT_MAX)

   Returns whether or not the specified object (key or ID with optional
   conformer index) is locked.

.. oe:function:: IsMarked

   .. oe:api::

      bool IsMarked(const OEPropDB::OEKey &k)
      bool IsMarked(unsigned int id, unsigned int conf=UINT_MAX)

   Returns whether or not the specified object (key or ID with optional
   conformer index) is marked.

.. oe:function:: IsSelected

   .. oe:api::

      bool IsSelected(const OEPropDB::OEKey &k)
      bool IsSelected(unsigned int id, unsigned int conf=UINT_MAX)

   Returns whether or not the specified object (key or ID with optional
   conformer index) is selected.

.. oe:function:: IsTrulyVisible

   .. oe:api::

      bool IsTrulyVisible(const OEPropDB::OEKey &k)
      bool IsTrulyVisible(unsigned int id, unsigned int conf=UINT_MAX)

   Returns whether or not the specified object (key or ID with optional
   conformer index) is truly visible.

.. oe:function:: IsVisible

   .. oe:api::

      bool IsVisible(const OEPropDB::OEKey &k)
      bool IsVisible(unsigned int id, unsigned int conf=UINT_MAX)

   Returns whether or not the specified object (key or ID with optional
   conformer index) is visible.
   
.. oe:function:: Lock

   .. oe:api::

      void Lock(const std::string &k)
      void Lock(const OEPropDB::OEKey &k, bool state)
      void Lock(const std::vector<OEPropDB::OEKey> &keys, bool state)
      void Lock(unsigned int id, bool state, unsigned int conf=UINT_MAX)

   Sets the *locked* property on the specified object to the specified value
   (*state*). If a string value is passed to this function as opposed to an
   object specifier, the *locked* property will be set for all the objects 
   that satisfy the specified query. For more details on the query language,
   see the relevant chapter in the main VIDA manual.

.. oe:function:: LockScoped

   .. oe:api::

      void LockScoped(bool state, unsigned int scope)

   Sets the *locked* property to the specified value for all objects in the
   specified scope.

.. oe:function:: Mark

   .. oe:api::

      void Mark(const std::string &prop)
      void Mark(const OEPropDB::OEKey &k, bool state)
      void Mark(const std::vector<OEPropDB::OEKey> &keys, bool state)
      void Mark(unsigned int id, bool state, unsigned int conf=UINT_MAX)
      void Mark(const std::vector<OEPropDB::OEKey> &keys, bool state, 
                unsigned char action)

   Sets the *marked* property on the specified object to the specified value
   (*state*). If a string value is passed to this function as opposed to an
   object specifier, the *marked* property will be set for all the objects 
   that satisfy the specified query. For more details on the query language,
   see the relevant chapter in the main VIDA manual.

.. oe:function:: MarkScoped

   .. oe:api::

      void MarkScoped(bool state, unsigned int scope)

   Sets the *marked* property to the specified value for all objects in the
   specified scope.

.. oe:function:: MimicParentVisibilityGet

   .. oe:api::

      bool MimicParentVisibilityGet(const OEPropDB::OEKey &k)

   Returns whether or not the visibility of the specified object is controlled 
   by its parent's visibility.

.. oe:function:: MimicParentVisibilitySet

   .. oe:api::

      void MimicParentVisibilitySet(const OEPropDB::OEKey &k, bool mimic)
      void MimicParentVisibilitySet(const std::vector<OEPropDB::OEKey> &k, 
                                    bool mimic)

   Sets whether or not the visibility of the specified object(s) is controlled 
   by each individual's parent's visibility.

.. oe:function:: MimicParentVisibilitySetScoped

   .. oe:api::

      void MimicParentVisibilitySetScoped(const std::string &tag, bool mimic, 
                                          unsigned int scope = BestScope)

   Sets whether or not the visibility of a certain set of objects with the 
   specified scope is controlled by each individual's parent's visibility. The
   set of objects is determined by the presence or absence of the specified 
   *tag* on the molecule.
  
.. oe:function:: ScratchClear

   .. oe:api::

      void ScratchClear()

   This function clears the ScratchScope.

.. oe:function:: ScratchGet

   .. oe:api::

      std::vector<OEPropDB::OEKey> ScratchGet()

   Returns all of the keys currently in the ScratchScope.
  
.. oe:function:: ScratchInsert

   .. oe:api::

      void ScratchInsert(const OEPropDB::OEKey &)
      void ScratchInsert(const std::vector<OEPropDB::OEKey> &)

   This function adds a key to the ScratchScope.

.. oe:function:: ScratchSet

   .. oe:api::

      void ScratchSet(const std::string &prop)
      void ScratchSet(const OEPropDB::OEKey &)
      void ScratchSet(const std::vector<OEPropDB::OEKey> &)

   This function sets the contents of the ScratchScope.

.. oe:function:: Select

   .. oe:api::

      void Select(const std::string &prop)
      void Select(const OEPropDB::OEKey &k, bool state)
      void Select(const std::vector<OEPropDB::OEKey> &keys, bool state)
      void Select(unsigned int id, bool state, unsigned int conf=UINT_MAX)
      void Select(const std::vector<OEPropDB::OEKey> &keys, bool state, 
                  unsigned char action)

   This function selects objects according to the selection language.

.. oe:function:: SelectAllMolecules

   .. oe:api::

      void SelectAllMolecules()

   This function selects every molecule that is currently visible.

.. oe:function:: SelectByQuery

   .. oe:api::

      void SelectByQuery(const std::string &query, int action=0, 
                         unsigned int scope = BestScope)

   This function selects every molecule in the specified scope based on whether or 
   not it matches the specified substructure *query*. Valid query inputs include 
   SMILES, SMARTS, and IUPAC as well as common names. The IUPAC and common name to 
   structure conversion is performed by the Ogham toolkit.

.. oe:function:: SelectInvert

   .. oe:api::

      void SelectInvert()

   This function selects the currently visible, but not selected items, and deselects
   the visible and selected items.

.. oe:function:: SelectKeys

   .. oe:api::

      void SelectKeys(const std::vector<OEPropDB::OEKey> &atomsKeys)

   This function selects the objects corresponding to each of the keys specified 
   in the parameter list *keys*.

.. oe:function:: SelectOERID

   .. oe:api::

      void SelectOERID(unsigned int id, bool selected=true)

   This function sets the selected property on the object corresponding to the 
   specified *id*. The *selected* parameter specifies whether or not the object
   should either be selected or unselected.

.. oe:function:: SelectResidues

   .. oe:api::

      void SelectResidues(const std::vector<OEPropDB::OEKey> &keys, bool state)

   Set the selected state of the residues containing the specified atoms.

.. oe:function:: SelectScoped

   .. oe:api::

      void SelectScoped(bool state, unsigned int scope)

  Select or unselect (based on the *state* parameter) all the objects in the
  specified scope.

.. oe:function:: SelectWithin

   .. oe:api::

      void SelectWithin(float radius, bool selected)

   This function selects all molecule objects, including atoms and bonds,
   within the specified radius of the currently selected objects.

.. oe:function:: SelectWithout

   .. oe:api::

      void SelectWithout(float radius, bool selected)

   This function selects all molecule objects, including atoms and bonds,
   outside of the specified radii of the currently selected objects.

.. oe:function:: Subset

   .. oe:api::

      void Subset(const std::string &name, const std::string &sel)

   Creates a named subset that can be then used in the Select routine.

.. oe:function:: Visible

   .. oe:api::

      void Visible(const std::string &prop)
      void Visible(const OEPropDB::OEKey &k, bool state)
      void Visible(const std::vector<OEPropDB::OEKey> &keys, bool state)
      void Visible(unsigned int id, bool state, unsigned int conf=UINT_MAX)
      void Visible(const std::vector<OEPropDB::OEKey> &keys, bool state, 
                   unsigned char action)
      bool Visible(const std::vector<unsigned int> &ids, bool visible, 
                   unsigned int conf=UINT_MAX)

   This function sets the keys that pass the specified criteria to be visible.

.. oe:function:: VisibleScoped

   .. oe:api::

      void VisibleScoped(bool state, unsigned int scope)
   
   Sets the visibility of all the objects in the specified scope based on the
   *state* parameter.

.. oe:function:: VisualizeCommandScopeGet

   .. oe:api::

      unsigned int VisualizeCommandScopeGet()

   Reserved for future expansion.

.. oe:function:: VisualizeCommandScopeSet

   .. oe:api::

      void VisualizeCommandScopeSet(unsigned int scope)

   Reserved for future expansion.



.. |product|        replace:: VIDA
.. |product's|      replace:: VIDA's
.. |settings_file|  replace:: *VIDA.ini*
.. |product_ext_url| replace:: VIDA_EXTENSIONS_URL
.. |xp_user_dir|    replace:: ``C:\Documents and Settings\USERNAME\Application Data\OpenEye\VIDA\5.0``
.. |vista_user_dir| replace:: ``C:\Users\USERNAME\AppData\Local\OpenEye\VIDA\5.0``
.. |osx_user_dir|   replace:: ``/Users/USERNAME/Library/OpenEye/VIDA/5.0``
.. |linux_user_dir| replace:: ``~USERNAME/.OpenEye/VIDA/5.0``
 


Data Analysis Functions
***********************

The functions detailed in this section provide access to the data analysis
and spreadsheet functionality in VIDA. An important distinction should
be made in that the "Datatable" functions refer to internal data collections
while the "Spreadsheet" functions refer to the actual tabular views of the
associated data that actually appear in the Spreadsheet display.

.. oe:function:: DataAdd

   .. code::

      void DataAdd(const OEPropDB::OEKey &key, const std::string &str, 
                   const std::string &data)

   Adds a piece of data to the object specified by *key*. If a column in the
   spreadsheet does not already exist for this data type, it will be added.

.. oe:function:: DataGetDB

   .. code::

      VFDataBase *DataGetDB()

   Return the VDDataBase object.

.. oe:function:: DataGetTable

   .. code::

      VFDataTable *DataGetTable(const std::string &name, bool throwError=true)

   Return the list of all internal databases.

.. oe:function:: DatatableAddColumn

   .. code::

      void DatatableAddColumn(std::string datatable, std::string columnName, 
                              bool genericData=false)

   Add a column to the specified data table with the specified name. If a column
   with the specified name already exists, this call will be ignored.

.. oe:function:: DatatableCommitChanges

   .. code::

      void DatatableCommitChanges(const std::string &datatable)

   Commits any outstanding changes to the internal database.

.. oe:function:: DatatableCurrentGet

   .. code::

      std::string DatatableCurrentGet()

   Returns the name of the current data table (e.g. 'Molecules').

.. oe:function:: DatatableCurrentSet

   .. code::

      bool DatatableCurrentSet(const std::string &datatable)

   Sets the current data table.

.. oe:function:: DatatableData

   .. code::

      std::string DatatableData(const std::string &datatable, unsigned int row, 
                                std::string header)

   Returns the string representation of the data in the specified data table at
   the specified row and column.

.. oe:function:: DatatableDeleteColumn

   .. code::

      void DatatableDeleteColumn(const std::string &datatable, 
                                 const std::string &name)

   Delete the specified column from the specified data table.

.. oe:function:: DatatableEditableGet

   .. code::

      bool DatatableEditableGet(const std::string &ss)

   Returns whether or not the specified data table is editable.

.. oe:function:: DatatableEditableSet

   .. code::

      void DatatableEditableSet(const std::string &ss, bool val)

   Sets whether or not the specified data table is editable.

.. oe:function:: DatatableFilter

   .. code::

      void DatatableFilter(const std::string &datatable, const std::string &filter, 
                           const std::string &name, bool staticView=true, 
                           bool permaFilter=false)

      void DatatableFilter(const std::string &datatable, const OEDataFilter &filter, 
                           const std::string &name, bool staticView=true, 
                           bool permaFilter=false)

   Creates a new data table view with the specified name from the specified data
   table using the specified filter. The filter is an arbitrary Python 
   expression that is applied to every row in the source data table to determine
   whether or not it should be included in the filtered view.
  
   The filter expression may assume that a local variable ``ROW`` is set to the
   current row number being evaluated. An example appears below:
  
  .. code::

    
    int(DatatableData(DatatableCurrent(), ROW, foo)) < 400
    
   The example shows an example expression where the string representation of 
   the data in the current data table (which may not necessarily be the 
   specified datatable) at row ``ROW`` and in column ``foo`` is converted to an
   integer and compared with the value 400. If this expression is ``True`` for
   the row being tested, it will be included in the filtered view, otherwise it
   will not be included.

.. oe:function:: DatatableFromList

   .. code::

      void DatatableFromList(unsigned int listid, const std::string &name)

   Creates a filtered data table with the specified name with row entries for
   each object in the specified list. If the specified name already exists, 
   a new name will be used (e.g. *name* --> *name1*, *name2*, and so on).

.. oe:function:: DatatableGetColumn

   .. code::

      std::vector<std::string> DatatableGetColumn(const std::string &datatable, 
                                                  unsigned int index)

      std::vector<std::string> DatatableGetColumn(const std::string &datatable, 
                                                  const std::string &name)

   Returns a list of string representations for each entry in the specified column
   in the specified data table.

.. oe:function:: DatatableGetCurrentRow

   .. code::

      int DatatableGetCurrentRow(std::string datatable)
      
   Returns the row index for the first active or selected row in the specified 
   data table.

.. oe:function:: DatatableGetDatatables

   .. code::

      std::vector<std::string> DatatableGetDatatables()

   Returns a list of the names of all the available datatables.

.. oe:function:: DatatableGetImageStreamAtRow

   .. code::

      bool DatatableGetImageStreamAtRow(const std::string &datatable, 
                                        const std::string &filename, int row, 
                                        int width=256, int height=256)

   Write an image file to the file specified by *filename* for the datatable 
   named *datatable* at the row specified by *row*.  The size of the image is 
   specified by *width* and *height*.

.. oe:function:: DatatableGetKeys

   .. code::

      std::vector<OEKey> DatatableGetKeys(const std::string &datatable)

   Returns a list of keys for the database specified by *datatable*.
   The keys are returned in the current datatable sort order and are
   consistent with the ordering from the call to DatatableGetColumn.

.. oe:function:: DatatableGetNumRows

   .. code::

      int DatatableGetNumRows(std::string datatable)

   Return the number of rows for the specified datatable.

.. oe:function:: DatatableHeaders

   .. code::

      std::vector<std::string> DatatableHeaders(const std::string &datatable)

   Return a list of all the names of all the headers for the specified 
   datatable.

.. oe:function:: DatatableLingoSimSort

   .. code::

      bool DatatableLingoSimSort(const std::string &spreadsheet, unsigned int row)

   Sorts the specified datatable according to Lingo similarity to the molecule
   contained in the specified row.

.. oe:function:: DatatableMolNumberFunction

   .. code::

      double DatatableMolNumberFunction(const std::string &datatable, int row, 
                                        const std::string &func)

   Calculates molecular data that returns a numeric value. *datatable* 
   identifies the datatable containing the molecule and row is the datatable 
   row with the molecule.

   The function *func* to compute is one of:

    * "mw" Molecular weight.

    * "Num Atoms" Number of atoms in the molecule.

    * "Num Bonds" number of bonds in the molecule.

    * "Carbon-Hetero ratio" the ratio of carbons to hetero atoms in the molecule.
                            Returns -1 if there are no carbons.

    * "Energy" The molecular energy of the molecule as specified in the input file.

    * "Actual Charge" The sum of the partial charges on all atoms as specified in the input file.

    * "Formal Charge" The sum of the formal charges on all atoms.

    * "Halide Count" The number of halogen atoms in the molecule.

    * "Num Carbons" The number of carbon atoms in the molecule.

    * "Num Formal Charges" The number of more atoms with a specified formal charge.

    * "Num Heavy Atoms" The number of heavy atoms (non hydrogen) in the molecule.

    * "Num Hetero Atoms" The number of hetero atoms in the molecule.

    * "Num Hydrogens" The number of hydrogen atoms in the molecule.

    * "Num Rigid Bonds" The number of rigid bonds in the molecule.

    * "Nom Rotatable Bonds" The number of rotatable bonds in the molecule.

    * "Num Chiral Atoms" returns the number of chiral atoms in the molecule.

    * "Num Chiral Bonds" returns the number of chiral bonds in the molecule.

.. oe:function:: DatatableMolStringFunction

   .. code::

      std::string DatatableMolStringFunction(const std::string &datatable, int row, 
                                             const std::string &func)

   Calculates molecular data that returns a string value. *datatable* identifies 
   the datatable containing the molecule and row is the datatable row with the 
   molecule.

   The function *func* to compute is one of:
   
    * "molformula" the molecular formula for the molecule.

.. oe:function:: DatatableNumRows

   .. code::

      int DatatableNumRows(std::string datatable)

   Return the number of rows for the datatable named *datatable*.

.. oe:function:: DatatableSetData

   .. code::

      void DatatableSetData(const std::string &datatable, unsigned int row, 
                            std::string header, std::string value, bool update=true)

   Set the cell data for the datatable named *datatable* at *row* for the column 
   named *header* to the string value *value*.  

   If update is True, immediately update the datatable.  Set this to False if 
   you are updating a bunch of data and then call 
   DatatableUpdateContents on
   this datatable.

.. oe:function:: DatatableSetExpression

   .. code::

      void DatatableSetExpression(const std::string &datatable, 
                                  const std::string &col, const std::string &expr)

   A datatable expression defines an arbitrary piece of python code to call
   that generates data to be displayed in the datatable.

   This function creates a new column named *col* for the specified datatable
   using the function defined by *expr*.

   This expression may assume that a local variable *ROW* is assigned to the
   row currently being evaluated.  e.g. 

   `DatatableData(DatatableCurrent(), ROW, foo)`

   returns the string representation of the data in column *foo* for the current
   datatable which, for this function, is always *datatable*.

.. oe:function:: DatatableSetRowData

   .. code::

      void DatatableSetRowData(const std::string &datatable, unsigned int row, 
                               std::vector<std::string> headers, 
                               std::vector<std::string> rows, bool update=true)

   Set data in the datatable named *datatable*.  *row* is the row index to set.  
   *headers* defines the names of the columns to set and *rows* is the string 
   representation of the data.

   **Note**: headers[i] should be the name of the column for row[i].

   *The update parameter is no longer used and is kept for backwards compatibility.*

.. oe:function:: SpreadsheetAddColumn

   .. code::

      void SpreadsheetAddColumn(std::string spreadsheet, std::string column, 
                                bool genericData=false)

   Add a column to spreadsheet *spreadsheet* with the name *columnName*.
   If *columnName* already exists in the spreadsheet, it will be ignored.

   For the "Atoms" and "Residues" spreadsheets, only certain column names are
   allowed, and the values in these columns cannot be changed.  

   For the "Atoms" spreadsheet, the valid column names are:

   - x
   - y
   - z
   - Radius
   - Element
   - Residue_Idx
   - Name
   - oe_atom_Formal_Charge
   - oe_atom_Partial_Charge
   - oe_atom_Idx
   - oe_atom_Map_Idx
   - oe_atom_Isotope
   - oe_atom_Hyb
   - oe_atom_Implicit_H_Count
   - oe_atom_Explicit_H_Count
   - oe_atom_Int_Type
   - oe_atom_Type
   - oe_atom_Aromatic
   - oe_atom_Chiral
   - oe_atom_In_Ring
   - oe_residue_Name
   - oe_residue_Occupancy
   - oe_residue_BFactor
   - oe_residue_Number
   - oe_residue_Serial_Number
   - oe_residue_Model_Number
   - oe_residue_Fragment_Number
   - oe_residue_Secondary_Structure
   - oe_residue_Alternate_Location
   - oe_residue_Chain_ID
   - oe_residue_IsHetAtom
 
   The *oe_residue_* and *oe_atom_* prefixes are not displayed in the spreadsheet
   headers, and are omitted when referring to these columns in other 
   functions, such as SpreadsheetData and SpreadsheetRemoveColumn.

   For the "Residues" spreadsheet, the valid column names are:

   - Residue
   - Average BFactor
   - Min Occupancy
   - Max Occupancy
   - Alt Group
   - Num AltConfs
   

.. oe:function:: SpreadsheetColumnColorerSet

   .. code::

      void SpreadsheetColumnColorerSet(const std::string &spreadsheet, 
                                       const std::string &column, 
                                       const std::string &colorer, double min, 
                                       double max)

   Sets a colorer for the specified column in the specified spreadsheet. 
   Valid values for the *colorer* parameter include:
   
   * "redtoblue"
   * "bluetored"
   * "rainbow"
   * "reverse rainbow"
   * "redyellowblue"
   * "greytogreen"

.. oe:function:: SpreadsheetColumnController

   .. code::

      void SpreadsheetColumnController()

   Open the spreadsheet column controller dialog.  The column controls
   allows controlling the visibility and other aspects for the
   current spreadsheets column.

.. oe:function:: SpreadsheetColumnFontGet

   .. code::

      std::string SpreadsheetColumnFontGet(const std::string &spreadsheet, 
                                           const std::string &column)

   Returns the font to be used when rendering text in the specified column of
   the specified spreadsheet.

.. oe:function:: SpreadsheetColumnFontSet

   .. code::

      void SpreadsheetColumnFontSet(const std::string &spreadsheet, 
                                    const std::string &column, 
                                    const std::string &font)

   Sets the font to be used when rendering text in the specified column of the
   specified spreadsheet.

.. oe:function:: SpreadsheetColumnReadonly

   .. code::

      bool SpreadsheetColumnReadonly(std::string spreadsheet, unsigned int col)
      bool SpreadsheetColumnReadonly(std::string spreadsheet, unsigned int col, 
                                     bool readonly)

   Set a spreadsheet column to be read-only.
 
   Without a readOnly value, returns the current readonly state for column *col* in 
   *spreadsheet*.

   With a readOnly specified, column *col* in the spreadsheet named *spreadsheet* is
   set to value set by readOnly.

.. oe:function:: SpreadsheetColumnSigFigGet

   .. code::

      int SpreadsheetColumnSigFigGet(const std::string &spreadsheet, 
                                     const std::string &column)

   Returns the number of significant figures used to display numerical values
   data in the specified column.

.. oe:function:: SpreadsheetColumnSigFigSet

   .. code::

      void SpreadsheetColumnSigFigSet(const std::string &spreadsheet, 
                                      const std::string &column, int digits)

   Sets the number of significant figures used to display numerical values
   data in the specified column.

.. oe:function:: SpreadsheetCommitChanges

   .. code::

      void SpreadsheetCommitChanges(const std::string &spreadsheet)

   Commit any unsaved changes to the spreadsheet named *spreadsheet*.  

   Normally, this is done automatically behind the scenes but sometimes is 
   necessary to keep the data in the spreadsheet synchronized with the 
   molecules and data in the repository.

.. oe:function:: SpreadsheetCopy

   .. code::

      std::string SpreadsheetCopy(const std::string &spreadsheet)

   Copies to the clipboard and returns the currently selected set of cells in 
   the specified spreadsheet. 

.. oe:function:: SpreadsheetCreateColumnExpression

   .. code::

      void SpreadsheetCreateColumnExpression()

   Open the dialog to create a new column expression for the current spreadsheet.
   A column expression is a user-defined function that populates a column with
   arbitrary data.

.. oe:function:: SpreadsheetCreateFilter

   .. code::

      void SpreadsheetCreateFilter()

   Open the dialog to generate a new view of the spreadsheet with all rows
   filtered by an arbitrary python expression.

.. oe:function:: SpreadsheetCurrentGet

   .. code::

      std::string SpreadsheetCurrentGet()

   Returns the name of the current spreadsheet. e.g. 'Molecules'.

.. oe:function:: SpreadsheetCurrentSet

   .. code::

      bool SpreadsheetCurrentSet(const std::string &spreadsheet)

   Sets the current spreadsheet.

.. oe:function:: SpreadsheetData

   .. code::

      std::string SpreadsheetData(const std::string &spreadsheet, unsigned int row, 
                                  std::string header)

   Return the string representation of the data in the spreadsheet named *spreadsheet* for
   the row *row* and the column named *header*.

.. oe:function:: SpreadsheetDeleteColumn

   .. code::

      void SpreadsheetDeleteColumn(const std::string &column)

   Delete the column named *column*.  Note that this deletes *column* from all 
   spreadsheets.

.. oe:function:: SpreadsheetEditableGet

   .. code::

      bool SpreadsheetEditableGet(const std::string &ss)

   Returns True if *spreadsheet* is editable.

.. oe:function:: SpreadsheetEditableSet

   .. code::

      void SpreadsheetEditableSet(const std::string &ss, bool val)

   Sets *spreadsheet* to be editable if *val* is True, otherwise sets *spreadsheet* to be read-only.

.. oe:function:: SpreadsheetFilter

   .. code::

      void SpreadsheetFilter(const std::string &spreadsheet, std::string filter, 
                             std::string name, bool staticView)
      void SpreadsheetFilter(const std::string &spreadsheet, const OEDataFilter &p, 
                             const std::string &name, bool staticview, 
                             bool permaFilter=false)

   Create a new spreadsheet view from the spreadsheet named *spreadsheet* using the filter
   defined in *filter*.  The new view is named *name*.  *filter* is an arbitrary
   python expression that is applied to every row in the spreadsheet.

   This expression may assume that a local variable *ROW* is assigned to the
   row currently being evaluated.  e.g. 

   SpreadsheetData(SpreadSheetCurrent(), ROW, foo)

   returns the string representation of the data in column foo for the current
   spreadsheet.  Note: the current spreadsheet may not be *spreadsheet*.

.. oe:function:: SpreadsheetFromList

   .. code::

      void SpreadsheetFromList(unsigned int listid, const std::string &name)

   Generate a filtered spreadsheet with name *name* from the list *listid*.

   If *name* is already in the spreadsheet, it will be renamed name1, name2 and
   so on.

.. oe:function:: SpreadsheetGetColumn

   .. code::

      std::vector<std::string> SpreadsheetGetColumn(const std::string &spreadsheet, 
                                                    unsigned int index)
      std::vector<std::string> SpreadsheetGetColumn(const std::string &spreadsheet, 
                                                    const std::string &name)

   Returns string representations of the entire column for the spreadsheet named 
   *spreadsheet* for column *name* or, alternatively, for column index by *index*.

.. oe:function:: SpreadsheetGetCurrentRow

   .. code::

      int SpreadsheetGetCurrentRow(std::string spreadsheet)

   Returns the row index for the first active or selected row for the spreadsheet named *spreadsheet*.

.. oe:function:: SpreadsheetGetIDForRow

   .. code::

      unsigned int SpreadsheetGetIDForRow(std::string spreadsheet, unsigned int row)

   Returns the repository id for the first active or selected row for the spreadsheet named *spreadsheet*.

.. oe:function:: SpreadsheetGetImageStreamAtRow

   .. code::

      bool SpreadsheetGetImageStreamAtRow(const std::string &spreadsheet, 
                                          const std::string &filename, int row, 
                                          int width=256, int height=256)

   Write an image file to the file specified by *filename* for the spreadsheet named *spreadsheet* at
   the row specified by *row*.  The size of the image is specified by *width* and *height*.

.. oe:function:: SpreadsheetGetKeyForRow

   .. code::

      OEPropDB::OEKey SpreadsheetGetKeyForRow(std::string spreadsheet, 
                                              unsigned int row)

   Returns the OEKey value for the first active or selected row for the spreadsheet named *spreadsheet*.

.. oe:function:: SpreadsheetGetNumRows

   .. code::

      int SpreadsheetGetNumRows(std::string spreadsheet)

   Return the number of rows for the spreadsheet named *spreadsheet*.

.. oe:function:: SpreadsheetGetRowForKey

   .. code::

      unsigned int SpreadsheetGetRowForKey(std::string spreadsheet, OEPropDB::OEKey)

   Returns the row that is generated from OEKey *key*.  Returns "4294967295L" if *key* is not in the spreadsheet.

.. oe:function:: SpreadsheetGetSpreadsheets

   .. code::

      std::vector<std::string> SpreadsheetGetSpreadsheets()

   Return a list of the names for all the currently available spreadsheets.

.. oe:function:: SpreadsheetHeaders

   .. code::

      std::vector<std::string> SpreadsheetHeaders(const std::string &spreadsheet)

   Return a list of all the names of all the headers for the spreadsheet named *spreadsheet*.

.. oe:function:: SpreadsheetHideColumn

   .. code::

      void SpreadsheetHideColumn(const std::string &spreadsheet, 
                                 const std::string &name)

   Hide the column named *name* for the spreadsheet named *spreadsheet*.

.. oe:function:: SpreadsheetHideTab

   .. code::

      bool SpreadsheetHideTab(std::string name)

   Hide the named spreadsheet from the spreadsheet view.

.. oe:function:: SpreadsheetImport

   .. code::

      int SpreadsheetImport(const VFSpreadSplitter &splitter, 
                            const std::string &filename, 
                            unsigned int matchBy=ImportSpreadsheet::ImportByOrder, 
                            const std::string &matchList="", 
                            unsigned int importBy=ImportSpreadsheet::ImportAsIs, 
                            const std::string &importColumnOrFunction="")

   Imports the specified file into the spreadsheet.

.. oe:function:: SpreadsheetLingoSimSort

   .. code::

      void SpreadsheetLingoSimSort(const std::string &spreadsheet, unsigned int row)

   Sorts the specified spreadsheet according to Lingo similarity to the 
   molecule in the specified row.

.. oe:function:: SpreadsheetLoadFilter

   .. code::

      void SpreadsheetLoadFilter(const std::string &spreadsheet, 
                                 const OEDataFilter &filter)
      void SpreadsheetLoadFilter(const std::string &spreadsheet, 
                                 const OEDataFilter &filter, bool wasStatic, 
                                 bool isStatic)

   Creates a new spreadsheet using the specified filter.

.. oe:function:: SpreadsheetMolNumberFunction

   .. code::

      double SpreadsheetMolNumberFunction(const std::string &spreadsheet, int row, 
                                          const std::string &func)

   Calculates molecular data that returns a numeric value.

   *spreadsheet* identifies the spreadsheet containing the molecule and row is the
   spreadsheet row with the molecule.

   The function *func* to compute is one of:

    * "mw" Molecular weight.

    * "Num Atoms" Number of atoms in the molecule.

    * "Num Bonds" number of bonds in the molecule.

    * "Carbon-Hetero ratio" the ratio of carbons to hetero atoms in the molecule.
                            Returns -1 if there are no carbons.

    * "Energy" The molecular energy of the molecule as specified in the input file.

    * "Actual Charge" The sum of the partial charges on all atoms as specified in the input file.

    * "Formal Charge" The sum of the formal charges on all atoms.

    * "Halide Count" The number of halogen atoms in the molecule.

    * "Num Carbons" The number of carbon atoms in the molecule.

    * "Num Formal Charges" The number of more atoms with a specified formal charge.

    * "Num Heavy Atoms" The number of heavy atoms (non hydrogen) in the molecule.

    * "Num Hetero Atoms" The number of hetero atoms in the molecule.

    * "Num Hydrogens" The number of hydrogen atoms in the molecule.

    * "Num Rigid Bonds" The number of rigid bonds in the molecule.

    * "Nom Rotatable Bonds" The number of rotatable bonds in the molecule.

    * "Num Chiral Atoms" returns the number of chiral atoms in the molecule.

    * "Num Chiral Bonds" returns the number of chiral bonds in the molecule.

.. oe:function:: SpreadsheetMolStringFunction

   .. code::

      std::string SpreadsheetMolStringFunction(const std::string &spreadsheet, 
                                               int row, const std::string &func)

   Calculate molecular data that returns a string value.

   *spreadsheet* identifies the spreadsheet containing the molecule and row is the
   spreadsheet row with the molecule.

   The function *func* to compute is one of:
   
    * 'molformula' the molecular formula for the molecule.

.. oe:function:: SpreadsheetMoveColumn

   .. code::

      void SpreadsheetMoveColumn(const std::string &spreadsheet, 
                                 const std::string &columnName, int position)

   Moves the specified column to the specified position.

.. oe:function:: SpreadsheetNumRows

   .. code::

      int SpreadsheetNumRows(std::string spreadsheet)

   Return the number of rows for the spreadsheet named *spreadsheet*.

.. oe:function:: SpreadsheetPromptColumnExpression

   .. code::

      std::string SpreadsheetPromptColumnExpression()

   This function opens a dialog and returns the expression to evaluate to add the specified column expression.

.. oe:function:: SpreadsheetPromptExport

   .. code::

      std::string SpreadsheetPromptExport(const std::string &filename)

   This function opens a dialog and returns the expression to export the specified spreadsheet and columns.

.. oe:function:: SpreadsheetPromptFilter

   .. code::

      std::string SpreadsheetPromptFilter()

   This function opens a dialog and returns the expression to evaluate to filter the specified spreadsheet.

.. oe:function:: SpreadsheetPromptFormat

   .. code::

      std::string SpreadsheetPromptFormat()

   This function opens a dialog which allows the user to specify the formatting 
   of the spreadsheet.

.. oe:function:: SpreadsheetPromptGraphemeOpts

   .. code::

      std::string SpreadsheetPromptGraphemeOpts()

   This function opens a dialog which allows the user to specify how the 2D depiction is rendered using
   OpenEye's **Grapheme** toolkit to apply a property map of computed properties or even user defined properties
   which are tagged to the atoms using generic data.

.. oe:function:: SpreadsheetPromptImport

   .. code::

      std::string SpreadsheetPromptImport(const std::string &filename)

   This function opens a dialog and returns the expression to import spreadsheet *filename*.

.. oe:function:: SpreadsheetPromptSort

   .. code::

      std::string SpreadsheetPromptSort()

   This function opens a dialog and returns the expression to evaluate to sort the specified spreadsheet and columns.

.. oe:function:: SpreadsheetRemoveTab

   .. code::

      bool SpreadsheetRemoveTab(std::string name)

   Remove the spreadsheet with name *name*.  The base "Molecules" spreadsheet 
   cannot be removed.

.. oe:function:: SpreadsheetRowHeightGet

   .. code::

  
      int SpreadsheetRowHeightGet(const std::string &spreadsheet)

   Returns the row height for the specified spreadsheet.

.. oe:function:: SpreadsheetRowHeightSet

   .. code::

   
      void SpreadsheetRowHeightSet(const std::string &spreadsheet, int height)

   Sets the default row height for the specified spreadsheet.

.. oe:function:: SpreadsheetSetData

   .. code::

      void SpreadsheetSetData(const std::string &spreadsheet, unsigned int row, 
                              std::string header, std::string value, bool update=true)

   Set the cell data for the spreadsheet named *spreadsheet* at *row* for the column named
   *header* to the string value *value*.  

   If update is true, immediately update the spreadsheet.  Set this to false if you
   are updating a bunch of data and then call
   :oe:func:`SpreadsheetUpdateContents` on the
   spreadsheet.

.. oe:function:: SpreadsheetSetExpression

   .. code::

      void SpreadsheetSetExpression(const std::string &spreadsheet, 
                                    const std::string &col, const std::string &expr)

   A spreadsheet expression defines an arbitrary piece of python code to call
   that generates data to be displayed in the spreadsheet.

   SpreadsheetSetExpression creates a new column named *col* for the spreadsheet
   named *spreadsheet* using the function defined by *expr*.

   This expression may assume that a local variable *ROW* is assigned to the
   row currently being evaluated.  e.g. 

   SpreadsheetData(SpreadSheetCurrent(), ROW, foo)

   returns the string representation of the data in column *foo* for the current
   spreadsheet which, for this function, is always *spreadsheet*.

.. oe:function:: SpreadsheetSetRowData

   .. code::

      void SpreadsheetSetRowData(const std::string &spreadsheet, unsigned int row, 
                                 std::vector<std::string> headers, 
                                 std::vector<std::string> rows, bool update=true)

   Set data in the spreadsheet named *spreadsheet*.  *row* is the row index to set.  *headers* defines
   the names of the columns to set and *rows* is the string representation of the data.

   **Note**: headers[i] should be the name of the column for row[i].

   If update is true, immediately update the spreadsheet.  Set this to false if you
   are updating a bunch of data and then call SpreadsheetUpdateContents(ss).

.. oe:function:: SpreadsheetShowAllColumns

   .. code::

      void SpreadsheetShowAllColumns(const std::string &spreadsheet)

   Make all columns visible for the spreadsheet named *spreadsheet*.

.. oe:function:: SpreadsheetShowAllTabs

   .. code::

      void SpreadsheetShowAllTabs()

   Make all spreadsheets visible.

.. oe:function:: SpreadsheetShowColumn

   .. code::

      void SpreadsheetShowColumn(const std::string &spreadsheet, int section, 
                                 bool visible=true)
      void SpreadsheetShowColumn(const std::string &spreadsheet, 
                                 const std::string &name, bool visible=true)

   Make column *name* visible for the spreadsheet named *spreadsheet*.

.. oe:function:: SpreadsheetShowStats

   .. code::

      void SpreadsheetShowStats(const std::string &spreadsheet, bool show)

   If *show* is true, show the column statistics for the spreadsheet named *spreadsheet*.
   Otherwise, hide the statistics.

.. oe:function:: SpreadsheetShowStatsGet

   .. code::

      bool SpreadsheetShowStatsGet(const std::string &spreadsheet)

   Returns True if *spreadsheets* has the statistics window shown, False otherwise.

.. oe:function:: SpreadsheetShowStatsSet

   .. code::

      void SpreadsheetShowStatsSet(const std::string &spreadsheet, bool show)

   If *show* is True, the statistics window for *spreadsheet* is shown.  Otherwise it is hidden.

.. oe:function:: SpreadsheetShowTab

   .. code::

      bool SpreadsheetShowTab(std::string name)

   Ensure that *spreadsheet* is shown as a spreadsheet selection in the spreadsheet window.

.. oe:function:: SpreadsheetSort

   .. code::

      void SpreadsheetSort(const std::string &spreadsheet, 
                           const std::vector<std::string> &columns, 
                           const std::vector<int> &directions, 
                           bool moveToFirst=true)

   Sort *spreadsheet* by the specified columns and directions.  If a direction is 1 then the column is
   ascending, if a direction is 2 the column is descending.

   Example::

       SpreadsheetSort( "Molecules", ["target", "IC50"], [1,2] )

       target | IC50
       cox2   | 1.60
       cox2   | 1.40
       cox1   | 1.80
       cox1   | 1.67

       If *moveToFirst* is True then the sorted columns will be placed first in the spreadsheet.

       This would sort the molecules by target ascending and then by IC50 descending



.. |product|        replace:: VIDA
.. |product's|      replace:: VIDA's
.. |settings_file|  replace:: *VIDA.ini*
.. |product_ext_url| replace:: VIDA_EXTENSIONS_URL
.. |xp_user_dir|    replace:: ``C:\Documents and Settings\USERNAME\Application Data\OpenEye\VIDA\5.0``
.. |vista_user_dir| replace:: ``C:\Users\USERNAME\AppData\Local\OpenEye\VIDA\5.0``
.. |osx_user_dir|   replace:: ``/Users/USERNAME/Library/OpenEye/VIDA/5.0``
.. |linux_user_dir| replace:: ``~USERNAME/.OpenEye/VIDA/5.0``
 


User Interface Functions
************************

The functions detailed in this section provide access to information about and
enable customization of the VIDA user interface.

.. oe:function:: AppComponentNameGet

   .. code::

      std::string AppComponentNameGet()

   Returns the name of which VIDA component currently has the mouse focus.

.. oe:function:: AppComponentNameSet

   .. code::

      void AppComponentNameSet(const std::string &name)

   Stores the name of which VIDA component currently has the mouse focus.
   This function is called internally whenever the mouse focus changes to a new
   widget within the application. This is primarily intended for internal use 
   and as such should not be called.

.. oe:function:: AppGeometryGet

   .. code::

      std::vector<unsigned int> AppGeometryGet()

   Returns a list of four unsigned integers corresponding to the width, height,
   x and y positions of the application.

.. oe:function:: AppGeometrySet

   .. code::

      std::vector<unsigned int> AppGeometrySet( const std::vector<unsigned int> &geom )
      std::vector<unsigned int> AppGeometrySet( unsigned int width, 
                                                unsigned int height, 
                                                unsigned int x, 
                                                unsigned int y, 
                                                unsigned int mainx ,
                                                unsigned int mainy )

   Sets the width, height, x position, y position, central widget width, and 
   central widget height of the application.

.. oe:function:: AppGlobalFontGet

   .. code::

      std::string AppGlobalFontGet()

   Returns the current global font used in the application.

.. oe:function:: AppGlobalFontSet

   .. code::

      void AppGlobalFontSet(const std::string &font)

   Sets the global font to be used in the application.

.. oe:function:: AppLayoutGet

   .. code::

      std::string AppLayoutGet()

   Returns a hexadecimal encoded string representation of the current layout.

.. oe:function:: AppLayoutSet

   .. code::

      std::string AppLayoutSet(const std::string &geom)

   Sets the current layout of the application based on the hexadecimal encoded 
   layout specified by ``geom``. Ordinarily this function should not need to be
   called by the user; however, in the event that it is called, the input to 
   this function should always be the return value from a previous call to 
   :oe:func:`AppLayoutGet`.

.. oe:function:: AppLayoutToIcon

   .. code::

      std::vector<std::string> AppLayoutToIcon(unsigned int width  = 24, 
                                               unsigned int height = 24 )

   Returns a cartoon representation of the current layout as an image of size
   ``width`` and ``height``. The image is returned in XPM format.

.. oe:function:: AppMainWindowGet

   .. code::

      std::string AppMainWindowGet()

   Returns the name of the current main window.

.. oe:function:: AppMainWindowSet

   .. code::

      std::string AppMainWindowSet(const std::string &mainWindow)

   Sets the current main window. The name of the desired main window is the 
   input to this function.

.. oe:function:: AppMovableWindowsGet

   .. code::

      bool AppMovableWindowsGet()

   Returns whether or not the layout of the individual windows in the
   application can be changed by clicking and dragging the window to the desired
   location.

.. oe:function:: AppMovableWindowsSet

   .. code::

      bool AppMovableWindowsSet(bool)

   Sets whether or not the layout of the individual windows in the application
   can be changed by clicking and dragging the window to the desired location.

.. oe:function:: AppPerspectiveSet

   .. code::

      std::string AppPerspectiveSet(const std::string &perspective)

   Sets the current layout of the application based on the hexadecimal encoded 
   layout specified by ``perspective`` while maintaining the current geometry
   (width, height, x and y positions). Ordinarily this function should not need
   to be called by the user; however, in the event that it is called, the input
   to this function should always be the return value of a previous call to 
   :oe:func:`AppLayoutGet`.

.. oe:function:: AppRecordWindowEventsGet

   .. code::

      bool AppRecordWindowEventsGet()

   Returns whether or not window events are currently being recorded in the
   application history.

.. oe:function:: AppRecordWindowEventsSet

   .. code::

      bool AppRecordWindowEventsSet(bool record)

   Sets whether or not window events are recorded in the application history.

.. oe:function:: AppShowGet

   .. code::

      std::string AppShowGet()

   Returns the display status of the application. Potential return values are:
  
    * "normal"
    * "minimized"
    * "maximized"
    * "fullscreen"

.. oe:function:: AppShowMenuBarGet

   .. code::

      bool AppShowMenuBarGet()
      
   Returns whether or not the main menubar is currently visible.

.. oe:function:: AppShowMenuBarSet

   .. code::

      void AppShowMenuBarSet(bool)

   Sets whether or not the main menubar is currently visible.

.. oe:function:: AppShowSet

   .. code::

      void AppShowSet(const std::string &style)

   Sets the display status of the application. Valid options are:
  
   * "normal"
   * "minimized"
   * "maximized"
   * "fullscreen"

.. oe:function:: AppShowStatusBarGet

   .. code::

      bool AppShowStatusBarGet()

   Returns whether or not the main status bar is currently visible.

.. oe:function:: AppShowStatusBarSet

   .. code::

      void AppShowStatusBarSet(bool)

   Sets whether or not the main status bar is currently visible.

.. oe:function:: AppSloppyFocusGet

   .. code::

      bool AppSloppyFocusGet()

   Returns whether or not the window focus is changed by simply positioning the 
   mouse over a window as opposed to requiring a click in the window to change
   focus (the default behavior).

.. oe:function:: AppSloppyFocusSet

   .. code::

      bool AppSloppyFocusSet(bool sloppy)

   Sets whether or not the window focus is changed by simply positioning the 
   mouse over a window as opposed to requiring a click in the window to change
   focus (the default behavior).

.. oe:function:: AppStatusTextSet

   .. code::

      void AppStatusTextSet(const std::string &text, unsigned int seconds)

   Sets the displayed text in the status bar of the main application window to 
   the specified text. If the *seconds* parameter is 0, this text will replace
   the default SMILES display in the status bar. If the *seconds* parameter is
   greater than 0, the text will only be displayed for the specified period of
   time, returning to the default SMILES display when the time has elapsed.

.. oe:function:: AppWindowStyleGet

   .. code::

      std::string AppWindowStyleGet()

   Returns the application window display style of the application. These styles
   typically correspond to specific operating system window managers.

.. oe:function:: AppWindowStyleSet

   .. code::

      std::string AppWindowStyleSet(const std::string &windowStyle)

   Sets the application window display style of the application. These styles
   typically correspond to specific operating system window managers. 

.. oe:function:: BlockBegin

   .. code::

      void BlockBegin()

   Blocks user interaction with the GUI with the exception of the abort button.
   This function is used internally and should only be called by the user to 
   restore already existing blocking behavior that may have been temporarily
   overridden to enable user interaction within a user specified script.

.. oe:function:: BlockEnd

   .. code::

      void BlockEnd()

   Restores user interaction with the GUI that was previously blocked by
   :oe:func:`BlockBegin`. This function is used 
   internally and should only be called to enable user interaction (if needed)
   within a user specified script. Any script which calls this function should
   restore the blocking behavior by calling BlockBegin once the user
   interaction portion is complete. However, it is important to make sure that 
   blocking is actually active in the first place (see 
   :oe:func:`BlockGet`) before calling this function 
   and then later calling BlockBegin.

.. oe:function:: BlockExemptGet

   .. code::

      bool BlockExemptGet(const std::string &name)

   Returns whether or not the GUI object specified by *name* is exempt from GUI
   blocking when Python commands are being executed.

.. oe:function:: BlockExemptSet

   .. code::

      void BlockExemptSet(const std::string &name, bool value)

   Sets whether or not the GUI object specified by *name* is exempt from GUI
   blocking when Python commands are being executed.

.. oe:function:: BlockGet

   .. code::

      bool BlockGet()

   Returns whether or not user interaction with the GUI is currently being 
   blocked. User interaction is typically blocked while Python commands and
   scripts are being executed.

.. oe:function:: BuilderFocusOnProperties

   .. code::

      void BuilderFocusOnProperties()

   Displays the *Properties* tab in the Builder Window.

.. oe:function:: BuilderFocusOnSketcher

   .. code::

      void BuilderFocusOnSketcher()

   Displays the *Sketcher* tab in the Builder Window.

.. oe:function:: IconGetXPM

   .. code::

      std::vector<std::string> IconGetXPM(const std::string &name)

   Returns an XPM representation of the icon specified by name.

.. oe:function:: InterpreterClear

   .. code::

      void InterpreterClear()

   Clears the contents of the scripting window.

.. oe:function:: InterpreterPopUpdateGUI

   .. code::

      void InterpreterPopUpdateGUI()

   Specifies to the application that the normal interface updating behavior
   should occur after issued commands. This function is normally called in
   conjunction with :oe:func:`InterpreterPushUpdateGUI` to
   terminate the nonupdating behavior triggered by that function. It is
   important to note that these functions can be nested.

.. oe:function:: InterpreterPushUpdateGUI

   .. code::

      void InterpreterPushUpdateGUI(bool update)

   Specifies to the application whether or not the application should be 
   updating the interface after this function is called. This is normally called
   to allow multiple commands to be issued in a row without causing an interface
   update after each individual call. A call to 
   :oe:func:`InterpreterPopUpdateGUI` will
   resume the normal updating behavior. It is important to note that these calls
   can be nested.

.. oe:function:: InterpreterShowDebugTextGet

   .. code::

      bool InterpreterShowDebugTextGet()

   Returns whether or not debugging text will be displayed in the scripting
   window.

.. oe:function:: InterpreterShowDebugTextSet

   .. code::

      void InterpreterShowDebugTextSet(bool show)

   Sets whether or not debugging text will be displayed in the scripting
   window.

.. oe:function:: InterpreterTimerGet

   .. code::

      bool InterpreterTimerGet()

   Returns whether or not the application reports the time elapsed after every
   user entered command.

.. oe:function:: InterpreterTimerSet

   .. code::

      bool InterpreterTimerSet(bool enable)

   Sets whether or not the application reports the time elapsed after every
   user entered command.

.. oe:function:: InterpreterUpdatesGUI

   .. code::

      bool InterpreterUpdatesGUI()

   Returns whether or not VIDA is updating the interface after every
   command is completed.

.. oe:function:: LayoutCurrentGet

   .. code::

      std::string LayoutCurrentGet()

   Returns the name of the most recently applied named layout.

.. oe:function:: LayoutExists

   .. code::

      bool LayoutExists(const std::string &name)

   Returns whether or not the specified named layout exists.

.. oe:function:: LayoutGet

   .. code::

      std::string LayoutGet(const std::string &name)

   Returns a string representation of the specified name layout. The value
   returned by this function can be used as input to the following functions:
   
   * :oe:func:`AppLayoutSet`
   * :oe:func:`AppPerspectiveSet`

.. oe:function:: LayoutIcon

   .. code::

      std::vector<std::string> LayoutIcon(const std::string &name)

   Returns the icon associated with the specified named layout in XPM format.

.. oe:function:: LayoutLoad

   .. code::

      bool LayoutLoad(const std::string &name)

   Loads the specified named layout.

.. oe:function:: LayoutOrganizePrompt

   .. code::

      std::string LayoutOrganizePrompt()

   Launches the layout organization dialog.

.. oe:function:: LayoutOverrideOrder

   .. code::

      void LayoutOverrideOrder(const std::vector<std::string> &names)

   Sets the order to be used when displaying the named layouts in the layout
   button.

.. oe:function:: LayoutRemove

   .. code::

      bool LayoutRemove(const std::string &name)

   Removes the specified named layout.

.. oe:function:: LayoutRename

   .. code::

      bool LayoutRename(const std::string &oldName, const std::string &newName)

   Renames the specified named layout.

.. oe:function:: LayoutSaveCurrent

   .. code::

      bool LayoutSaveCurrent(const std::string &name)

   Saves the current application's layout using the specified name.

.. oe:function:: LayoutSet

   .. code::

      void LayoutSet(const std::string &name, const std::string &data)

   Creates a named layout using the specified name and layout data. The input 
   for the *data* parameter can be obtained from 
   :oe:func:`AppLayoutGet` command.

.. oe:function:: LayoutStickyGet

   .. code::

      bool LayoutStickyGet()

.. oe:function:: LayoutStickySet

   .. code::

      void LayoutStickySet(bool sticky)

.. oe:function:: Layouts

   .. code::

      std::vector<std::string> Layouts()

   Returns a list of the available named layouts.

.. oe:function:: ListWindowCollapseAll

   .. code::

      void ListWindowCollapseAll()

   Collapses all the visible nodes in the List Window to show only the top-level
   list entries.

.. oe:function:: ListWindowCollapseCurrent

   .. code::

      void ListWindowCollapseCurrent()

   Collapses the currently active list node in the List Window to a single 
   top-level entry.

.. oe:function:: ListWindowExpandAll

   .. code::

      void ListWindowExpandAll()

   Expands all the top-level list nodes in the List Window to show their 
   contents.

.. oe:function:: ListWindowExpandCurrent

   .. code::

      void ListWindowExpandCurrent()

   Expands the currently active list node in the List Window to show its
   contents.

.. oe:function:: ListWindowFirstList

   .. code::

      void ListWindowFirstList()

   Makes active the first item in the first list.

.. oe:function:: ListWindowFirstListItem

   .. code::

      void ListWindowFirstListItem()

   Makes active the first item in the current list.

.. oe:function:: ListWindowFocusOnOERID

   .. code::

      void ListWindowFocusOnOERID(unsigned int id)

   Changes the view of the list window to ensure that the specified ID is 
   visible.

.. oe:function:: ListWindowGetCurrentPos

   .. code::

      std::vector<unsigned int> ListWindowGetCurrentPos()

   Returns the current active position with the list window. This function
   is primarily intended for internal use only.

.. oe:function:: ListWindowHideColumn

   .. code::

      void ListWindowHideColumn(unsigned int column)

   Hides the specified column from view in the list window.

.. oe:function:: ListWindowIsVisible

   .. code::

      bool ListWindowIsVisible()

   Returns whether or not the list window is currently visible.

.. oe:function:: ListWindowLastList

   .. code::

      void ListWindowLastList()

   Makes active the first item in the last list.

.. oe:function:: ListWindowLastListItem

   .. code::

      void ListWindowLastListItem()

   Makes active the last item in the current list.

.. oe:function:: ListWindowNavigateChildrenGet

   .. code::

      bool ListWindowNavigateChildrenGet()

   Returns whether or not to navigate through an object's children when 
   browsing through the list window.

.. oe:function:: ListWindowNavigateChildrenSet

   .. code::

      void ListWindowNavigateChildrenSet(bool nav)

   Sets whether or not to navigate through an object's children when 
   browsing through the list window.

.. oe:function:: ListWindowNavigateLeft

   .. code::

      void ListWindowNavigateLeft()

   Navigate to a new active object as if the user had pressed the left arrow
   key inside of the list window.

.. oe:function:: ListWindowNavigateRight

   .. code::

      void ListWindowNavigateRight()

   Navigate to a new active object as if the user had pressed the right arrow
   key inside of the list window.

.. oe:function:: ListWindowNextList

   .. code::

      bool ListWindowNextList()
      
   Makes active the first item in the next list.

.. oe:function:: ListWindowNextListItem

   .. code::

      bool ListWindowNextListItem()

   Makes active the next item in the current list.

.. oe:function:: ListWindowPrevList

   .. code::

      bool ListWindowPrevList()

   Makes active the first item in the previous list.

.. oe:function:: ListWindowPrevListItem

   .. code::

      bool ListWindowPrevListItem()

   Makes active the previous item in the current list.

.. oe:function:: ListWindowRowColoringGet

   .. code::

      bool ListWindowRowColoringGet()

   Returns whether or not the list window uses an alternating row coloring 
   scheme.

.. oe:function:: ListWindowRowColoringSet

   .. code::

      void ListWindowRowColoringSet(bool on)

   Sets whether or not the list window uses an alternating row coloring 
   scheme.

.. oe:function:: ListWindowSetCurrentPos

   .. code::

      void ListWindowSetCurrentPos(std::vector<unsigned int> pos)

   Sets the current active position within the list window. This is intended
   for internal use only.

.. oe:function:: ListWindowShowColumn

   .. code::

      void ListWindowShowColumn(unsigned int column)

   Shows the specified column in the list window.

.. oe:function:: MainWindowScreenshot

   .. code::

      bool MainWindowScreenshot(const std::string &filename="")

   Captures an image of the current main window and saves that image to the 
   specified file.

.. oe:function:: MainWindowScreenshotPrompt

   .. code::

      bool MainWindowScreenshotPrompt()

   Opens a dialog which allows the user to specify multiple parameters regarding
   the creation of a screenshot of the main window.

.. oe:function:: MenuAddButton

   .. code::

      std::string MenuAddButton(const std::string &menu, const std::string &button, 
                                const std::string &command, bool last=false)
      std::string MenuAddButton(const std::string &menu, const std::string &button, 
                                const std::string &command, const std::string &hotkey, 
                                bool last)

   Adds a button to the specified menu which when pushed will execute the 
   specified Python command. An optional ``hotkey`` for this menu button may be
   provided. The ``last`` argument, if specified, indicates whether or not this
   button should always appear at the end of the menu regardless of how many 
   items are added to the menu after this.
  
   Returns a unique name identifier which can be used to reference this button
   in other functions.

.. oe:function:: MenuAddRadioButton

   .. code::

      std::string MenuAddRadioButton(const std::string &menu, 
                                     const std::string &button, 
                                     const std::string &command, 
                                     const std::string &updateCommand)

   Adds a radio button to the specified menu which when pushed will execute the
   specified Python command. The ``updateCommand`` parameter is a Python command
   which is used to update the checked state of this button.
  
   This function should only be called in between calls to 
   :oe:func:`MenuBeginRadioGroup` and
   :oe:func:`MenuEndRadioGroup`.

   Returns a unique name identifier which can be used to reference this button
   in other functions.

.. oe:function:: MenuAddSeparator

   .. code::

      std::string MenuAddSeparator(const std::string &menu, 
                                   const std::string &name="", 
                                   bool last=false, 
                                   bool conditional=false)

   Adds a simple line separator to the specified menu. The ``last`` parameter 
   specifies whether to keep this separator at the end of the menu. The 
   ``conditional`` parameter specifies whether or not to collapse multiple
   adjacent separators into a single separator.

   Returns a unique name identifier which can be used to reference this 
   separator in other functions.

.. oe:function:: MenuAddSubmenu

   .. code::

      std::string MenuAddSubmenu( const std::string &parent, 
                                  const std::string &menu, 
                                  bool last = false )
      std::string MenuAddSubmenu( const std::string &parent, 
                                  const std::string &menu, 
                                  const std::string &displayname, 
                                  bool last)
      std::string MenuAddSubmenu( const std::string &parent, 
                                  const std::string &menu, 
                                  const std::string &displayName, 
                                  const std::string &update, 
                                  bool last)

   Adds a submenu to the specified ``parent`` menu. The ``menu`` parameter is
   the desired name for this menu. The ``displayName`` parameter, if specified,
   contains the actual text to be shown when this menu is displayed. If no
   ``displayName`` parameter is specified, the ``menu`` parameter will be used.
   The ``update`` parameter specifies a Python command which will be called 
   immediately before showing the menu. This command can be used to update the
   state of the menu or to generate the menu on the fly as desired. The ``last``
   parameter specifies whether to keep this submenu at the end of the parent 
   menu.
   
   Returns a unique name identifier which can be used to reference this menu
   in other functions. Often this value will be the same as the value specified
   by the ``menu`` parameter, but it is not guaranteed to be the same due to
   potential name clashes.

.. oe:function:: MenuAddToggleButton

   .. code::

      std::string MenuAddToggleButton(const std::string &menu, 
                                      const std::string &button, 
                                      const std::string &command, 
                                      const std::string &updateCommand, 
                                      bool last=false)

   Adds a toggle button to the specified menu. Clicking on the button executes
   the Python code specified in the ``command`` parameter. The state of the
   toggle button is available to the Python command in the variable 
   ``OEInternal.MenuVal`` as either 0 or 1. The ``updateCommand`` parameter 
   specifies Python code which is called to determine the current state of the
   button. If this code returns a True value, the toggle will be set to on, if
   not, it will be set to off.
  
   Returns a unique name identifier which can be used to reference this button
   in other functions.

.. oe:function:: MenuBeginRadioGroup

   .. code::

      void MenuBeginRadioGroup(const std::string &menu)
      
    Begins a group of mutually exclusive radio buttons in the specified menu.

.. oe:function:: MenuButtonActionSet

   .. code::

      void MenuButtonActionSet(const std::string &menu, const std::string &item, 
                               const std::string &action)

   Sets the Python command *action* to be executed by the specified button 
   *item* in the specified menu *menu*.

.. oe:function:: MenuDisplayName

   .. code::

      void MenuDisplayName(const std::string &menu, const std::string &item, 
                           const std::string &display_name)

   Sets the display name (i.e. the text actually shown for this menu item) for 
   the specified menu item (button or submenu) in the specified menu. 

.. oe:function:: MenuDynamicSet

   .. code::

      void MenuDynamicSet(const std::string &menu, const std::string &cmd, 
                          bool dynamic)
  
   Sets whether or not the specified menu is dynamically updated or not. If the
   menu is set to be dynamically updated, the Python code contained in the 
   ``cmd`` parameter will be executed immediately before showing the menu each
   time the menu is shown.

.. oe:function:: MenuEnableItem

   .. code::

      void MenuEnableItem(const std::string &menu, const std::string &item, 
                          bool enabled)

   Sets whether or not the specified menu item is enabled.
  
.. oe:function:: MenuEnableItemCommand

   .. code::

      void MenuEnableItemCommand(const std::string &menu, const std::string &item, 
                                 const std::string &command)

   Sets a Python command which is run when a menu is updated to set whether the
   specified menu item is enabled or not.

.. oe:function:: MenuEndRadioGroup

   .. code::

      void MenuEndRadioGroup(const std::string &menu)

   Ends a group of mutually exclusive radio buttons in the specified menu.   

.. oe:function:: MenuExists

   .. code::

      bool MenuExists(const std::string &menu)

   Returns whether or not the specified menu exists.

.. oe:function:: MenuGetAllItemsContainingName

   .. code::

      std::vector<std::string> MenuGetAllItemsContainingName(const std::string &name)

   Searches for all menu items that contain the string "name."

.. oe:function:: MenuGetAllItems

  .. code::

      std::vector<std::string> MenuGetAllItems(const std::string &id)

   Returns a vector of ids of all sub items of a particular menu.
   If id is empty then it returns every menu item.

.. oe:function:: MenuHasItem

   .. code::

      bool MenuHasItem(const std::string &menu, const std::string &item)

   Returns whether or not the specified menu contains the specified menu item.

.. oe:function:: MenuItemIsAMenu

   .. code::

      bool MenuItemIsAMenu ( const std::string &id )

   Returns true if the id belongs to a menu as opposed to an action menu item.

.. oe:function:: MenuRemoveAll

   .. code::

      void MenuRemoveAll(const std::string &menu)

   Removes the entire contents of the specified menu.

.. oe:function:: MenuRemoveItem

   .. code::

      void MenuRemoveItem(const std::string &item)
      void MenuRemoveItem(const std::string &menu, const std::string &item)

   Removes the specified menu item from the specified menu.

.. oe:function:: MenuUpdateItem

   .. code::

      void MenuUpdateItem(const std::string &menu, const std::string &item)

   Updates the specified menu item in the specified menu. Calling this function
   on a menu item will cause the associated item to execute any previously bound 
   update command to determine the current state of the item.

.. oe:function:: Pick

   .. code::

      void Pick(unsigned int action, const std::string &source, 
                const std::vector<OEPropDB::OEKey> &keys, int replicate)
      void Pick(unsigned int action, unsigned int startX, unsigned int startY, 
                unsigned int endX, unsigned int endY, unsigned int width, 
                unsigned int height)

   Picks a small rectangular region on the 3D display specified by the start 
   and end coordinates. This function is primarily intended for internal use.

.. oe:function:: PickAgain

   .. code::

      void PickAgain(unsigned int action)

   Repeats the previous :oe:func:`Pick` action.

.. oe:function:: PopIgnoreHint

   .. code::

      void PopIgnoreHint()

   This function, paired with PushIgnoreHint, minimizes application response to the
   functions called between them.  Every PushIgnoreHint must be matched with a
   PopIgnoreHint and vice versa.

.. oe:function:: PopupAddButton

   .. code::

      std::string PopupAddButton(const std::string &button, 
                                 const std::string &command, bool showOnce=false)

   This function adds a clickable menu entry that runs the specified command to the popup menu.
   The last optional parameter specifies that this menu entry should only last one show
   of the popup menu.

.. oe:function:: PopupAddRadioButton

   .. code::

      std::string PopupAddRadioButton(const std::string &button, 
                                      const std::string &command, 
                                      const std::string &updateCommand, 
                                      bool showOnce=false)

   This function adds an exclusive clickable menu entry to the popup menu.
   The last optional parameter specifies that this menu entry should only last one show
   of the popup menu. It should only be called between 
   :oe:func:`PopupBeginRadioGroup` and
   :oe:func:`PopupEndRadioGroup`.

.. oe:function:: PopupAddSeparator

   .. code::

      std::string PopupAddSeparator(bool once=false, bool conditional=false)

   This function adds a non-clickable line menu entry to the popup menu.
   The last optional parameter specifies that this menu entry should only last one show
   of the popup menu.

.. oe:function:: PopupAddSetupFunc

   .. code::

      void PopupAddSetupFunc(const std::string &function)

   This function specifies a worker function to be called before the popup menu is shown.
   It is called with no arguments.  It is designed to allow context sensitive menu
   entries to be added to the popup menu.

.. oe:function:: PopupAddSubmenu

   .. code::

      std::string PopupAddSubmenu(const std::string &child, bool showOnce=false)

   This function adds a submenu to the popup menu. The last optional parameter specifies
   that this menu entry should only last one show of the popup menu.

.. oe:function:: PopupAddToggleButton

   .. code::

      std::string PopupAddToggleButton(const std::string &button, 
                                       const std::string &command, 
                                       const std::string &updateCommand, 
                                       bool showOnce=false, bool state=false)

   This function adds a clickable menu entry that runs the specified command to the popup menu.
   The last optional parameter specifies that this menu entry should only last one show
   of the popup menu. The state of the toggle is passed as either 0 or 1 in the variable
   OEInternal.MenuVal.  The return value of the update command is used to set the state
   of the toggle.  Returning 1 or True from the update function sets the toggle on.

.. oe:function:: PopupBeginRadioGroup

   .. code::

      void PopupBeginRadioGroup()

   This function specifies that the following added radio buttons are exclusive.

.. oe:function:: PopupDisplayName

   .. code::

      void PopupDisplayName(const std::string &item, const std::string &display_name)

   This function modifies the display name of a popup menu entry.

.. oe:function:: PopupEnableItem

   .. code::

      void PopupEnableItem(const std::string &item, bool enabled)

   This function enables or disables the specified popup menu entry.

.. oe:function:: PopupEnableItemCommand

   .. code::

      void PopupEnableItemCommand(const std::string &item, 
                                  const std::string &command)

   This function sets the update command on the given entry in the popup menu.

.. oe:function:: PopupEndRadioGroup

   .. code::

      void PopupEndRadioGroup()

   This function ends the radio group begun by 
   :oe:func:`PopupBeginRadioGroup`.

.. oe:function:: PopupRemoveAll

   .. code::

      void PopupRemoveAll()

   This function removes all entries from the popup menu.

.. oe:function:: PopupRemoveItem

   .. code::

      void PopupRemoveItem(const std::string &item)

   This function removes the specified entry from the popup menu.

.. oe:function:: ProgressbarUpdate

   .. code::

      bool ProgressbarUpdate(int count, int total)

   Updates the application progress bar based on the specified *count* and 
   *total* parameters.

.. oe:function:: PromptAtomicNum

   .. code::

      unsigned int PromptAtomicNum(const std::string &caption, unsigned int def=6)

   Prompts the user to specify an element from a periodic table dialog. 

.. oe:function:: PromptColor

   .. code::

      OEColor PromptColor(const OEColor &deflt=OEColor())

   Prompts the user to specify a color.

.. oe:function:: PromptError

   .. code::

      bool PromptError(const std::string &)

   This function prompts the user with an error message.

.. oe:function:: PromptFilename

   .. code::

      std::string PromptFilename(const std::string &def="", 
                                 const std::string &mode="Open", 
                                 const std::string &type="all", 
                                 const std::string &msg="")

   This function prompts the user for a filename.  The parameters specify the default value,
   whether it should be an 'Open' or 'Save' dialog, and what kind of file.

.. oe:function:: PromptFilenames

   .. code::

      std::vector<std::string> 
        PromptFilenames(const std::vector<std::string> &def=std::vector<std::string>(), 
                        const std::string &type="all", const std::string &msg="")

   This function prompts the user for a collection of filenames.  The parameters 
   specify the default value, whether it should be an 'Open' or 'Save' dialog, and 
   what kind of files.

.. oe:function:: PromptFloat

   .. code::

      float PromptFloat(const std::string &prompt, float def=0.0f, 
                        unsigned int prec=5)

   This function prompts the user for a floating point number.

.. oe:function:: PromptFont

   .. code::

      std::string PromptFont()

   Prompts the user to specify a desired font.

.. _PromptID:

.. oe:function:: PromptID

   .. code::

      unsigned int PromptID(unsigned int filters=0xF0FF, bool preview=true)
      unsigned int PromptID(std::vector<std::string> filterList, bool preview=true)

   This function prompts the user for an ID from the currently loaded set.

   Unsigned integer filters are an OR'ed combination of the following
   values.

    * PromptFilter_Molecules
    * PromptFilter_Surfaces
    * PromptFilter_Grids
    * PromptFilter_Lists
    * PromptFilter_Reflections
    * PromptFilter_Selected
    * PromptFilter_Active
    * PromptFilter_Marked
    * PromptFilter_Visible
    * PromptFilter_Unknown
    * PromptFilter_All

   String filters are just placed in a list:

    * 'M' or 'm' for molecules
    * 'S' or 's' for surfaces
    * 'R' or 'r' for reflections
    * 'G' or 'g' for grids
    * 'L' or 'l' for lists
    * 'O' or 'o' for Unknown objects

   For example, to prompt for Molecules and Surfaces:

   id = PromptID(PromptFilter_Molecules | PromptFilter_Surfaces)

   or

   id = PromptID(['M','S'])
   
.. oe:function:: PromptIDWriteFilters

   .. code::

      std::vector<std::string> PromptIDWriteFilters(const std::string &fname)

   This function returns the valid types that can be written to the type of
   file specified by the filename parameter.

.. oe:function:: PromptIDs

   .. code::

      std::vector<unsigned int> PromptIDs(unsigned int filters=0xF0FF, 
                                          bool preview=true)
      std::vector<unsigned int> PromptIDs(const std::vector<std::string> &filterList, 
                                          bool preview=true)

   This function prompts the user for several IDs from the currently loaded set.

   See :ref:`PromptID<PromptID>` for the list of available filters.

.. oe:function:: PromptInteger

   .. code::

      int PromptInteger(const std::string &msg, int def=0)

   This function prompts the user for an integer.

.. oe:function:: PromptKey

   .. code::

      OEPropDB::OEKey PromptKey(unsigned int filters=0xF0FF, bool preview=true)
      OEPropDB::OEKey PromptKey(const std::vector<std::string> &filterList, 
                                bool preview=true)

   This function prompts the user for a key.

   See :ref:`PromptID<PromptID>` for the list of available filters.

.. oe:function:: PromptKeys

   .. code::

      std::vector<OEPropDB::OEKey> 
        PromptKeys(const std::vector<std::string> &filterList, bool preview=true)
      std::vector<OEPropDB::OEKey> PromptKeys(unsigned int filters=0xF0FF, 
                                              bool preview=true)

   This function prompts the user for a collection of key.

   See :ref:`PromptID<PromptID>` for the list of available filters.

.. oe:function:: PromptMessage

   .. code::

      bool PromptMessage(const std::string &msg)

   This function alerts the user with a message and an OK button.

.. oe:function:: PromptModeGet

   .. code::

      std::string PromptModeGet()

.. oe:function:: PromptModeSet

   .. code::

      bool PromptModeSet(const std::string &mod)

.. oe:function:: PromptFragment

   .. code::

      std::string PromptMolecule(const std::string &caption)

   Prompts the user to input a molecule fragment using the built-in molecule input 
   dialog. Returns a hexadecimal encoded OEB string representation of the 
   fragment.  In addition to specifying a molecular fragment, the user will
   be required to define an attachment point, either by including a dummy atom
   or a selected atom or bond.

.. oe:function:: PromptMolecule

   .. code::

      std::string PromptMolecule(const std::string &caption, 
                                 const std::string &def="", unsigned int options=21)

   Prompts the user to specify a molecule using the built-in molecule input 
   dialog. Returns a hexadecimal encoded OEB string representation of the 
   molecule.

.. oe:function:: PromptMoleculeSplit

   .. code::

      std::string PromptMoleculeSplit(unsigned int id)

   Launches a dialog to assist in the splitting of the specified molecule.

.. oe:function:: PromptMulti

   .. code::

      bool PromptMulti(const std::string &prompt, std::vector<std::string> names, 
                       std::vector<std::string> types, 
                       std::vector<std::string> defs, 
                       std::vector<OEInterpreter::OEMultiTypeVar> &out)

   This function prompts the user for several different types of variables and
   returns them in a list.

.. oe:function:: PromptQuery

   .. code::

      std::string PromptQuery(const std::string &def="")

   This function prompts the user for a query string for calls to 
   :oe:func:`ListSubsetQuery`.

.. oe:function:: PromptResponseBool

   .. code::

      void PromptResponseBool(const std::string &msg, bool v, bool forceInter)

   This function pushes a boolean response to an upcoming Prompt, allowing it to be skipped
   in scripts. Ordinarily this function should not need to be called by the user.

.. oe:function:: PromptResponseCanceled

   .. code::

      void PromptResponseCanceled(const std::string &)

   This function pushes a cancel response to an upcoming Prompt, allowing it to be skipped
   in scripts. Ordinarily this function should not need to be called by the user.

.. oe:function:: PromptResponseColor

   .. code::

      void PromptResponseColor(const std::string &type, const OESystem::OEColor &c, 
                               bool forceInteractive)

   This function pushes a color response to an upcoming Prompt, allowing it to be skipped
   in scripts. Ordinarily this function should not need to be called by the user.

.. oe:function:: PromptResponseFloat

   .. code::

      void PromptResponseFloat(const std::string &type, float v, bool forceInter)

   This function pushes a floating point response to an upcoming Prompt, allowing it to be skipped
   in scripts. Ordinarily this function should not need to be called by the user.

.. oe:function:: PromptResponseInt

   .. code::

      void PromptResponseInt(const std::string &type, int v, bool forceInter=false)

   This function pushes an integer response to an upcoming Prompt, allowing it to be skipped
   in scripts. Ordinarily this function should not need to be called by the user.

.. oe:function:: PromptResponseKey

   .. code::

      void PromptResponseKey(const std::string &type, const OEPropDB::OEKey &key, 
                             bool forceInteractive=false)

   This function pushes a key response to an upcoming Prompt, allowing it to be skipped
   in scripts. Ordinarily this function should not need to be called by the user.

.. oe:function:: PromptResponseKeys

   .. code::

      void PromptResponseKeys(const std::string &type, 
                              std::vector<OEPropDB::OEKey> &keys, 
                              bool forceInteractive=false)

   This function pushes a collection of keys response to an upcoming Prompt, 
   allowing it to be skipped in scripts. Ordinarily this function should not 
   need to be called by the user.

.. oe:function:: PromptResponseString

   .. code::

      void PromptResponseString(const std::string &type, const std::string &v, 
                                bool forceInteractive=false)

   This function pushes a string response to an upcoming Prompt, allowing it to be skipped
   in scripts. Ordinarily this function should not need to be called by the user.

.. oe:function:: PromptResponseUInt

   .. code::

      void PromptResponseUInt(const std::string &type, unsigned int v, 
                              bool forceInteractive=false)

   This function pushes a positive integer response to an upcoming Prompt, allowing it to be skipped
   in scripts. Ordinarily this function should not need to be called by the user.

.. oe:function:: PromptResponseVectInt

   .. code::

      void PromptResponseVectInt(const std::string &type, 
                                 const std::vector<int> &value, 
                                 bool forceInteractive=false)

   This function pushes a list-of-integers response to an upcoming Prompt, allowing it to be skipped
   in scripts. Ordinarily this function should not need to be called by the user.

.. oe:function:: PromptResponseVectMulti

   .. code::

      void PromptResponseVectMulti(const std::string &type, 
                                   const std::vector<OEInterpreter::OEMultiTypeVar> &value, 
                                   bool forceInteractive=false)

.. oe:function:: PromptResponseVectString

   .. code::

      void PromptResponseVectString(const std::string &type, 
                                    const std::vector<std::string> &value, 
                                    bool forInteractive=false)

   This function pushes a list-of-strings response to an upcoming Prompt, allowing it to be skipped
   in scripts. Ordinarily this function should not need to be called by the user.

.. oe:function:: PromptResponseVectUInt

   .. code::

      void PromptResponseVectUInt(const std::string &type, 
                                  const std::vector<unsigned int> &value, 
                                  bool forceInteractive=false)

   This function pushes a list-of-positive-integers response to an upcoming Prompt,
   allowing it to be skipped in scripts. Ordinarily this function should not
   need to be called by the user.

.. oe:function:: PromptSaveFilename

   .. code::

      std::string PromptSaveFilename(const std::vector<unsigned int> &ids, 
                                     const std::string &msg="")
      std::string PromptSaveFilename(const std::vector<OEPropDB::OEKey> &keys, 
                                     const std::string &msg="")
      std::vector<std::string> PromptSaveFilename(const std::string &filters, 
                                                  const std::string &msg="")

   This function prompts the user to select a file for saving. The *filters* 
   parameter allows for specification of filter types to be shown in the file
   dialog. Individual filters should be separated by a pair of semicolons like 
   this:

   "OpenEye OEBinary (*.oeb);;All Files (*.*)"

   The *msg* parameter allows for specification of the caption of the file dialog.
   This function returns a list where the first member is the selected filename
   and the second is the selected filter. If the user cancels the prompt, the 
   returned list will be empty.

   See :ref:`PromptID<PromptID>` for the list of available filters.

.. oe:function:: PromptSmiles

   .. code::

      std::string PromptSmiles(const std::string &caption, const std::string &def="", 
                               unsigned int options=21)

   Prompts the user to specify a molecule using the built-in molecule input 
   dialog. The molecule is returned as a SMILES string.

.. oe:function:: PromptString

   .. code::

      std::string PromptString(const std::string &prompt="", 
                               const std::string &def="", bool lineMode=true, 
                               bool editable=true)

   This function prompts the user for a string.

.. oe:function:: PromptStringListFromString

   .. code::

      void PromptStringListFromString(const std::string &in, 
                                      std::vector<std::string> &options, 
                                      unsigned int &def)

   This function prompts the user for a string.

.. oe:function:: PromptStringListToString

   .. code::

      std::string PromptStringListToString(const std::vector<std::string> &options, 
                                           unsigned int def)
      std::string PromptStringListToString(const std::vector<std::string> &options, 
                                           const std::string &def)

   This function generates a list of strings from a formatted string.  
   Ordinarily this function should not need to be called by the user.

.. oe:function:: PromptYesNo

   .. code::

      bool PromptYesNo(const std::string &prompt, const std::string &key="")
      bool PromptYesNo(const std::string &prompt, bool &check, 
                       const std::string &key="")

   This function prompts the user for a yes or no answer.

.. oe:function:: PromptYesNoSetDefault

   .. code::

      bool PromptYesNoSetDefault(const std::string &key, bool def)

   This function prompts the user for a yes or no answer.

.. oe:function:: PushIgnoreHint

   .. code::

      void PushIgnoreHint(bool ignore)

   This function delays update actions for the following commands until a PopIgnoreHint is called.
   PushIgnoreHint and PopIgnoreHints MUST match.

.. oe:function:: SetProgressbar

   .. code::

      void SetProgressbar(int index, int total)

   This function sets the progress bar to the specified value.

.. oe:function:: ToolbarAddSeparator

   .. code::

      void ToolbarAddSeparator(const std::string &toolbar="Application")

   Adds a separator to the specified toolbar.

.. oe:function:: ToolbarAddToggle

   .. code::

      void ToolbarAddToggle(const std::string &onText, const std::string &offText, 
                            const std::string &onCommand, 
                            const std::string &offCommand, const std::string &desc, 
                            const std::string &update, 
                            const std::string &toolbar="Application", 
                            const std::string &name="", int margin=5)
      void ToolbarAddToggle(const std::vector<std::string> &onIcon, 
                            const std::vector<std::string> &offIcon, 
                            const std::string &onCommand, 
                            const std::string &offCommand, const std::string &desc, 
                            const std::string &update, 
                            const std::string &toolbar="Application", 
                            const std::string &name="")

   Adds a single standard toggle button to the specified toolbar. Both on and off 
   icons can be specified as parameters (in XPM format). Commands for both the on 
   and off states can be specified and will be executed when the associated 
   button enters that state.

.. oe:function:: ToolbarBeginRadio

   .. code::

      void ToolbarBeginRadio(const std::string &name, 
                             const std::string &toolbar="Application")

    Begins a named group of mutually exclusive radio buttons in the specified 
    toolbar.

.. oe:function:: ToolbarButtonEnableGet

   .. code::

      bool ToolbarButtonEnableGet(const std::string &name, 
                                  const std::string &toolbar="Application")

   Returns whether or not the specified button in the specified toolbar is 
   currently enabled.

.. oe:function:: ToolbarButtonEnableSet

   .. code::

      void ToolbarButtonEnableSet(const std::string &name, bool enabled, 
                                  const std::string &toolbar="Application")

   Sets whether or not the specified button in the specified toolbar is 
   currently enabled. 

.. oe:function:: ToolbarCreate

   .. code::

      void ToolbarCreate(const std::string &toolbar)

   Creates a new toolbar with the specified name.

.. oe:function:: ToolbarEnabledGet

   .. code::

      bool ToolbarEnabledGet(const std::string &toolbar="Application")

   Returns whether or not the specified *toolbar* is currently enabled.

.. oe:function:: ToolbarEnabledSet

   .. code::

      bool ToolbarEnabledSet(bool vis, const std::string &toolbar="Application")

   Sets whether or not the specified *toolbar* is currently enabled.

.. oe:function:: ToolbarEndRadio

   .. code::

      void ToolbarEndRadio(const std::string &name, 
                           const std::string &toolbar="Application")

   Ends the named group of mutually exclusive radio buttons in the specified 
   toolbar.   

.. oe:function:: ToolbarGetAll

   .. code::

      std::vector<std::string> ToolbarGetAll()

   Returns a list of all the existing toolbars in VIDA.

.. oe:function:: ToolbarItemCheckedGet

   .. code::

      bool ToolbarItemCheckedGet(const std::string &name, const std::string &toolbar)

   Returns whether or not the specified toolbar item in the specified toolbar is
   currently checked.

.. oe:function:: ToolbarItemCheckedSet

   .. code::

      bool ToolbarItemCheckedSet(bool, const std::string &name, 
                                 const std::string &toolbar)

   Sets whether or not the specified toolbar item in the specified toolbar is
   currently checked.

.. oe:function:: ToolbarItemUpdate

   .. code::

      void ToolbarItemUpdate(const std::string &name, const std::string &toolbar)

   Causes the specified toolbar item in the specified toolbar to update itself.

.. oe:function:: ToolbarItemVisibleGet

   .. code::

      bool ToolbarItemVisibleGet(const std::string &name, const std::string &toolbar)

   Returns whether or no the specified toolbar item in the specified toolbar is 
   currently visible.

.. oe:function:: ToolbarItemVisibleSet

   .. code::

      bool ToolbarItemVisibleSet(bool, const std::string &name, 
                                 const std::string &toolbar)

   Sets whether or not the specified toolbar item in the specified toolbar is
   currently visible.

.. oe:function:: ToolbarRemove

   .. code::

      void ToolbarRemove(const std::string &toolbar)
      void ToolbarRemove(const std::string &toolbar, const std::string &name)

   Removes the specified *toolbar* from VIDA. Please not that when a
   toolbar is removed, it is deleted from the application and not simply hidden.

.. oe:function:: ToolbarUpdate

   .. code::

      void ToolbarUpdate(const std::string &toolbar)

   Updates the specified toolbar.

.. oe:function:: ToolbarVisibleGet

   .. code::

      bool ToolbarVisibleGet(const std::string &toolbar="Application")

   Returns whether or not the specified toolbar is currently visible.

.. oe:function:: ToolbarVisibleSet

   .. code::

      bool ToolbarVisibleSet(bool vis, const std::string &toolbar="Application")

   Sets whether or not the specified toolbar is currently visible.

.. oe:function:: UpdateStyleWidget

   .. code::

      void UpdateStyleWidget()

   This function notifies the style widget that it should update itself due to 
   changes that might affect its display.

.. oe:function:: UpdateUndo

   .. code::

      void UpdateUndo()

   This function updates the undo menu. Ordinarily this function
   should not need to be called by the user.

.. oe:function:: ViewerActiveAnnotation

   .. code::

      OEGLTextBox *ViewerActiveAnnotation(int x=-1, int y=-1, int w=-1, int h=-1)

   Create the active annotation.

.. oe:function:: ViewerActiveAnnotationBackgroundColorGet

   .. code::

      OESystem::OEColor ViewerActiveAnnotationBackgroundColorGet()

   Return the background color for the active annotation.

.. oe:function:: ViewerActiveAnnotationBackgroundColorSet

   .. code::

      void ViewerActiveAnnotationBackgroundColorSet(const OESystem::OEColor &clr)

   Set the background color for the active annotation.

.. oe:function:: ViewerActiveAnnotationClose

   .. code::

      void ViewerActiveAnnotationClose()

   Close the active annotation window.

.. oe:function:: ViewerActiveAnnotationFontGet

   .. code::

      std::string ViewerActiveAnnotationFontGet()

   Return the font used for the active annotation.

.. oe:function:: ViewerActiveAnnotationFontSet

   .. code::

      void ViewerActiveAnnotationFontSet(const std::string &font)

   Set the font used for the active annotation. Uses fonts as returned by the 
   :oe:func:`PromptFont` scripting command.

.. oe:function:: ViewerActiveAnnotationForegroundColorGet

   .. code::

      OESystem::OEColor ViewerActiveAnnotationForegroundColorGet()

   Returns the foreground (text) color used in the active annotation.

.. oe:function:: ViewerActiveAnnotationForegroundColorSet

   .. code::

      void ViewerActiveAnnotationForegroundColorSet(const OESystem::OEColor &clr)

   Sets the foreground (text) color for the active annotation.

.. oe:function:: ViewerActiveAnnotationVisible

   .. code::

      bool ViewerActiveAnnotationVisible()
      
   Returns whether or not the active annotation is visible.

.. oe:function:: ViewerActiveDataFontSizeGet

   .. code::

      unsigned int ViewerActiveDataFontSizeGet()

   Returns the font size for the active data display.

.. oe:function:: ViewerActiveDataFontSizeSet

   .. code::

      void ViewerActiveDataFontSizeSet(unsigned int sz)

   Sets the font size for the active data display.

.. oe:function:: ViewerActiveDataHide

   .. code::

      OEGLDataView *ViewerActiveDataHide()

   Hides the active data display.

.. oe:function:: ViewerActiveDataShow

   .. code::

      OEGLDataView *ViewerActiveDataShow()
      OEGLDataView *ViewerActiveDataShow(int x, int y, int h, int w)

   Returns and shows the active data display.

.. oe:function:: ViewerActiveDataVisible

   .. code::

      bool ViewerActiveDataVisible()

   Returns whether or not the active data display is currently visible in
   the 3D display.

.. oe:function:: ViewerBookmarkWidget

   .. code::

      OEGLHList *ViewerBookmarkWidget()

   Returns a reference to the bookmark control widget.

.. oe:function:: ViewerBookmarkWidgetFontSizeGet

   .. code::

      unsigned int ViewerBookmarkWidgetFontSizeGet()

   Returns the size of the font used in the bookmark control widget.

.. oe:function:: ViewerBookmarkWidgetFontSizeSet

   .. code::

      void ViewerBookmarkWidgetFontSizeSet(unsigned int sz)

   Sets the size of the font used in the bookmark control widget.

.. oe:function:: ViewerBookmarkWidgetHide

   .. code::

      OEGLHList *ViewerBookmarkWidgetHide()

   Hides the bookmark control widget from the 3D display.

.. oe:function:: ViewerBookmarkWidgetShow

   .. code::

      OEGLHList *ViewerBookmarkWidgetShow()

   Shows the bookmark control widget in the 3D display.

.. oe:function:: ViewerButtonImage

   .. code::

      OEGLButton *ViewerButtonImage(const std::string &image, 
                                    const std::string &callback, 
                                    int x, int y, int w=-1, int h=-1)

   Creates and returns a clickable button in the 3D display. The *image* parameter
   specifies the name of the icon to be displayed on the button. The *callback*
   parameter specifies the Python function to be executed when the button is 
   clicked on. The position and dimensions of the button are specified by the 
   parameters *x*, *y*, *w*, and *h*.

.. oe:function:: ViewerClick

   .. code::

      void ViewerClick(int fxn, int x, int y, int gX, int gY, int w, int h)

   This function performs an action in the display corresponding to a mouse click
   event in the 3D display window. Ordinarily, this function should not need to be 
   called by the user.

.. oe:function:: ViewerCursorSet

   .. code::

      void ViewerCursorSet(const std::string &mode)

   This function sets the cursor style based on the *mode* parameter. Valid *mode*
   parameters are:

    * arrow - sets the cursor to the standard arrow cursor
    * back diagonal arrow - sets the cursor to a backwards diagonal double-ended arrow
    * blank - sets the cursor to a blank cursor (no cursor will appear)
    * busy - sets the cursor to be a busy indicator (an hourglass on many systems)
    * closed hand - sets the cursor to be a closed hand
    * cross - sets the cursor to two crossed lines
    * double arrow - sets the cursor to two crossed double-ended arrows
    * forbidden - sets the cursor to be a circle with a cross line through it
    * forward diagonal arrow - sets the cursor to a forwards diagonal double-ended arrow
    * horizontal arrow - sets the cursor to a horizontal double-ended arrow
    * ibeam - sets the cursor to an ibeam style cursor
    * open hand - sets the cursor to be an open hand
    * pointing - sets the cursor to be a pointing hand
    * rotation - same as *cross*
    * split horizontal - sets the cursor to two parallel horizontal lines with perpendicular arrows coming out of each line
    * split vertical - sets the cursor to two parallel vertical lines with perpendicular arrows coming out of each line
    * translation - same as *double arrow*
    * up arrow - sets the cursor to an upwards point arrow
    * vertical arrow - sets the cursor to a vertical double-ended arrow
    * wait - sets the cursor to a waiting indicator (an hourglass on many systems)
    * whats this - sets the cursor to be an arrow with an adjacent question mark

.. oe:function:: ViewerDepict

   .. code::

      OEGLImage *ViewerDepict(const OEPropDB::OEKey &key, int x, int y, int width, 
                              int height)

   Creates and returns a depiction widget for the 3D display. The *key* parameter
   specifies which molecule to use for the depiction. The position and dimensions
   of the widget are specified by the *x*, *y*, *width*, and *height* parameters.

.. oe:function:: ViewerDepictionAntiAliasGet

   .. code::

      bool ViewerDepictionAntiAliasGet()

   Returns whether or not the lines used in drawing depictions in the 3D display 
   should be anti-aliased.

.. oe:function:: ViewerDepictionAntiAliasSet

   .. code::

      void ViewerDepictionAntiAliasSet(bool s)

   Sets whether or not the lines used in drawing depictions in the 3D display 
   should be anti-aliased.

.. oe:function:: ViewerDepictionHeightGet

   .. code::

      float ViewerDepictionHeightGet()

   Returns the percent of the total height of the 3D display that the active
   depiction display uses when drawing onto the 3D display.

.. oe:function:: ViewerDepictionLineWidthGet

   .. code::

      float ViewerDepictionLineWidthGet()

   Returns the width of the lines used in drawing depictions in the 3D display.

.. oe:function:: ViewerDepictionLineWidthSet

   .. code::

      void ViewerDepictionLineWidthSet(float lw)

   Sets the width of the lines used in drawing depictions in the 3D display.

.. oe:function:: ViewerDepictionSizeSet

   .. code::

      float ViewerDepictionSizeSet(float percent)
      float ViewerDepictionSizeSet(float perc_w, float perc_h)

   Sets the percents of the total width and height of the 3D display that the
   active depiction display uses when drawing onto the 3D display. The *perc_w*
   parameter specifies the percent width and the *perc_h* specifies the percent
   height.

.. oe:function:: ViewerDepictionWidthGet

   .. code::

      float ViewerDepictionWidthGet()

   Returns the percent of the total width of the 3D display that the active
   depiction display uses when drawing onto the 3D display.

.. oe:function:: ViewerLabel

   .. code::

      OEGLLabel *ViewerLabel(const std::string &message, int x, int y)

   Creates and returns a text label which is displayed in the 3D window. The text
   is specified by the *message* parameter and the position is specified by the 
   *x* and *y* parameters.

.. oe:function:: ViewerLabelDialog

   .. code::

      void ViewerLabelDialog(const std::string &type)

   Opens a dialog which allows the user to specify what types of labels to
   apply to either atoms or bonds.

.. oe:function:: ViewerMouseClick

   .. code::

      void ViewerMouseClick(unsigned int state, unsigned int action)

   This function specifies the desired *action* that should occur when a mouse
   click event is generated with the associated *state*. The *state* parameter 
   specifies which mouse buttons were clicked as well as whether any modifier
   keys were depressed at the same time. *State* parameters can be added together
   to specify complicated states. Valid *state* parameters are:

    * MouseState_None
    * MouseState_Left
    * MouseState_Middle
    * MouseState_Right
    * MouseState_Shift
    * MouseState_Control
    * MouseState_Alt

   *Action* parameters are distinct and cannot be added together like *state* 
   parameters. Valid *action* parameters are:

    * MouseClick_None
    * MouseClick_Menu - creates a context specific popup menu
    * MouseClick_Select - selects the object that was clicked on and clears the
                          previous selection
    * MouseClick_SelectAdd - selects the object that was clicked on, but does not
                            clear the previous selection
    * MouseClick_SelectGrow - extends the selection of the object that was 
                              clicked on: atom -> residue -> chain -> mol and
                              clears the previous selection
    * MouseClick_SelectAddGrow - extends the selection of the object that was 
                                clicked on: atom -> residue -> chain -> mol and
                                clears the previous selection
    * MouseClick_SelectToggle - toggles the selection of the object that was 
                                clicked on
    * MouseClick_Label - displays a context specific label corresponding to the
                         object that was clicked on
                       
                       
.. oe:function:: ViewerMouseDoubleClick

   .. code::

      void ViewerMouseDoubleClick(unsigned int state, unsigned int action)

   This function specifies the desired *action* that should occur when a mouse
   double-click event is generated with the associated *state*. The *state* 
   parameter specifies which mouse buttons were clicked as well as whether any 
   modifier keys were depressed at the same time. *State* parameters can be added 
   together to specify complicated states. Valid *state* parameters are:

    * MouseState_None
    * MouseState_Left
    * MouseState_Middle
    * MouseState_Right
    * MouseState_Shift
    * MouseState_Control
    * MouseState_Alt

   *Action* parameters are distinct and cannot be added together like *state* 
   parameters. Valid *action* parameters are:

    * MouseClick_None
    * MouseClick_Menu - creates a context specific popup menu
    * MouseClick_Select - selects the object that was clicked on and clears the
                          previous selection
    * MouseClick_SelectAdd - selects the object that was clicked on, but does not
                            clear the previous selection
    * MouseClick_SelectGrow - extends the selection of the object that was 
                              clicked on: atom -> residue -> chain -> mol and
                              clears the previous selection
    * MouseClick_SelectAddGrow - extends the selection of the object that was 
                                clicked on: atom -> residue -> chain -> mol and
                                clears the previous selection
    * MouseClick_SelectToggle - toggles the selection of the object that was 
                                clicked on
    * MouseClick_Label - displays a context specific label corresponding to the
                         object that was clicked on
  
.. oe:function:: ViewerMouseFunctionGet

   .. code::

      unsigned int ViewerMouseFunctionGet()

   Returns the current function of the mouse when used in the 3D display. For more
   details on the different types of functions, please see the documentation for
   ViewerMouseFunctionSet.

.. oe:function:: ViewerMouseFunctionNameGet

   .. code::

      std::string ViewerMouseFunctionNameGet(unsigned int)

   Returns the name of the specified mouse function.

.. oe:function:: ViewerMouseFunctionSet

   .. code::

      void ViewerMouseFunctionSet(unsigned int action)
      void ViewerMouseFunctionSet(const std::string &)

   Sets the current function of the mouse when used in the 3D display. Valid 
   functions are:

    * MouseClick_None - this tells the mouse to act according to behaviors specified by the current mouse map (this is the default behavior)
    * MouseClick_Label - this mode causes a detailed information label to appear on the screen regarding whatever is currently under the cursor
    * MouseClick_MeasureAngle - this puts the mouse into angle measurement mode
    * MouseClick_MeasureDistance - this puts the mouse into distance measurement mode
    * MouseClick_MeasureTorsion - this puts the mouse into torsion measurement mode

.. oe:function:: ViewerMouseMap

   .. code::

      void ViewerMouseMap(const std::string &map)

   This function sets the current mouse mapping. Valid parameters include: 
  
    * vida
    * afitt
    * coot
    * insight
    * moe
    * o
    * quanta
    * rasmol
    * sybyl
    * maestro

.. oe:function:: ViewerMouseMove

   .. code::

      void ViewerMouseMove(unsigned int state, unsigned int action, 
                           unsigned int loc=OEGUI::MouseLocation::Both, 
                           unsigned int dir=OEGUI::MouseDirection::Both)

   This function specifies the desired *action* that should occur when a mouse
   movement event is generated with the associated *state*, in the specified 
   *location*, and in the specified *direction*. The *state* parameter specifies 
   which mouse buttons were clicked as well as whether any modifier keys were 
   depressed at the same time. *State* parameters can be added together to specify 
   complicated states. Valid *state* parameters are:

    * MouseState_None
    * MouseState_Left
    * MouseState_Middle
    * MouseState_Right
    * MouseState_Shift
    * MouseState_Control
    * MouseState_Alt

   The *location* parameter specifies whether the mouse was inside or outside a
   central circular region in the 3D display. The bounds of this region can be
   displayed using the ViewerShowTrackballGuideSet scripting command. Valid 
   *location* parameters are:

    * MouseLocation_None
    * MouseLocation_Inside
    * MouseLocation_Outside
    * MouseLocation_Both
    
   The *direction* parameter specifies which direction of mouse motion should 
   control the action. Valid *direction* parameters are:

    * MouseDirection_None
    * MouseDirection_X
    * MouseDirection_Y
    * MouseDirection_Both

   *Action* parameters are distinct and cannot be added together like *state* 
   parameters. Valid *action* parameters are:

    * MouseMotion_None
    * MouseMotion_RotateX - rotates the display along the X axis
    * MouseMotion_RotateY - rotates the display along the Y axis
    * MouseMotion_RotateZ - rotates the display along the Z axis
    * MouseMotion_Trackball - rotates the display using a trackball motion
    * MouseMotion_TranslateXY - translates the display along the X and Y axes
    * MouseMotion_TranslateX - translates the display along the X axis
    * MouseMotion_TranslateY - translates the display along the Y axis
    * MouseMotion_TranslateZ - translates the display along the Z axis 
    * MouseMotion_Zoom - zooms the display
    * MouseMotion_Clip - controls the position of the far and near clipping 
                        planes in a mirrored fashion
    * MouseMotion_ClipFar - controls the position of the far clipping plane
    * MouseMotion_ClipNear - controls the position of the near clipping plane
    * MouseMotion_DepthcueBegin - controls the position of the start of the 
                                  depthcueing calculation
    * MouseMotion_DepthcueEnd - controls the position of the end of the 
                                depthcueing calculation
    * MouseMotion_SelectRect - draws a rectangle on the screen and will select
                              the entire contents of that rectangle when the
                              mouse button is released while clearing the
                              previous selection
    * MouseMotion_SelectRectAdd - draws a rectangle on the screen and will select
                                  the entire contents of that rectangle when the
                                  mouse button is released while keeping the
                                  previous selection
    * MouseMotion_Label - displays a context specific label containing 
                          information about whatever object is currently beneath
                          the mouse
    * MouseMotion_Contour - adjusts the contour level of the grid contours in the
                            current scope
    * MouseMotion_TextScale - adjusts the size of the text displayed in the 3D 
                              display
                              
                            
.. oe:function:: ViewerMouseOutsideAwareGet

   .. code::

      bool ViewerMouseOutsideAwareGet()

   Returns whether or not the display window recognizes mouse motion along the 
   outside edge of the window as a potentially different action from mouse motion 
   in the interior of the window. Ordinarily, this function should not need to be 
   called by the user.

.. oe:function:: ViewerMouseOutsideAwareSet

   .. code::

      bool ViewerMouseOutsideAwareSet(bool aware)

   Sets whether or not the display window recognizes mouse motion along the outside 
   edge of the window as a potentially different action from mouse motion in the 
   interior of the window. Ordinarily, this function should not need to be 
   called by the user.

.. oe:function:: ViewerMouseReset

   .. code::

      void ViewerMouseReset()

   Clears the current mouse mapping. Ordinarily, this function should not need to
   be called by the user. Furthermore, calling this function without rebuilding 
   the mouse map will disable all interaction with the 3D window.

.. oe:function:: ViewerMouseSensitivityGet

   .. code::

      float ViewerMouseSensitivityGet()

   Returns the sensitivity of mouse event detection in the 3D window.

.. oe:function:: ViewerMouseSensitivitySet

   .. code::

      float ViewerMouseSensitivitySet(float s)

   Sets the sensitivity of mouse event detection in the 3D window.

.. oe:function:: ViewerMouseWheel

   .. code::

      void ViewerMouseWheel(unsigned int state, unsigned int action)

   This function specifies the desired *action* that should occur when a mouse
   wheel event is generated with the associated *state*. The *state* parameter 
   specifies whether any modifier keys were depressed at the same time. *State* 
   parameters can be added together to specify complicated states. Valid *state* 
   parameters are:

    * MouseState_None
    * MouseState_Shift
    * MouseState_Control
    * MouseState_Alt

   *Action* parameters are distinct and cannot be added together like *state* 
   parameters. Valid *action* parameters are:

    * MouseMotion_None
    * MouseMotion_RotateX - rotates the display along the X axis
    * MouseMotion_RotateY - rotates the display along the Y axis
    * MouseMotion_RotateZ - rotates the display along the Z axis
    * MouseMotion_TranslateX - translates the display along the X axis
    * MouseMotion_TranslateY - translates the display along the Y axis
    * MouseMotion_TranslateZ - translates the display along the Z axis 
    * MouseMotion_Zoom - zooms the display
    * MouseMotion_Clip - controls the position of the far and near clipping 
                        planes in a mirrored fashion
    * MouseMotion_ClipFar - controls the position of the far clipping plane
    * MouseMotion_ClipNear - controls the position of the near clipping plane
    * MouseMotion_DepthcueBegin - controls the position of the start of the 
                                  depthcueing calculation
    * MouseMotion_DepthcueEnd - controls the position of the end of the 
                                depthcueing calculation
    * MouseMotion_Contour - adjusts the contour level of the grid contours in the
                            current scope
    * MouseMotion_TextScale - adjusts the size of the text displayed in the 3D 
                              display

.. oe:function:: ViewerMove

   .. code::

      void ViewerMove(int fxnX, int fxnY, int x, int y, int oldx, int oldy, int w, int h, 
                      bool first)

   This function performs an action in the display window corresponding to a mouse 
   move event in the 3D display window. Ordinarily, this function should not need 
   to be called by the user.

.. oe:function:: ViewerPickSurfaceTrianglesGet

   .. code::

      bool ViewerPickSurfaceTrianglesGet()

   Returns whether or not picking on a surface picks individual triangles as 
   opposed to picking the entire surface. Ordinarily, this function should not 
   need to be called by the user.

.. oe:function:: ViewerPickSurfaceTrianglesSet

   .. code::

      bool ViewerPickSurfaceTrianglesSet(bool enable)

   Sets whether or not picking on a surface picks individual triangles as 
   opposed to picking the entire surface. Ordinarily, this function should not 
   need to be called by the user.

.. oe:function:: ViewerProgress

   .. code::

      OEGLProgress *ViewerProgress(const std::string &message)

   Creates and returns a progress bar display shown in the 3D window. The
   *message* parameter specifies the text associated with the progress bar.

.. oe:function:: ViewerRemoveWidget

   .. code::

      void ViewerRemoveWidget(OEGLWidget *widget, bool update)

   This function removes the specified widget from the 3D display. The *update*
   parameter specifies whether or not all the other widgets in the 3D display 
   need to be updated as a result of this change.

.. oe:function:: ViewerTextBox

   .. code::

      OEGLTextBox *ViewerTextBox(const OEPropDB::OEKey &key, int x=-1, int y=-1, 
                                 int w=-1, int h=-1)
      OEGLTextBox *ViewerTextBox(const std::string &message, int x=-1, int y=-1, 
                                 int w=-1, int h=-1)

   Creates and returns a text display widget to be shown in the 3D display. The
   parameter *message* specifies the current text. The position and dimensions
   of the widget are specified by the parameters *x*, *y*, *w*, and *h*.

.. oe:function:: ViewerUseInertiaGet

   .. code::

      bool ViewerUseInertiaGet()

   Returns whether or not the 3D display window tracks the inertia of mouse 
   movements and uses that to keep the scene spinning after the mouse button is
   released.

.. oe:function:: ViewerUseInertiaSet

   .. code::

      bool ViewerUseInertiaSet(bool state)

   Sets whether or not the 3D display window tracks the inertia of mouse 
   movements and uses that to keep the scene spinning after the mouse button is
   released.

.. oe:function:: ViewerUseKeyMapGet

   .. code::

      bool ViewerUseKeyMapGet()

   Returns whether or not the viewer is using its own internal key bindings. 
   Ordinarily, this function does not need to be called by the user.

.. oe:function:: ViewerUseKeyMapSet

   .. code::

      bool ViewerUseKeyMapSet(bool state)

   Sets whether or not the viewer is using its own internal key bindings. 
   Ordinarily, this function does not need to be called by the user.

.. oe:function:: ViewerWheel

   .. code::

      void ViewerWheel(int fxn, int x, int y, int delta)

   This function performs an action in the display window corresponding to a mouse 
   wheel event in the 3D display window. Ordinarily, this function should not need 
   to be called by the user.

.. oe:function:: ViewerWidgetUpdate

   .. code::

      void ViewerWidgetUpdate()

   Forces an update of all the display widgets in the 3D display.

.. oe:function:: WaitBegin

   .. code::

      void WaitBegin()

   This function sets the application in a waiting state.  It is used for long operations.
   Ordinarily this function should not need to be called by the user.

.. oe:function:: WaitEnd

   .. code::

      void WaitEnd()

   This function stops the application in a waiting state.  It is used for long operations.
   Ordinarily this function should not need to be called by the user.

.. oe:function:: WindowEnabledGet

   .. code::

      bool WindowEnabledGet(const std::string &windowName)

   Returns whether or not the specified window is enabled for use within VIDA.

.. oe:function:: WindowEnabledSet

   .. code::

      void WindowEnabledSet(const std::string &windowName, bool enabled)

   Sets whether or not the specified window is enabled for use within VIDA.

.. oe:function:: WindowMenuUpdate

   .. code::

      void WindowMenuUpdate()

   Updates the contents of the main *Window* menu.

.. oe:function:: WindowRegisterHotkey

   .. code::

      void WindowRegisterHotkey(const std::string &windowName, 
                                const std::string &keystroke, 
                                const std::string &pyCommand)
                                
   Registers the specified keystroke with the associated Python command in the
   specified window. If this keystroke is detected when the specified window has
   the application focus, the associated command will be run.

.. oe:function:: WindowVisibleGet

   .. code::

      bool WindowVisibleGet(const std::string &windowName)

   Returns whether or not the specified window is currently visible.

.. oe:function:: WindowVisibleSet

   .. code::

      bool WindowVisibleSet(const std::string &windowName, bool visible, 
                            const std::string &pos="")

   Sets whether or not the specified window is currently visible.


.. _builder:


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


*********************
Molecule Manipulation
*********************

|product| has the ability to both create and modify existing molecules. The
focus is primarily on small molecules, but it is not limited to small 
molecules. Molecules can only be modified in a specific *Editing* mode, more
details of which are available in the following sections.

.. _creating_molecules:

Creating Molecules
==================

A new molecule can be created from scratch in |product| by clicking on the
button in the main toolbar with the icon of a molecule overlaid with a plus
sign (see :ref:`Table: Builder Icons<figure_builder_icons>`). Clicking this 
button will open |product's| sketcher window.

.. _figure_sketcher_vida:

VIDA Sketcher Window
-----------------------

The 2D sketcher window contains a basic 2D sketching environment at 
the top and a 1D text entry mechanism below that. The 1D input mechanism provides 
a very fast way to specify a new molecule or get started with new molecule
creation. The 1D input mechanism supports SMILES, IUPAC and common names, as well 
as FASTA sequences for small peptides (sequence must be prefixed by a leading 
angle bracket (>) character). Disconnected fragments can be specified on the 1D 
input line by entering a vertical bar (|) character between the entries.  Once a 
valid molecule has been specified in the 1D area, that molecule will be depicted in the 2D sketching area.

A basic overview of the 2D sketcher can be seen in :ref:`Figure: 2D Sketcher<figure_sketcher>`


.. figure:: /_images/2D_sketcher.png
   :scale: 75
   :align: center

   **2D Sketcher**

.. list-table::
  :widths: 15 50
  :header-rows: 1
  
  * - Icon
    - Description
  * - .. image:: images/2D_sketcher_icons/pencil.png
    - **Pencil:**  This is the default drawing tool.  With the pencil icon selected (highlighted) click in the 
      main sketcher window to start drawing a new molecule.  Clicking on an atom in 
      the main sketcher window will incrementally build up a carbon chain.  The attachment points 
      are highlighted in orange.  Clicking on a bond will toggle the bond order.
      This tool can also be used to close rings.  Click on the first 
      atom and drag to the second atom where the ring will close.

      Hovering the mouse over an atom or bond highlights it orange.  Right-click on the highlighted 
      atom to access a right-click menu which allows the user to *Set Element*, *Set Formal Charge* 
      or *Delete* the selected atom/bond.  If a bond is highlighted then the 
      right-click menu offers an option to *Set Bond Order*.  There are also options to 
      *Attach...* (through an atom) or *Fuse...* (through an atom or bond) a functional group.  
      In these cases a secondary dialog opens 
      in which a SMILES string can be input of the group to be attached or fused. 
  * - .. image:: images/2D_sketcher_icons/bond.png
    - **Bond order:**  
      Clicking on a bond in the main sketcher window will cycle through the
      available bond orders for that bond.

      Bond order can also be set through the *Set Bond Order* option of the right-click menu.
      Hovering the mouse over an individual bond will temporarily highlight it orange
      and the right-click menu will operate on that bond only.  If multiple bonds are 
      selected (and therefore highlighted orange) using the *Selection* tool (below) then they
      will ALL be set to the new bond order using *Bond Order* in the right-click menu.
      Available options are 0-4 where 0 will break the bond.
  * - .. image:: images/2D_sketcher_icons/element.png
    - **Element:**  
      Click on the small arrow to open a dropdown menu and select from some commonly 
      used elements.  Clicking on an atom in the main 2D sketcher window will cause 
      that atom to be changed to the selected atom type.  In addition to the 
      commonly used atoms there is an "X" dummy atom type.  Clicking the "..." option in 
      the list opens a full periodic table of the elements from which any element 
      can be selected.

      This icon shows an image of the currently active atom type.  The default is 
      "C".

      Atoms types can also be set through the *Set Element* option of the right-click menu.
      Hovering the mouse over a single atom will temporarily highlight it orange
      and the right-click menu will operate on that atom only.  If multiple atoms are 
      selected (and therefore highlighted orange) using the *Selection* tool (below) then they
      will ALL be set to the same atom type using *Set Element* in the right-click menu.
  * - .. image:: images/2D_sketcher_icons/charge.png
    - **Charge:**  Click on the small arrow to open a dropdown and select the formal 
      charge for an atom.  Options available are -2, -1, 0, +1, +2.  With the 
      charge icon active (highlighted white) clicking on any atom in the main 
      sketcher window will modify the atom to have the currently selected charge.

      This icon displays an image of the currently active charge.  
      The default is "-2".

      Formal charge can also be set through the *Set Formal Charge* option of the right-click menu.
      Hovering the mouse over an individual atom will temporarily highlight it orange
      and the right-click menu will operate on that atom only.  If multiple atoms are 
      selected (and therefore highlighted orange) using the *Selection* tool (below) then they
      will ALL be set to the new formal charge using *Set Formal Charge* in the right-click menu.
      This method provides a wider range of charge values than can be accessed using the *Charge* icon.
  * - .. image:: images/2D_sketcher_icons/rings.png
    - **Rings:**  
      Click on the small arrow to open a dropdown menu and select from some commonly 
      used rings, such as benzene, cyclopropane and cyclohexane. The selected  
      ring can be added to the growing molecule multiple times.  The attachment atom or fusion bond 
      is highlighted in orange and alternative fusion options can be accessed using 
      the mouse scroll wheel.  

      This icon shows an image of the currently active ring template.  The default is benzene.

.. list-table::
  :widths: 15 50
  :header-rows: 0

  * - .. image:: images/2D_sketcher_icons/templates.png
    - **Templates:**  
      Click on the small arrow to open a dropdown menu and select from numerous 
      predefined template functional groups, linkers and rings.  There is also an 
      option to define a Custom functional group.  This opens a new dialog into 
      which a SMILES string can be input.  The selected functional group, linker or 
      ring can be added to the growing molecule multiple times.  The attachment atom or fusion bond 
      is highlighted in orange and alternative fusion options can be accessed using 
      the mouse scroll wheel.

      This icon shows an image of the currently active functional group, linker or 
      ring.  The default is "C". 

      With the default "C" functional group selected clicking on an atom in the 
      main sketcher window will build up a carbon chain.  This tool can also be 
      used to close rings.  Click on the first atom and drag to the second atom 
      where the ring will close.
  * - .. image:: images/2D_sketcher_icons/stereo.png
    - **Stereochemistry:**  Click on the small arrow to open a dropdown and select 
      atom and bond CIP stereochemistry options.  Available options are R and S 
      for chiral atoms and E or Z for chiral bonds.  There is also an option to 
      invert the current stereochemistry.

      This icon displays an image of the currently active option.  
      The default is "Invert".

      If no stereochemistry is already set then clicking an atom with the *Invert* option 
      selected will initially set the stereochemistry to R and subsequent clicks with *Invert* will
      toggle between R and S.  In the case of bonds where no stereochemistry is already set the 
      *Invert* option will initially set the stereochemistry to E and then toggle between E and Z.
      Thus *Invert* can be considered a 'one stop shop'.
  * - .. image:: images/2D_sketcher_icons/select.png
    - **Select:**  With the arrow icon highlighted drag to draw a loop around the 
      atoms to be selected or Shift-click or Ctrl-click to incrementally select 
      multiple atoms and/or bonds.  The selected atoms and bonds will be 
      highlighted in orange.  

      A right-click menu allows the user to *Set Element*, *Set Formal Charge* 
      or *Delete* the selected atom(s).  This operation acts on ALL the selected atoms 
      *e.g.* they would all get the same charge.  If only bonds are selected then the 
      right-click menu offers an option to *Set Bond Order*.  There are also options to 
      *Attach...* (through an atom) or *Fuse...* (through an atom or bond) a functional group.  
      In these cases a secondary dialog opens 
      in which a SMILES string can be input of the group to be attached or fused.
  * - .. image:: images/2D_sketcher_icons/wand.png
    - **Clean up the display:** This tool is useful after portions of the molecule have been 
      deleted, especially if a ring has been cleaved.  It uses an OEDepict algorithm to 
      redraw the molecule according to an internal set of rules.
  * - .. image:: images/2D_sketcher_icons/undo.png
    - **Undo:**  Clicking on this icon will undo the last action in the main sketcher window.  
      Repetitive use will undo actions further back in the history.  *Ctrl-Z* is a keyboard
      shortcut that can also be used.
  * - .. image:: images/2D_sketcher_icons/eraser.png
    - **Eraser:**  Delete atoms and/or bonds by selecting the eraser tool and clicking on the 
      atom or bond to be deleted.

      Atoms and bonds can also be deleted through the *Delete* option of the right-click menu.
      Hovering the mouse over a single atom or bond will temporarily highlight it orange
      and the right-click menu will operate on that atom/bond.  If multiple atoms/bonds are 
      selected (and therefore highlighted orange) using the *Selection* tool (below) then they
      will ALL be deleted using *Delete* in the right-click menu.


.. _editing_molecules:

Editing Molecules
=================

Molecules can only be changed in |product| when in *Editing* mode. Only a 
single molecule can be in *Editing* mode at a time. To put a molecule into
*Editing* mode, select the "Edit" option from the right-click popup menu or
click on the button in the main toolbar with the icon of a molecule overlaid 
with a pencil (see :ref:`Table: Builder Icons<figure_builder_icons>`).

.. _figure_builder_icons:

.. list-table:: **Builder Icons**
  :widths: 15 50
  :header-rows: 1

  * - Button
    - Description
  * - .. image:: images/builder/icon_open_2dsketcher.png
        :align: center
    - **Sketch new molecule:** Opens the 2D Sketcher to allow creation of a 
      new molecule.
  * - .. image:: images/builder/icon_open_builder.png
        :align: center
    - **Edit current molecule:** Places the current active molecule into the
      3D Builder and 2D Sketcher.
  * - .. image:: images/builder/icon_accept_builder.png
        :align: center
    - **Save as new molecule:** Saves the edited molecule as a new entry while
      remaining in Editing mode.
  * - .. image:: images/builder/icon_cancel_builder.png
        :align: center
    - **Accept edits:** Leaves Editing mode and keeps the changes made to the
      edited molecule.
  * - .. image:: images/builder/icon_builder_saveas.png
        :align: center
    - **Cancel edits:** Leaves Editing mode and cancels any unsaved edits.

On entering *Editing* mode, the "Open 3D Builder" icon will be replaced by one of 
a molecule with a green "+" sign.  This icon will close the Builder and keep any changes
made to the molecule during editing.  An additional button also appears in the toolbar
with the icon of a molecule overlaid with a red "X". Clicking on this button will
cancel out all of the changes made to the molecule and will restore the 
molecule back to its original state. 

When |product| enters *Editing* mode, a number of builder tools appear in
the 3D window, and the Sketcher window opens, allowing editing of a molecule
in either 2D or 3D.  The 2D and 3D editing functions are roughly equivalent,
and are synchronized, so that selecting a tool in the 3D window will select 
the corresponding tool (where possible) in the 2D sketcher and vice versa.  
The various building tools are discussed in detail in :ref:`creating_molecules`.

.. _figure_edit_molecule:

.. figure:: /_images/3D_builder.png
   :scale:  75
   :align:  center
   
   **Molecule Editing**

.. _builder_icon_table:

.. list-table::
  :widths: 15 50
  :header-rows: 1
  
  * - Icon
    - Description
  * - .. image:: images/builder/icon_select.png
    - **Select:**  This is the default selection mode.  With the icon highlighted 
      click on the atoms or bonds to be selected or Shift-click or Ctrl-click to 
      incrementally select multiple atoms and/or bonds.  The selected atoms and bonds 
      will be highlighted in orange.  Double click to select whole functional groups
      or molecules.  Select a group of atoms and bonds within a rectangle using 
      right-click and drag.
  * - .. image:: images/builder/icon_information.png
    - **Information:**  Clicking on an atom or bond provides information such as
      atom type, 3D Cartesian coordinates, bond type and bond length.
  * - .. image:: images/builder/icon_center.png
    - **Center:**  Select the center tool and then click on an atom to center the view
      on that atom
  * - .. image:: images/builder/icon_distance_angle_torsion.png
    - **Monitors:**  Place monitors for distance (2 atoms), angle (3 atoms) or torsion
      (4 atoms).  Click sequentially on the atoms to be included in the monitor.  Before
      the last atom is clicked hovering over an atom will display a temporary monitor.  
      Clicking on the atom makes the monitor persist.
  * - .. image:: images/builder/icon_add_label.png
    - **Add Labels:**  With the tool selected click on an atom or bond to add label text.
  * - .. image:: images/builder/icon_erase.png
    - **Delete:**  Delete atoms and/or bonds by selecting the eraser tool and clicking on the 
      atom or bond to be deleted.  To delete groups of atoms or bonds first select them 
      with the Selection tool and then either use the *Delete* option in the right-click
      menu or use the *Delete* keyboard key.
  * - .. image:: images/builder/icon_add_fragment.png
    - **Rings:**  
      Click on the small arrow to open a dropdown menu and select from some commonly 
      used rings, such as benzene, cyclopropane and cyclohexane. The selected  
      ring can be added to the growing molecule multiple times.  There is also an 
      option to define a Custom functional group.  This opens the 2D sketcher into 
      which the functional group can be sketched or a SMILES string can be input.    

      This icon shows an image of the currently active ring template.  The default is benzene.
  * - .. image:: images/builder/icon_atom.png
    - **Element:**  
      Click on the small arrow to open a dropdown menu and select from some commonly 
      used elements.  Clicking on an atom in the main 3D window will cause 
      that atom to be changed to the selected atom type.  In addition to the 
      commonly used atoms there is an "X" dummy atom type.  Clicking the "..." option in 
      the list opens a full periodic table of the elements from which a wider range
      of elements can be selected.

      This icon shows an image of the currently active atom type.  The default is 
      "C".
  * - .. image:: images/builder/icon_bond.png
    - **Bond order:**  
      Clicking on a bond in the main 3D Builder window will cycle through
      the available bond orders for that bond.
  * - .. image:: images/builder/icon_charge.png
    - **Charge:**  Click on the small arrow to open a dropdown and select the formal 
      charge for an atom.  Options available are -2, -1, 0, +1, +2.  Other formal
      charges not in this range can be set with the "..." option.  With the 
      charge icon active (highlighted white) clicking on any atom in the main 
      sketcher window will modify the atom to have the currently selected charge.

      This icon displays an image of the currently active charge.  
      The default is "-2".
  * - .. image:: images/builder/icon_stereochemistry.png
    - **Stereochemistry:**  Click on the small arrow to open a dropdown and select 
      atom and bond CIP stereochemistry options.  Available options are R and S 
      for chiral atoms and E or Z for chiral bonds.  There is also an option to 
      invert the current stereochemistry.

      This icon displays an image of the currently active option.  
      The default is "Invert".

When a molecule enters *Editing* mode, |product| adds explicit hydrogens to the
molecule to properly fill out the valences. In addition, labels are added to 
both atoms and bonds to indicate stereochemistry and formal charge.

A molecule can be edited by either setting the mouse mode using the buttons on 
the right or by clicking on one or more atoms/bonds and then selecting the 
desired operation from the context sensitive right-click menu. The menu provides the 
following choices.  Some options are available only when atoms are selected and
others only when bonds are selected.

.. _builder_menu_table:

.. list-table:: **Builder Right-Click Menu**
  :widths: 10 50
  :header-rows: 0

  * - **Center**  
    - Centers the highlighted atom(s) in the display.
  * - **Set Element**  
    - Atoms only. Select the desired atom type from a Periodic Table.  This atom type 
      will be applied to all the selected atoms.
  * - **Set Formal Charge**  
    - Atoms only. Select the formal charge for all the selected atoms.
  * - **Set Torsion**  
    - Specify a torsion angle for a 4-atom set.
  * - **Set Bond Order** 
    - Bonds only. Specify the desired bond order.  Applies to all the 
      highlighted bonds.
  * - **Set Bond Length** 
    - Bonds only.  Specify the desired bond length.  
      The new length is applied to all the highlighted bonds.
  * - **Modify Torsion** 
    - Bonds or 4-atom sets only.  Use the keyboard *up* and *down* arrow keys
      or the mouse scroll wheel to increase and decrease the bond torsion.
  * - **Modify Angle** 
    - 3-atom sets only. Use the keyboard *up* and *down* arrow keys to
      increase and decrease the bond angle.
  * - **Sprout Methyl** 
    - Atoms only. If the selected atom has an open valence (i.e. bond to H)
      this option will replace the H-atom with a methyl group.
  * - **Create Bond**  
    - Atoms only. Make a new bond between two selected atoms with open valences.
  * - **Attach** 
    - Atoms only.  Opens the 2D sketcher to input the fragment to be attached
      to the highlighted atom.
  * - **Fuse** 
    - Opens the 2D sketcher to input the fragment to be fused to the 
      highlighted atom or bond.
  * - **Measure Length** 
    - Bonds only.  Displays a monitor with the bond length. 
  * - **Measure Torsion** 
    - Bonds only.  Displays a monitor for the torsion around the bond(s).
  * - **Measure Angle** 
    - Atoms only. Displays a monitor with the bond length.
  * - **Minimize** 
    - Atoms only.  Minimize the highlighted portion of the molecule using
      the MMFF94 or MMFF94s force field.
  * - **Delete**  
    - Delete the highlighted atoms or bonds.  Open valences will be filled
      with H-atoms.
  * - **Cancel Editing**  
    - Exit the 3D builder without keeping any of the changes.
  * - **Finish Editing**  
    - Exit the 3D builder and accept the edits.
  * - **Create**  
    - A sub-menu provides options for creating molecular or accessible
      surfaces or electrostatic grids.
  * - **Bookmarks**  
    - A sub-menu provides options to add or organize bookmarks and define
      animation preferences.
  * - **Delete Visible Monitors**  
    - Deletes all visible monitors (angle, length, torsion)
      from the 3D display.

Independent Rotation/Translation of Molecules
---------------------------------------------

It is possible to rotate and translate a molecule in *Editing* mode independently from
all other molecules in |product|, by holding down the *Ctrl* key (*Command* key on the 
Macintosh) during rotation or translation actions.  Any selected atoms will define the 
center of rotation.  If no atoms are selected, the centroid of the molecule is used for 
the center of rotation.

.. _editing_minimization:

Minimization
------------

An entire molecule or just a subset of a molecule can be minimized using the 
MMFF94 or MMFF94s forcefield. This minimization takes place in a vacuum and does not take 
into account any context (such as a protein active site).

.. _figure_icon_minimize:

.. figure:: /_images/icon_minimize.png
   :align:  center
   
   **Minimize Tool**

To minimize a molecule, the molecule of interest must be in *Editing* mode. 
Once *Editing* mode has been enabled for a molecule, a button with a magic wand
icon (see :ref:`Figure: Minimize<figure_icon_minimize>`) will appear on the right hand 
side of the 3D display. Clicking on this 
button will cause the entire molecule or just the selected subset of the 
molecule to be minimized. Like all other procedures in |product|, the 
minimization process can be undone.

Monitors
--------

Angle, distance, and torsion monitors can be added to individual molecules to
display as well as modify the associated properties. Monitors can be created 
using the monitor mouse mode (available from the toolbar on the left side of
the :ref:`3D display<builder_icon_table>`). Torsion monitors can also be created by first selecting a 
single bond, three adjacent bonds, or four adjacent atoms and then choosing
the *Modify Torsion* option in the right-click menu.

The value associated with a distance or angle monitor can be changed by selecting the
monitor of interest and then scrolling the mouse wheel. By default, the smaller
side of the molecule will be the one modified by these changes; however, if the
*Ctrl* key is held down while using the mouse wheel, the larger side will be
modified instead.  

In the builder, torsion monitors are added in pairs, with one monitor at each end
of the selected bond.  The monitor you select will determine which end of the bond
will rotate.  (By default the monitor on the smaller side of the molecule is
selected.)

To rotate torsions within a ring, create a torsion monitor on a ring bond, then
select one other bond in the ring as a "closure bond".  The closure bond will
stretch and deform as you adjust the torsion.  When finished with the adjustment,
you will probably want to minimize the ring structure using the *Minimize Tool* 
(see :ref:`Figure: Minimize<figure_icon_minimize>`).

The figure below illustrates adjusting a ring torsion to convert a cyclohexyl group from chair to boat conformation.  The active torsion monitor and closure bond are shown selected.

.. _figure_chair_boat:

.. figure:: /_images/pucker_chair_boat.png
   :scale:  100
   :align:  center

   **Ring Pucker Conversion.**  *Interconversion of a ring from chair to boat conformation can be performed by rotating a single ring torsion.*

Torsion monitors can also be used to convert between equatorial and axial 
substitutions of a ring, as shown in the following figure.  In this example,
a single torsion is rotated in two steps, using two different closure bonds.

.. _figure_equat_axial:

.. figure:: /_images/pucker_equat_axial.png
   :scale: 100
   :align: center

   **Equatorial to Axial Conversion.**  *An equatorial substitution on a 
   cyclohexyl ring is converted to an axial substitution by adjusting a 
   ring torsion.  In step 3 a new closure bond is selected, and the torsion
   rotated farther, until a chair conformation is obtained.*

When adjusting torsions, the default step size is 10 degrees; however, a finer
resolution of 1 degree can be achieved by simultaneously holding down the 
*Shift* key while using the mouse wheel.


.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



.. _vida_citation:

************
Citation
************

.. note:: To cite VIDA please use the following:

    VIDA <vida_version>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com

    `The version number is available on the front page of the VIDA section <https://beta-docs.nm.eyesopen.us/applications/vida/index.html>`_.

.. _custom_views:

************
Custom Views
************

There are a number of very common uses of the 3D display which can take some
effort to set up correctly by hand. For this reason, a number of automatically 
setup custom views are available. These custom views are designed to quickly 
show in an expected and logical manner the results of various different 
applications. Support currently exists for viewing FRED, ROCS, or EON results. 
These views can be accessed by choosing the desired option in the *Tools* menu. 
An example of the interface to each of these custom views can be seen in
:ref:`Table: Custom View Inputs<figure_custom_views>`.

.. _figure_custom_views:

.. list-table:: Custom View Inputs
  :widths: 30 30 30
  :header-rows: 0
  
  * - .. image:: images/cvdocking.png
        :align: center
    - .. image:: images/cveon.png
        :align: center
    - .. image:: images/cvrocs.png
        :align: center
  * - FRED Results View
    - EON Results View
    - ROCS Results View

The first thing to notice about all the views are the molecule choice buttons. 
The *FRED View* has three, while the *EON* and *ROCS Views* 
have only two. Clicking on the *Select* button next to any of these allows
selection of a molecule from the currently loaded set. Clicking on the 
*Browse* button allows selection of a molecule from a file on disk. 
Following the molecule choice buttons are various check boxes for customizable 
display options for that view.

FRED View
=========

The first view is the *FRED View*, the results of which can be seen in 
:ref:`Figure: FRED Results View<figure_fred_results>`. This view sets up the 
protein's active site 
(the region around the reference ligand) with a cropped electrostatic surface 
and the nearby molecular structure. Optionally, it will also display the 
protein's associated ribbon.  Finally, it labels the c-alpha carbons on the 
protein with residue information.

.. _figure_fred_results:

.. figure:: /_images/cvdockingeg.png
   :scale:  75
   :align:  center
   
   **FRED Results View**

The *FRED View* then places the reference ligand in the active site and 
colors the carbons using the "Reference Color" (the default is green).  Finally, 
it loads the optional results and makes the first molecule in that list the 
*Focused* molecule.  

The *FRED View* has several optional parameters, as shown in 
:ref:`Table: Custom View Inputs<figure_custom_views>`.
Hydrogen bonds, protein ribbons, residue labels, and the protein surface can 
all be toggled using the checkboxes at the bottom of the dialog. Furthermore, 
there are additional preferences with respect to the distance cutoffs used that 
can be found in the application preferences.

The *FRED View* also adds a custom pane to the Style 
Control to enable more specific interactions with the scene generated by *FRED 
View* (see :ref:`Figure: FRED Pane<figure_fred_pane>`).

.. _figure_fred_pane:

.. figure:: /_images/cvfred_pane.png
   :scale:  75
   :align:  center
   
   **FRED Pane**

The custom pane contains a row of nine buttons above a "Setup" button
which relaunches the original *FRED View* dialog 
(see :ref:`Table: Custom View Inputs<figure_custom_views>`). 
The first eight buttons toggle the display of
hydrogen bonds to the protein, residue labels, ribbons, active site surface,
the FRED inner docking contour, the FRED outer docking contour, the reference
ligand, and any other extra molecules that might be associated with the protein
such as waters or co-factors. The last button toggles the display of FRED 
docking constraints (if any) and furthermore contains a drop down menu with a 
list of all the individual constraints.

.. note::

   Receptors in OEDesignUnit entries are not compatible with *FRED View* at this time

EON View
========

The *EON View* has two molecule pickers, one for the result set, and one 
for the optional reference molecule (see :ref:`Table: Custom View Inputs<figure_custom_views>`.  
Below these are the parameters to the 
*EON View*.  The first checkbox specifies whether or not to use the first 
result as the reference molecule or not.  The second checkbox is the Tiled 
display option, which sets the application into Tiled mode with the various 
results displayed in their own individual panes. Next to this checkbox is a
numeric entry box to set the max number of tiles in the display. The third
check box toggles whether or not to load the spreadsheet display as well.
Finally, the last checkbox toggles whether to display the Style Control. This
ensures that the *EON* pane in the Style Control is visible, allowing scrolling
through the results with that pane's slider.

The *EON View* places the reference molecule in the first tile and colors
that molecule using the "Reference Color" (the default is green). The other 
molecules are displayed in their own tiles. If the molecules contain 
electrostatic Tanimoto (ET) grids (produced by EON with the -writegrid option),
each molecule will have these grid contours displayed for comparison with 
the reference. An example of this can be seen in 
:ref:`Figure: EON Results View<figure_eon_results>`.

.. _figure_eon_results:

.. figure:: /_images/cveoneg.png
   :scale:  75
   :align:  center
   
   **EON Results View**

As mentioned previously, the 
*EON View* adds a custom pane to the Style Control to enable more 
specific interactions with the scene generated by *EON View* (see
:ref:`Figure: EON Pane<figure_eon_pane>`).  

.. _figure_eon_pane:

.. figure:: /_images/cveon_pane.png
   :scale:  75
   :align:  center
   
   **EON Pane**

The custom pane contains a row of two buttons and a slider followed by a
"Setup" button which relaunches the original *EON View* dialog (see 
:ref:`Table: Custom View Inputs<figure_custom_views>`). The first 
button toggles the display of the reference
molecule. The second button toggles the display of any ET grids that were 
attached to the molecules by EON.  The slider allows scrolling through the 
results.

ROCS View
=========

The last custom view is the *ROCS View*. This view, like the 
*EON View*, has two 
molecule pickers, one for results and one for a reference molecule (see 
:ref:`Table: Custom View Inputs<figure_custom_views>`). It also has
all of the same options as the EON view.

The *ROCS view* colors the reference molecule using the "Reference Color"
(the default is green) as well as making that molecule *Locked*. The rest
of the results are either overlaid in that same pane or displayed in their own
individual pane overlaid on just the reference depending on whether or not
Tiled mode was specified. An example of this can be seen in 
:ref:`Table: Custom View Inputs<figure_custom_views>`.

.. _figure_rocs_results:

.. figure:: /_images/cvrocseg.png
   :scale:  75
   :align:  center
   
   **ROCS Results View**

As mentioned previously, the 
*ROCS View* adds a custom pane to the Style Control to enable more 
specific interactions with the scene generated by *ROCS View* (see 
:ref:`Figure: ROCS Pane<figure_rocs_pane>`).

.. _figure_rocs_pane:

.. figure:: /_images/cvrocs_pane.png
   :scale:  75
   :align:  center
   
   **ROCS Pane**

The custom pane contains a toggle button, a slider, and a "Setup" button
which relaunches the original *ROCS View* dialog (see 
:ref:`Table: Custom View Inputs<figure_custom_views>`). The 
toggle button toggles the display of the reference molecule. The slider
allows scrolling through the results.


.. _display_2d:


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


**********
2D Display
**********

2D molecular depictions are provided using OpenEye's **OEDepict** toolkit. A
large number of options are available in the applications preferences to 
customize how the depictions are drawn. 

.. _figure_molecule_2d:

.. figure:: /_images/molecule_2d.png
   :scale:  75
   :align:  center
   
   **Molecule Depiction**

Depictions are drawn in color on a 
white background by default as seen in 
:ref:`Figure: Molecule Depiction<figure_molecule_2d>`, but other
color schemes are available and can be seen in 
:ref:`Table: Depiction Colors<figure_depict_colors>`.

.. _figure_depict_colors:

.. list-table:: **Depiction Colors**
   :widths: 25 25 25 25
   :header-rows: 0
  
   * - .. image:: images/depict_cob.png
         :align: center
     - .. image:: images/depict_cow.png
         :align: center
     - .. image:: images/depict_wob.png
         :align: center
     - .. image:: images/depict_bow.png
         :align: center
   * - *Color on black*
     - *Color on white*
     - *White on black*
     - *Black on white*

As might be expected, 2D depictions of this nature only make sense for small 
molecules (< 255 atoms in this case). For proteins, an amino acid sequence
view is displayed instead (see :ref:`Figure: Protein Sequence<figure_sequence>`).

.. _figure_sequence:

.. figure:: /_images/sequence.png
   :scale:  100
   :align:  center
   
   **Protein Sequence**

Preview vs. Viewer
==================

The 2D display comes in two flavors - the 2D Preview and the 2D Viewer. There
are two differences between these two windows. First, the 2D Preview can only 
show a single molecule -- the *Focused* one -- whereas the 2D Viewer can show 
several in a grid if the application is in Tiled mode. Secondly, the 2D Viewer 
can be set as the main window, but the 2D Preview cannot. The 2D Viewer is 
shown in :ref:`Figure: Molecule Depiction<figure_molecule_2d>`.

The 2D Preview is best suited for use as a small secondary display of the 
*Focused* molecule while otherwise browsing. The 2D Viewer often requires 
more screen real estate and is usually best suited as the main window.

Interaction
===========

2D selection behaves much like selection in the 3D display. Left clicking will 
select an individual atom, bond, or residue (if in sequence mode). When viewing 
a depiction, the right mouse button allows lasso style selection, as in the 3D 
display. When viewing a sequence, holding down the *Shift* key when selecting 
will allow selection of a continuous range of residues.

The current selection is reflected in the coloring of the 2D depiction. There 
may be slight variations between the depicted selection in 2D and 3D due to the 
difference in how hydrogens are drawn.

.. _advanced_depiction:

Advanced Depiction Options
==========================

Some advanced options for molecular depictions are available in the Advanced 
Depiction Options dialog 
(see :ref:`Figure: Advanced Depiction Options<figure_adv_depict_opts>`), which
can be accessed through the *Data* menu.

Through this dialog, it is possible to add property maps to depicted molecules
in the 2D Viewer and Spreadsheet using the **Grapheme** toolkit.  Additionally, 
this dialog allows the designation of reference template molecules that can be 
used to align 2D depictions to a common orientation.  The reference templates
can also be used to highlight matching substructures in depicted molecules.

.. _figure_adv_depict_opts:

.. figure:: /_images/depict_advanced.png
   :scale:  75
   :align:  center
   
   **Advanced Depiction Options**

Atom property map displays are enabled by choosing one of the Atom Property 
Map options on the left of the dialog.  Three of the properties, 
*Partial Charge*, *XLogP*, and *TPSA*, |product| will calculate internally.
To display property maps for other atom-level properties, select the
*Custom* option and specify a generic data tag to use for property map displays.
The atoms must have real-valued generic data on them for the *Custom* option to
work.

Reference molecule templates can be pasted into the dialog or sketched, and 
multiple templates can be specified.  The first template matching 
a molecule will be used for alignment and highlighting in that molecule's 
depictions.

If *Align to Reference* is checked, molecules in the 2D Viewer and spreadsheet 
will be aligned to match the orientation of the first matching reference
template.  If *Hightlight Match* is checked, the part of the depicted molecule
that matches the template will be highlighted using the color shown in the 
Reference Templates list.

Individual templates can be enabled or disabled using the checkbox next to the 
molecule in the Reference Templates list.  New templates can be added, and
selected templates deleted, using the "+" and "-" buttons below the
Reference Templates list.



.. _display_3d:


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


**********
3D Display
**********

The 3D display is the primary visualization interface available to the 
user (although it is not the only one, there is also a spreadsheet view and 2D views). 
The purpose of the 3D display is to allow the user to view and interact 
with molecules, grids, and surfaces.

User Interaction
================

The primary interface mechanism to the 3D display is the mouse which is 
discussed in detail below. However, the large number of potential 
operations that can be performed in the 3D display necessitate an 
additional mechanism of interaction besides the simple use of mouse buttons 
and popup menus. For this reason a separate peripheral window is provided to 
access these operations. This window is called the :ref:`Style Control<style_control>` and is 
discussed below.

Mouse
-----

As described above, the mouse is considered to be the primary interface 
mechanism to the 3D display. The details of how to use the mouse to interact 
with the 3D display are listed here. A three (or two) button mouse is 
recommended for use; however, support for a single button mouse is available
on macOS. Holding down the *Ctrl* key while clicking or pressing the mouse 
button will emulate using the *Right* mouse button on a three button mouse.

For users not comfortable or familiar with the mouse interactions described
below, |product| can be made to emulate the mouse behavior of many other 
applications including: Coot, Insight, Maestro, MOE, O, Quanta, PyMol, RasMol, 
and SYBYL. The desired mouse map can be set in the application preferences in 
the *3D Display* section (:ref:`Figure: Mouse Map Preferences<figure_mouse_map>`). 
Please note that not all the functionality 
described below is available in the emulated mouse modes, nor is all of the 
functionality of the emulated applications available in |product|.

.. _figure_mouse_map:

.. figure:: /_images/mouse_map.png
   :scale:  75
   :align:  center
   
   **Mouse Map Preferences**

Selection
---------

Objects in the display can be selected by clicking on them using the *Left* 
mouse button. The selection is cleared between button clicks (or by clicking 
in the background) unless the *Shift* or *Ctrl* key is also held 
down when clicking. If a single atom on a surface has been selected, holding
down the *Shift* key and selecting a second atom will select the 
shortest path of vertices between the two selected end points.

Double-clicking using the *Left* mouse button expands the current 
selection to the next logical grouping. For instance, double-clicking on a 
selected atom in a protein will expand the selection to include all of the 
atoms in the same residue as the original selected atom. Double-clicking on 
the selected set again will expand the selection to include either the entire 
chain if there are multiple chains, otherwise it will include the entire 
molecule.

Selection can also be performed using a lasso style selection method by holding
down the *Right* mouse button and moving the mouse in the window to define 
a selection rectangle (a dotted rectangle will be displayed on the screen as 
you do this). Releasing the *Right* mouse button will select all of the 
atoms and bonds inside of the rectangle. The previous selection will be cleared 
unless the *Shift* or *Ctrl* key is also held down while moving 
the mouse. Lasso style selection of surfaces and grids is not currently 
supported. 

Additional methods of selection are available in the *Select Menu* pane of 
the :ref:`Style Control<style_control>`  and the *Select Menu*.

Rotation
^^^^^^^^^^^^^

The scene can be rotated in three dimensions by holding down the *Left* 
mouse button and moving the mouse in the window. These movements will emulate 
rotation using a trackball.

The scene can also be rotated around just the Z axis by holding down the 
*Alt* key and the *Left* mouse button simultaneously.

Translation
^^^^^^^^^^^^^

Using the mouse, the scene can be translated in the XY plane by holding down the
*Shift* key and the *Left* mouse button simultaneously. Translation 
along the Z axis can be performed by holding down the *Alt* key, 
*Shift* key, and the *Left* mouse button simultaneously. The scene can 
also be translated along the Z axis by holding down the *Alt* key while 
using the mouse wheel.

Using the keyboard, the scene can be translated horizontally in the display by
pressing either the *A* key or *D* key which translate to the left 
and to the right respectively.

Scale/Zoom
^^^^^^^^^^^^^

The scene can be scaled (or zoomed) by holding down the *Middle* mouse 
button by itself, the *Left* and *Right* mouse buttons together, or by using 
the mouse wheel. Any of these three modes will scale the scene. Multiple modes 
are provided for convenience and to accommodate the many varied mouse 
configurations in existence.

The scene can also be scaled using the *W* and *S* keys on the 
keyboard.

Text Scale
^^^^^^^^^^^^^

The scale of the text displayed in the scene can be controlled by using the
mouse wheel while holding down the *Ctrl* key. 

Clipping
^^^^^^^^^^^^^

The position of the near and far clipping (or slabbing) planes can be 
controlled using the mouse wheel while holding down both the *Ctrl*
and *Shift* keys. Both planes are moved simultaneously and mirror 
each other's position. It is important to note that slabbing must already
be enabled for these operations to actually be performed.

The clipping planes can be adjusted independently by holding down the *Alt*
key with one of the *Ctrl* or *Shift* keys corresponding to the far and near
clipping planes respectively.

Contour Level
^^^^^^^^^^^^^

The contour level of the grids in the default scope can be adjusted using the
mouse wheel while simultaneously holding down the *Shift* key. Each 
incremental turn on the mouse wheel corresponds to an increase or decrease in
the contour level by 0.1.

Label
^^^^^^^^^^^^^

Informative labels can be displayed about atoms and bonds (as well as surfaces 
and grid contours) underlying the current mouse position if the *Ctrl* key 
is pressed while moving the mouse (no mouse button need be depressed) on most 
platforms. On the Mac, this behavior is obtained by holding down the *Alt* 
key instead of the *Ctrl* key.

Additional methods of labeling atoms and bonds are available in the 
*Style* pane of the :ref:`Style Control<style_control>` .

Menu
^^^^^^^^^^^^^

A context sensitive popup menu can be generated by clicking in the window 
while holding the *Right* mouse button down. This menu will contain 
operations that can be performed on those objects associated with the context
when the popup menu was generated.

.. _style_control:

Style Control
-------------

The Style Control is a separate peripheral window which is provided to enable
additional interactions with the 3D display. The Style Control is a vertical 
window consisting of many individual panes. Each pane provides its own set
of functionality. The display of the individual panes can be toggled by 
clicking on the title bar of the pane of interest. In addition, individual
panes can be "torn off" to act as top-level windows by clicking on the "+"
icon in the top right of the title bar. When the pane is torn off the "+" icon
becomes a "-" icon which when clicked hides the "torn off" window. The 
specific details of the individual panes are listed below.

Color
^^^^^^^^^^^^^

|product| provides a wide array of coloring schemes as can be seen in the color
pane (see 
:ref:`Figure: Color Pane<figure_color_style>`). The first button (with the color wheel
icon) prompts the user to select a specific color which will be applied to all 
of the objects in the current scope. The second button (with the molecule 
overlaid on a color wheel) prompts the user to select a specific color that 
will be applied to all molecules in the current scope. In addition, this button 
contains a drop down menu of molecule specific coloring schemes which can be 
applied. Detailed information about the individual color schemes can be found 
in :ref:`molecule_colors`. The third button (with the surface 
overlaid on a color wheel) prompts the user to select a specific color that 
will be applied to all surfaces in the current scope. In addition, this button 
contains a drop down menu of surface specific coloring schemes which can also 
be applied. Detailed information about the individual color schemes can be 
found in :ref:`surface_colors`. The fourth button (with the 
grid overlaid on a color wheel) prompts the user to select a color that will 
be applied to all grid contours in the current scope. The fifth button (with 
the "U" icon overlaid on a color wheel) assigns a unique color to every 
object in the current scope. The last button restores the original color of 
all the objects in the current scope. More details about the specific coloring 
schemes can be found below.

.. _figure_color_style:

.. figure:: /_images/color_style.png
   :scale:  75
   :align:  center
   
   **Color Pane**

Beneath the buttons is a slider which can be used to adjust the transparency
of surfaces (see 
:ref:`Table: Surface Transparency<figure_surface_transparency>`) and grid contours. The slider 
values range from 0 (completely opaque) to 100 (completely transparent). The 
specified transparency value is applied to all surfaces and grid contours in 
the current scope. However, if a part of a surface is selected, the 
transparency will only be applied to the selected region as can be seen in the
second figure in 
:ref:`Table: Surface Transparency<figure_surface_transparency>`.

.. _figure_surface_transparency:

.. list-table:: Surface Transparency
  :widths: 30 30
  :header-rows: 0
  
  * - .. image:: images/surftrans.png
        :align: center
    - .. image:: images/surftrans_partial.png
        :align: center
  * - Transparent surface 
    - Partially transparent surface

.. _style_control_selection:

Selection
^^^^^^^^^^^^^

The simplest mechanism to perform a selection is to click on the object of 
interest in the 3D display using the mouse. However, a number of additional 
selection mechanisms are available in the selection pane as can be seen in 
:ref:`Figure: Selection Pane<figure_selection_style>`.

.. _figure_selection_style:

.. figure:: /_images/selection_style.png
   :scale:  75
   :align:  center
   
   **Selection Pane**

In the top row of the selection pane, there are seven individual
buttons. The first button with the "A" icon selects all of the currently 
visible molecules. The second button with the partially selected molecule icon
performs a selection based on a substructure query. Clicking on this button 
will launch a query dialog which allows the user to specify a substructure 
query. The substructure can be entered as a SMARTS pattern, selected from a
large number of predefined patterns, or can be specified using a common or 
IUPAC name which will be converted to a structure using OpenEye's **Lexichem** 
toolkit. All atoms in the current scope matching the specified pattern will be
selected. If the current scope is set to *All* and more than 50 molecules
match the pattern, the user will be prompted as to whether to *Mark* the 
matching structures instead of selecting them, as being selected would make them 
visible.

The third button inverts the current selection, unselecting everything that
was selected and selecting everything that is currently visible but was not
previously selected. The fourth button selects everything within a defined
radius of the current selected set (the default is 5 Angstroms). The fifth 
button selects everything within a user specified radius of the current
selected set. This radius is specified by the slider in the bottom row of the
pane. The sixth button selects everything outside of the same user specified
radius of the current selected set. It is important to note that these distance
based selection mechanisms expand their selected sets to include entire 
residues in the event that only a portion of a residue is included within the
radius. 

The last button contains a drop down menu which has different options based on
the current selection. If a molecule is selected it contains the following 
options: "Hide Outside", "Hide Inside", and "Restore". Selecting one of 
these options will hide all of the atoms and bonds outside the current slider
specified radius, hide all of the atoms and bonds inside the current slider
specified radius, or unhide any previously hidden atoms and bonds respectively.
If a surface is the options are: "Crop Outside", "Crop Inside", and 
"Restore". Selecting one of these options will crop away the unselected portion
of the surface, crop away the selected portion of the surface, or restore the
surface to its original state respectively. Examples of cropped surfaces can be
seen in :ref:`Table: Surface Cropping<figure_surface_cropping>`.

.. _figure_surface_cropping:

.. list-table:: Surface Cropping
  :widths: 25 25
  :header-rows: 0
  
  * - .. image:: images/surfscribe_crop.png
        :align: center
    - .. image:: images/surfscribe_remove.png
        :align: center
  * - Unselected region removed
    - Selected region removed

In the bottom row, there is one button adjacent to a slider and a numeric 
display. The button is a toggle that controls whether or not unselected
atoms and bonds are shown based on their distance to the selected set. The
cutoff distance is controlled by the adjacent slider (and the actual value
in Angstroms can be seen in the numeric display). This state of this button
is ignored when a surface is selected. When a vertex (or a line of vertices) 
is selected, the slider can be used to flood out from the original selected 
set to include many more adjacent vertices. The different types of surface
selections can be seen in 
:ref:`Table: Surface Scribing<figure_surface_scribing>`.

.. _figure_surface_scribing:

.. list-table:: Surface Scribing
  :widths: 25 25 25
  :header-rows: 0
  
  * - .. image:: images/surfscribe_vert.png
        :align: center
    - .. image:: images/surfscribe_line.png
        :align: center
    - .. image:: images/surfscribe_region.png
  * - Single atom selected
    - Line of atoms selected
    - Region of surface selected

.. _style_pane:
    
Style
^^^^^^^^^^^^^

The style pane of the Style Control is divided into two distinct areas as can
be seen in 
:ref:`Figure: Style Pane<figure_style_pane>`. The area above the dividing line 
contains a row of four buttons which control the display style of the various
different types of objects that can be visualized in |product|. The area beneath
the dividing line is a collection of buttons whose functionality is specific to
just molecules.

.. _figure_style_pane:

.. figure:: /_images/style_style.png
   :scale:  75
   :align:  center
   
   **Style Pane**

In the top area, the first button (with the molecule icon) contains a drop down
menu of the available molecule display styles: *ball and stick*, *CPK*, 
*stars*, *stick*, *wireframe*, and *hidden*. Selecting one 
of these options will change the display style of all the atoms and bonds in 
the current scope. 

The second button (with the surface icon) contains a drop down menu of the 
available surface display styles: *solid*, *mesh*, and *points*.
Selecting one of these options will change the display style of all the 
surfaces in the current scope. 

The third button (with the grid icon) contains a drop down menu of the 
available grid display styles: *solid*, *line*, and *cloud*.
Selecting one of these options will change the display style of all the grid
contours in the current scope. 

The fourth button contains a drop down menu of the supported grid types in
|product|: *Electrostatic*, *ET*, *FRED*, *Generic*, 
*Difference Map*, and *Regular Map*. Selecting one of these options
will change the grid type of all the grids in the current scope. A grid's type
determines how it is visualized in |product| including the default number of 
contours (and their levels) and the display style as well as the color of those
contours. 

In the bottom area, there are three individual rows of buttons. In the first
row, the first three buttons turn on the display of molecular surfaces, 
accessible surfaces, and electrostatic grids, respectively. Surfaces are created
over the selected atoms, or over the currently scoped molecule if no atoms are
selected.  The two surface
buttons have pulldown menus to allow either toggling the visibility of a
surface or regeneration of the surface.  Regeneration may be used to surface
a new part of a molecule if the selection has changed.  Surfaces and grids
generated with these buttons are considered display properties of their 
associated molecules 
and therefore are not displayed in the List Window. Independent (non-property) 
versions of these can be created from the relevant options in a right-click 
menu. The next two buttons turn on the display of protein ribbons and c-alpha 
traces respectively. The next button turns on the display 
of hydrogen bonds by making all of the molecules in the current scope to be 
hydrogen bond targets. Being a hydrogen bond target means that when it 
is visible, it displays any hydrogen bonds made between it and any of the 
other molecules that are also visible. The last button in the row toggles 
whether or not internal (intramolecular) hydrogen bonds are shown. 

In the second row, the first three buttons turn off the display of molecular
surface, accessible surfaces, and electrostatic grids, respectively.
The next two buttons turn off the display of protein ribbons and c-alpha traces.
The next button makes all of the molecules in the current scope
no longer hydrogen bond targets. The last button in the row toggles whether or
not external (intermolecular) hydrogen bonds are shown.

In the last row, the first button allows the user to specify and turn on
atom and bond labels. The second button turns off all of the atom and bond 
labels in the current scope. The third button toggles the display of non-bonded
atoms in the scene. The remaining three buttons control the hydrogen style for
the molecules in the current scope. The first of the three turns all hydrogens
on, the second buttons shows only polar hydrogens, and the last button hides
all hydrogens.

Contours
^^^^^^^^^^^^^

.. _figure_contour_pane:

.. list-table:: Contour Pane
  :widths: 25 25
  :header-rows: 0
  
  * - .. image:: images/contours_style.png
        :align: center
    - .. image:: images/contours_advanced.png
        :align: center
  * - *Normal view*
    - *Advanced view*
    
The contour pane of the Style Control is used to control the number and level
of the individual grid contours as can be seen in 
:ref:`Table: Contour Pane<figure_contour_pane>`. When the 
current application scope is set to *Focused* there will be a pull down menu in 
the top left of the window containing a list of all the current grid contours. If the scope is not set
to *Focused*, the scope will be displayed in place of the pull down menu
to remind users that all operations in this window apply to more than just the
*Focused* grid. Next to this area is a numeric display which displays the
current contour level. Next to this display are two buttons, one with a "+" 
icon and one with a "-" icon. These two buttons allow for the creation and 
deletion of individual grid contours. Please note that these options are 
disabled for both *Electrostatic* and *ET* grids as they can have
only two contours: positive and negative. Furthermore, the contour levels of
the positive and negative contours are coupled together and so changing one
will change the other (but with the opposite sign).

At the bottom of this window is a slider which allows for direct control over
the contour level. To the right of the slider is an *Advanced* button 
(with the equalizer icon) which will expand the pane to show a number of 
advanced options (see 
:ref:`Table: Contour Pane<figure_contour_pane>`).

In the advanced section, there are two adjustable parameters (*Radius* 
and *Grid Spacing*) and one button. The parameters control how contours 
of *Reentrant* grids are displayed according to their symmetry. The 
*Radius* parameter specifies how far out from the center of the scene 
(in Angstroms) |product| should look in the grid in order to generate of the 
isocontour. The *Grid Spacing* parameter specifies the spacing (in 
Angstroms) of the sub-grid used to generate the isocontours.

The single button (with the check icon) to the right of the *Radius* 
parameter converts the current grid contour into a fixed surface independent
of the grid. This can be particularly useful when generating state files as
a single surface can take up considerably less disk space than an entire 
grid.

Graphics
^^^^^^^^^^^^^

The graphics control pane in the Style Control provides an additional level
of control over and interaction with the 3D display (see 
:ref:`Figure: Graphics Pane<figure_graphics_style>`). It 
is particularly useful for users without mouse wheels.

.. _figure_graphics_style:

.. figure:: /_images/graphics_style.png
   :scale:  75
   :align:  center
   
   **Graphics Pane**

At the top of the graphics pane are three check boxes: "Depthcue", 
"Slabbing", and "Mirror". The first two check boxes toggle the use of their
associated properties respectively. The "Mirror" check box is only enabled 
when slabbing is on and controls whether the front and back slabbing 
planes move together (mirrored around the center of the scene) or 
independently.

Beneath these check boxes is an interactive control which allows the user
easy control over both depthcueing and the clipping planes. Displayed in the 
control is a top-down view of the current scene in the 3D display. The front 
of the scene is at the bottom as indicated by the label. 

When depthcueing is enabled, two red lines will appear in the control which 
indicate the start and the end points in the depthcueing calculation. These 
lines can be moved by clicking on the triangular tab at the right of the 
lines and dragging them to the desired location. The 3D display will update
dynamically as these lines are moved.

When clipping (or slabbing) is enabled, two yellow lines will appear in the 
control which indicate the position of the near and far clipping planes. These 
can be moved by simply clicking on the triangular tab at the left of the lines 
and dragging them to the desired location. The 3D display will update 
dynamically as these lines are moved. 

In the center of the control is a small white dot that corresponds to the 
center of scene that the camera is pointing at. The position of the center can 
be changed in the Z plane by dragging the dot in the vertical plane. The 
position of the center can be changed in the X plane by dragging the dot in the
horizontal plane.

Beneath this control is a slider which controls the scale of the text drawn in
the 3D display. The 3D display will update dynamically as the slider is 
adjusted.

Beneath the slider are four radio buttons which control the mode of 
stereoscopic visualization. The default behavior is "Off". The "Stencil" option 
provides an additional mechanism for hardware stereo specific to the Zalman Trimon 
3D LCD Monitor.

Custom Views
^^^^^^^^^^^^^

Each of the individual custom views available in |product| can also provide 
their own individual panes which can be inserted into the Style Control to
further enable task specific operations. These panes appear when a specific
custom view is selected and disappear when the "X" icon is clicked or when
another custom view is loaded.  For more information on custom views refer to the 
:ref:`Custom Views<custom_views>` chapter. 

Rendering
=========

The images shown in the 3D display are rendered using OpenGL, therefore the 
quality and speed of the rendered scenes in the 3D display is dependent on the 
graphics card in the computer running the application. Computers with graphics
cards that do not support OpenGL acceleration will still be able to display 
images, but the quality and speed with which the images are displayed may be 
markedly reduced. To help alleviate situations like this, multiple "levels of 
detail" are supported ranging from "Fastest"  to "Best" which adjust the 
quality of the rendered scenes accordingly. For most computers, "Best" level 
of detail should be appropriate.  "Presentation" quality rendering is 
optimized for creating images with a white background, such as might be used
in slide presentations and printed documents.

In addition to the "level of detail", the scene can be further adjusted by 
modifying a few select OpenGL parameters such as the background color as well 
as the lighting and material models. All of these parameters can be adjusted in 
the :ref:`application preferences<preferences>`. 

Stereo
======

Multiple types of stereo visualization are supported in the 3D display. 
The "Stencil" option enables stereo visualization using the 
Zalman Trimon 3D LCD Monitor. This is the only LCD display on which stereo 
visualization is supported. This monitor has been tested on multiple operating
systems and requires no specific graphics card.

Finally, split-screen stereo is also a viable option. Both cross-eyed and 
wall-eyed views are available and can be set in the :ref:`preferences<preferences>`. Furthermore, 
the stereo angle and eye offset parameters can be adjusted in the 
:ref:`preferences<preferences>` as well. 

Viewpoint
=========

When viewing objects in the 3D display, there is always a center to the scene
where the virtual "camera" is pointing. When the first molecule, grid, or 
surface is loaded into the application, the center of that object becomes the 
center of the scene where the camera is pointing. By default, the center does 
not automatically change with changes to the scene. The center can be changed 
explicitly from the main application toolbar, the right-click popup menu, or 
using the following scripting commands: ``ViewerCenterSet`` or 
``ViewerCenterAndRadiusSet``. Furthermore, the center can 
also be translated using mouse interactions. 

The center can be made to automatically change when browsing if the 
"Auto-Center" or "Auto-Fit" preferences are set to true (the default is 
false). The "Auto-Center" preference directs the window to always recenter 
the scene after any changes are made to that scene. The "Auto-Fit" preference 
directs the window to not only recenter the scene after any changes are made 
but to also ensure that everything in the scene is completely visible in the 
window. These preferences can be edited in the :ref:`application preferences<preferences>` 
dialog.

Bookmarks
=========

The 3D display is capable of capturing and storing named bookmarks of the 
currently displayed scene to enable viewing again at another time without having
to setup the scene again by hand. Bookmarks are saved in state files and are
particularly useful when trying to communicate multiple pieces of information
to other users.

All bookmarks have names and are stored in order. Bookmarks can be created
from the top-level *Bookmark* menu by selecting the "Add" option. The
order of the bookmarks can be organized by selecting the "Organize" option
in the same menu. The *Bookmark* menu also contains an "Animated" option
which controls whether |product| animates the transition between the current
scene and the newly selected bookmark. A list of all the currently available
bookmarks populate the rest of the menu. Bookmarks can also be created by
clicking on the "Add Bookmark" button in the 3D display *Style* toolbar.

The 3D display also provides a :ref:`bookmark display widget<bookmark_widget>` 
which displays a 
clickable list of all the available bookmarks directly in the 3D display.

.. _display_3d_tiled:

Tiled Display
=============

The default behavior of the 3D display is to display everything that is 
*Visible* in the same coordinate space; however, there are often occasions when it is desirable
to view everything in their own space. This behavior can be obtained in 
"Tiled" mode, also called "Matrix" mode or "Multi-Pane" mode. "Tiled" mode 
can be toggled on or off from the main application toolbar.

When the 3D display is in "Tiled" mode every *Visible* and *Focused* 
object is displayed centered in its own individual pane. However, if desired 
each object can be shown relative to the same center if the "Auto-Center Panes"
option in the *3D Display* section of the application preferences is 
unchecked. It is important to note that when "Auto-Center Panes" is enabled it
is not possible to recenter or translate using mouse interactions in any of the
panes.

To indicate which object is *Focused*, the corresponding pane will contain 
a blue border just inside the regular pane border. If there are any *Locked* 
objects, each of them will be displayed in every pane in addition to the 
individual *Visible* and *Focused* objects. 

Toolbars
========

The 3D display provides additional toolbar areas (aside from the main 
application toolbar) inside the 3D window. There are four possible toolbar
locations: at the top of the window, at the bottom of the window, at the left
edge of the window and at the right edge of the window. 

By default, the 3D display provides a "Mouse" toolbar at the left edge of the
display. In Edit mode, a "3D Right"
toolbar on the right side of the display is populated with building tools.  
Two toolbars are empty and hidden by default, one at the bottom of the 3D 
Window ("3D Bottom") and one at the top ("Style").
These can be shown and populated *via* the use of scripting commands.  

Mouse Toolbar
-------------

The *Mouse* toolbar contains a single row of buttons along the left side of the
3D display which control the behavior of the mouse in the display. The first 
button is the default and puts the mouse into normal selection mode. The second
button puts the mouse into information mode which will cause information about 
the object currently under the mouse to be displayed. The third button puts the
mouse into centering mode which will cause the display to be centered on 
whatever the mouse clicks on. The fourth button puts the mouse into measuring
mode. There is a drop down menu adjacent to this button which allows the user to
select one of three measurement modes: *Distance*, *Angle*, and *Torsion*. The
fifth button puts the mouse into labeling mode which will prompt the user for
a custom label to apply to any object that is clicked.

Double-clicking in the background of the 3D display will restore the mouse 
function to the default selection mode.

This toolbar can be referenced in scripting commands using the name "Mouse".

Bottom Toolbar
--------------

Although empty by default it contains a set of buttons (that change depending 
on what is active) collectively referred to as the "Object toolbar" although they are 
not technically a separate toolbar.  It also contains the :ref:`bookmark widget<bookmark_widget>`.

For each type (molecule, grid, surface) it can show two buttons which represent 
menus - one color & one style.  If the active object is a molecule and it has 
surfaces and/or grids shown via the Style Control, it will show the button menus 
for those objects as well.  These buttons are quick links to the options
available in the :ref:`Style Control<style_control>` window. 

This toolbar can be referenced in scripting commands using the name "Bottom".

Right Toolbar
-------------

This toolbar is displayed during 3D building, and contains tools for editing
molecules.  The first button is a tool for deleting atoms and bonds.  The
second button shows a benzene ring by default and attaches the fragment 
selected from a dropdown to either an atom or bond of the molecule in the main
window.  The third button provides a dropdown for selection of the active atom 
type.  The fourth button provides a selection of bond types from a dropdown.  
The fifth button allows modification of format atomic charges.  The sixth
button allows stereochemistry to be set (R/S or E/Z) or inverted.  The last 
tool on this toolbar minimizes the active molecule using the MMFF94 or MMFF94s
forcefield.

Application Toolbar
-------------------

In addition to providing its own toolbars, the 3D display is affected by a few
of the buttons in the main application toolbar. The application toolbar 
contains the "Tiled" display toggle button (matrix icon), the main window 
screenshot button (camera icon), the centering button (four arrows pointing in), 
the fitting button (four arrows pointing out), the new molecule button, and the
edit molecule button.

The "Tiled" display button toggles the display between single pane overlay 
mode and multiple pane tiled mode. The screenshot button captures an image of the 
current main window at a user specified resolution. The centering button
centers the display on the currently selected set or whatever molecule(s) are
in the current scope. The fit button centers the scene and adjusts the scale
factor such that all *Visible* objects can be seen on the screen at the
same time. The new molecule button prompts the user to specify a new molecule 
using the 2D molecule editor. The edit molecule button puts the application 
into editing mode for the currently active molecule.

Display Widgets
===============

The 3D display provides a number of additional widgets which are drawn directly
in 3D display as opposed to on the side or floating above it. These widgets 
include an annotation widget, a bookmark widget, a data display widget, and 
a depiction widget.  See :ref:`Figure: 3D Display Widgets<figure_display_widgets>`. 

.. _figure_display_widgets:

.. figure:: /_images/widgets.png
   :scale:  75
   :align:  center
   
   **3D Display Widgets**

Annotation
----------

It is often desirable when viewing molecules to make notes or simple
annotations about specific molecules. This can be done directly within the 
3D display, where the annotation widget appears like a transparent Post-It(TM) (see 
:ref:`Figure: Molecule Annotation<figure_molecule_annotation>`). The color 
of the widget as well as the font used can be specified in the 
:ref:`application preferences<preferences>`.

.. _figure_molecule_annotation:

.. figure:: /_images/annotation.png
   :align:  center
   
   **Molecule Annotation**

The widget can be moved by clicking on the title bar and dragging it to the 
desired location. The widget can be resized by grabbing the small triangular 
tab in the lower right-hand corner of the widget and dragging until the 
desired size is achieved.

Clicking in the annotation widget will activate it for editing. Editing
can be accomplished by directly typing once the widget has been clicked or by
clicking on the "Edit" button in the title bar. Clicking on the "Edit" button
will launch a more fully featured text editor which supports copy and paste
operations (see 
:ref:`Figure: Annotation Editing<figure_annotation_edit>`).

.. _figure_annotation_edit:

.. figure:: /_images/annotation_edit.png
   :scale:  75
   :align:  center
   
   *Annotation Editing*

Annotations are also stored in the spreadsheet and can be edited there as well 
as in the 3D display. Annotations are saved as a SD tag when a molecule is 
written out (in either SD or OEB formats). 

.. _bookmark_widget:

Bookmark
--------

The bookmark widget is a simple widget drawn at the bottom of the 3D display
(:ref:`Figure: 3D Display Widgets<figure_display_widgets>`) 
containing a clickable list of the currently available bookmarks. Clicking on
any individual bookmark will load that bookmark and update the display 
accordingly. 

Data Display
------------

This widget provides a simple table which contains the spreadsheet data of the
*Focused* object. The widget can be moved around the 3D display by 
clicking and dragging it to the desired location. It can also be resized by
clicking in the tab in the upper left hand corner. Lastly, if the amount of
data associated with the object is too large to be shown all at once, the 
widget does provide scrolling functionality.

Depiction Widget
----------------

The depiction widget draws a 2D depiction of the focused molecule directly
into the 3D display. The depiction is drawn in the lower left hand corner 
of the display (or individual pane if in tiled mode). The depiction style is
determined based on the application 2D depiction preferences. The size and
other drawing parameters (e.g. anti-aliasing) of the depiction are also 
specified in the :ref:`application preferences<preferences>`. 

The depiction widget is mouse-aware making it possible to perform selections
in this region.

Molecular Visualization
=======================

This section describes the very powerful, versatile, and interactive molecular 
visualization capabilities of the 3D display. The interactive control of 
molecular visualization is typically performed using the *Style Control* 
or through scripting commands.

.. _molecule_display_styles:

Display Styles
--------------

All of the standard molecule display styles are available in |product| (*Wireframe*,
*Stick*, *Ball and Stick*, *CPK*, and *Stars*), and are illustrated
in :ref:`Table: Display Styles<figure_display_styles>`. 
By default, small molecules are drawn in *Stick* mode while large
molecules are drawn in *Wireframe* mode. These defaults can be changed in
the :ref:`application preferences<preferences>`. 

.. _figure_display_styles:

.. list-table:: Display Styles
  :widths: 10 10 10 10 10
  :header-rows: 0 
  
  * - .. image:: images/wireframe.png
        :align: center
    - .. image:: images/stick.png
        :align: center
    - .. image:: images/ballstickfancy.png
        :align: center
    - .. image:: images/cpk.png
        :align: center
    - .. image:: images/stars.png
        :align: center
  * - Wireframe
    - Stick
    - Fancy Ball and Stick
    - CPK
    - Stars

.. _molecule_colors:

Molecule Color
--------------

By default, the atoms in a molecule are colored according to their element 
types and the bonds in a molecule are colored according to the element types
of the two atoms defining that bond. There are two color palettes that specify 
the actual colors used for a given element, one for use with dark-colored 
backgrounds and the other for use with light-colored backgrounds. Both of these 
palettes can be viewed and modified in the application preferences. The 
dark-background atom color palette can be seen in 
:ref:`Table: Color Palettes<figure_color_palettes>`.

.. _figure_color_palettes:

.. list-table:: Color Palettes
  :widths: 30 30
  :header-rows: 0
  
  * - .. image:: images/atomcolors.png
        :align: center
    - .. image:: images/residuecolors.png
        :align: center
  * - Atom Color Palette
    - Residue Color Palette

Coloring Schemes
^^^^^^^^^^^^^^^^

There are a number of molecule specific coloring schemes in addition to the 
standard element based coloring. The following schemes are discussed below: 
amino, bfactor, carbon, chain, cpk, cpknew, element, formal charge, group, 
partial charge, reference, residue, and shapely.

Amino
^^^^^^^^^^^^^^^^

The *amino* color scheme is a protein specific scheme which colors atoms
according to their individual residues. The residue colors are listed below.

.. table:: Amino Color Scheme
  
  =============== =============== ===============
  Residue         Color           RGB Value
  =============== =============== ===============
  ASP, GLU        Bright Red      [230, 10, 10] 
  CYS, MET        Yellow          [230, 230, 0]
  LYS, ARG        Blue            [20, 90, 255]
  SER, THR        Orange          [250, 150, 0]
  PHE, TYR        Mid Blue        [50, 50, 170]
  ASN, GLN        Cyan            [0, 220, 200]
  GLY             Light Grey      [235, 235, 235]
  LEU, VAL, ILE   Green           [15, 130, 15] 
  ALA             Dark Grey       [200, 200, 200]
  TRP             Purple          [180, 90, 180] 
  HIS             Pale Blue       [130, 130, 210]
  PRO             Flesh           [220, 150, 130]
  Others          Tan             [190, 160, 110]
  =============== =============== ===============

BFactor
^^^^^^^^^^^^^^^^

The *bfactor* color scheme is a protein specific scheme which colors atoms
according to the bfactor value using a fixed blue-to-red gradient between 0 and 
60.

Carbon
^^^^^^^^^^^^^^^^

The *carbon* color scheme colors all of the carbon atoms in the current
scope the same color which is specified by the user.

Chain
^^^^^^^^^^^^^^^^

The *chain* color scheme is a macromolecule specific scheme which assigns 
a unique color to each of the macromolecular chains.

CPK, CPKNew
^^^^^^^^^^^^^^^^

The *CPK* color scheme is an element specific scheme based on the colors
used in the popular CPK plastic space filling models. The *CPKnew* color 
scheme is a variant on the *CPK* color in that it uses a slightly brighter 
version of some of the colors. The atom colors are listed below with the RGB
values for *CPK* in the third column and the RGB values for *CPKNew*
in the fourth column (if different).

.. table:: CPK, CPKNew

  ================== ================== ================== ==================
  Element            Color              CPK: RGB Values    CPKNew: RGB Values
  ================== ================== ================== ==================
  H                  White              [255, 255, 255]  
  He                 Pink               [255, 192, 203]  
  Li                 Fire Brick         [178, 34, 34]      [178, 33, 33] 
  B,Cl               Green              [0, 255, 0] 
  C                  Light Grey         [200, 200, 200]    [211, 211, 211] 
  N                  Sky Blue           [143, 143, 255]    [135, 206, 235] 
  O                  Red                [255, 0, 0]   
  F,Si,Au            Golden Rod         [218, 165, 32] 
  Na                 Blue               [0, 0, 255]  
  Mg                 Forest Green       [34, 139, 34]  
  Al,Ca,Ti,Cr,Mn,Ag  Dark Grey          [128, 128, 144]    [105, 105, 105]
  P,Fe,Ba            Orange             [255, 165, 0]      [255, 170, 0]
  S                  Yellow             [255, 200, 50]     [255, 255, 0] 
  Ni,Cu,Zn,Br        Brown              [165, 42, 42]      [128, 40, 40] 
  I                  Purple             [160, 32, 240]  
  Unknown            Deep Pink          [255, 20, 147]     [255, 22, 145]
  ================== ================== ================== ==================

Element
^^^^^^^^^^^^^^^^

The *element* color scheme is the default color scheme used when coloring
molecules. Colors are assigned according to atomic number. The actual colors 
used for a given element can be edited in the :ref:`application preferences<preferences>` 
as seen in :ref:`Table: Element Color Palettes<figure_color_palettes>`.

.. table:: Element Color Palettes

  ================= ================= =================
  Element           Color             RGB Values
  ================= ================= =================
  H                 White             [255, 255, 255] 
  C                 Grey              [180, 180, 180] 
  N                 Blue              [0, 0, 255] 
  O                 Red               [255, 0, 255]
  F                 Green             [0, 255, 0] 
  P                 Magenta           [192, 0, 192] 
  S                 Yellow            [255, 255, 0] 
  Cl                Lime Green        [170, 255, 0] 
  Br                Dark Red          [170, 0, 0] 
  I                 Dark Orange       [170, 85, 0] 
  Group I           Cyan              [0, 255, 255] 
  Group II          Light Blue        [160, 160, 255] 
  Transition Metals Purple            [170, 0, 255] 
  Others            Pink              [255, 0, 128] 
  ================= ================= =================

Formal Charge
^^^^^^^^^^^^^^^^

The *formal charge* color scheme colors atoms according to their formal 
charge using a fixed red-to-blue gradient between -4 and +4.

Group
^^^^^^^^^^^^^^^^

The *group* color scheme is a macromolecule specific scheme which colors
each atom according to its position in a macromolecular chain. The colors are
assigned along a smooth rainbow spectrum from blue, through green, yellow and orange 
to red.

Partial Charge
^^^^^^^^^^^^^^^^

The *partial charge* color scheme colors atoms according to their partial
charge using a red-to-blue gradient between -1.0 and +1.0.

Reference
^^^^^^^^^^^^^^^^

The *reference* color scheme colors all of the carbon atoms in the current 
scope using the current *Reference* color which can be set in the 
:ref:`application preferences<preferences>`. The default is green. 

Residue
^^^^^^^^^^^^^^^^

The *residue* color scheme is a protein specific scheme which colors atoms
according to their individual residues. The actual colors used can be edited in
the :ref:`application preferences<preferences>` as seen in 
:ref:`Table: Color Palettes<figure_color_palettes>`. The default colors 
correspond to those used in the *shapely* color scheme.

Shapely
^^^^^^^^^^^^^^^^

The *shapely* color scheme is a protein specific scheme which colors atoms
according to their individual residues. This scheme is based upon Bob 
Fletterick's "Shapely Models"(\ [Fletterick-1982]_\ ). The residue colors are listed below.

.. table:: Shapely Color Scheme

  ================ ================ ================
  Residue          Color            RGB Values
  ================ ================ ================
  ALA              Medium Green     [140, 255, 140] 
  GLY              White            [255, 255, 255] 
  LEU              Olive Green      [ 69, 94, 69] 
  SER              Medium Orange    [255, 112, 66] 
  VAL              Light Purple     [255, 140, 255] 
  THR              Dark Orange      [184, 76, 0] 
  LYS              Royal Blue       [ 71, 71, 184] 
  ASP              Dark Rose        [160, 0, 66] 
  ILE              Dark Green       [0, 76, 0] 
  ASN              Light Salmon     [255, 124, 112] 
  GLU              Dark Brown       [102, 0, 0] 
  PRO              Dark Grey        [ 82, 82, 82]
  ARG              Dark Blue        [0, 0, 124] 
  PHE              Olive Grey       [83, 76, 66] 
  GLN              Dark Salmon      [255, 76, 76] 
  TYR              Medium Brown     [140, 112, 76] 
  HIS              Medium Blue      [112, 112, 255]
  CYS              Medium Yellow    [255, 255, 112]
  MET              Light Brown      [184, 160, 66] 
  TRP              Olive Brown      [79, 70, 0] 
  ASX,GLX,PCA,HYP  Medium Purple    [255, 0, 255] 
  A                Light Blue       [160, 160, 255]
  C                Light Orange     [255, 140, 75] 
  G                Medium Salmon    [255, 112, 112] 
  T                Light Green      [160, 255, 160] 
  Backbone         Light Grey       [184, 184, 184] 
  Special          Dark Purple      [94, 0, 94] 
  Default          Medium Purple    [255, 0, 255] 
  ================ ================ ================

Proteins
--------

In addition to the standard display styles, the two protein specific displays 
of *C-Alpha Traces* and *Ribbons* are supported. Examples of these 
display styles can be seen in 
:ref:`Table: Protein Styles<figure_protein_styles>`.

.. _figure_protein_styles:

.. list-table:: Protein Styles
  :widths: 25 25 25
  :header-rows: 0
  
  * - .. image:: images/proteinwire.png
        :align: center
    - .. image:: images/catrace.png
        :align: center
    - .. image:: images/ribbon.png
        :align: center
  * - *Wireframe*
    - *C-Alpha Trace*
    - *Ribbon*

Given that protein files often inevitably contain many extra components that 
are not necessarily of interest to the user (waters for example), the ability
to hide the display of non-bonded atoms is provided to ease the viewing of 
proteins without having to manually edit the input file. An example of a
protein displayed with and without waters can be seen in 
:ref:`Table: Water Styles<figure_water_styles>`.  There is also a button in the 
:ref:`style panel<style_pane>` of the Style Control window that will 
toggle the display of non-bonded atoms.

.. _figure_water_styles:

.. list-table:: Water Styles
  :widths: 30 30
  :header-rows: 0

  * - .. image:: images/protein_h2o.png
        :align: center
    - .. image:: images/protein_noh2o.png
        :align: center
  * - Protein with waters
    - Protein without waters

.. _figure_multimeric_styles:

.. list-table:: Multimeric Styles
  :widths: 30 30
  :header-rows: 0
  
  * - .. image:: images/multimer_one.png
        :align: center
    - .. image:: images/multimer_comp.png
        :align: center
  * - Multimer displayed as a single molecule
    - Multimer displayed as multiple molecules
    
Another common scenario when working with proteins is that the input file 
contains a large multimer which, as expected, is interpreted as a single 
molecule. However, sometimes the ability to interact with the individual
components is of particular value. The ability to split a molecule into
separate components can be performed by selecting the "*File* > *New Molecule* 
> *From Split* > Components" menu option. This function will then determine what the 
individual components of the *Focused* molecule are and create a new 
list containing a new molecule for each component. The original molecule is 
not changed or deleted. An example of this process can be seen in Figure 
X.Y. The *From Split* submenu also contains 
"Selected" and "Marked" options which will create new molecules from the 
original based on the selected or marked set of atoms.

It may also be of interest to put some of these components back together into
a single molecule. This can be done by choosing one of the following options
from the "*File* > *New Molecule* > *From Merge*" submenu: "Selected", "Marked", "Visible". Choosing any one of these
options will create a new molecule which is composed of all the molecules that
were either "Selected", "Marked", or "Visible" at the time of the operation.

.. _molecule_monitors:

Monitors
--------

The ability to display measurement monitors is a useful feature and is well
supported. Access to these measurement facilities is available from the 
*Mouse* toolbar on the left hand side of the 3D display. There is a single
button with three options which turn on *Distance*, *Angle*, and *Torsion*
measurement respectively.

.. _figure_monitor_types:

.. list-table:: Monitor Types
  :widths: 30 30 30
  :header-rows: 0
  
  * - .. image:: images/monitor_distance.png
        :align: center
    - .. image:: images/monitor_angle.png
        :align: center
    - .. image:: images/monitor_torsion.png
        :align: center
  * - *Distance Monitor*
    - *Angle Monitor*
    - *Torsion Monitor*
    

When the mouse is put into one of these modes, the measurements are made
based on the selected set of atoms. In *Distance* mode, the first atom
selected is consider the "anchor" atom. Once the anchor atom has been 
selected, a temporary distance monitor will be displayed to any other atom
that the mouse passes over. Selecting another atom will create a permanent
monitor and clear the anchor. In *Angle* mode, the first two atoms 
selected are considered the anchor atoms and a temporary angle monitor will 
be displayed to any other atom that the mouse passes over. Selecting a 
third atom will create a permanent monitor and clear the anchors. In 
*Torsion* mode, the first three atoms selected are considered the anchor
atoms and a temporary torsion monitor will be displayed to any other atom that 
the mouse passes over. Selecting a fourth atom will create a permanent monitor
and clear the anchor.

Monitors can be removed by selecting the monitor of interest and then choosing
the "Delete" option in the right-click menu. All of the visible monitors can be
deleted in one step by right-clicking in the 3D display and selecting the 
"Delete visible monitors" option. Monitors are also displayed in
the "List Window" and can be deleted individually there. Examples of the three 
types of monitors can be seen in 
:ref:`Table: Monitor Types<figure_monitor_types>`.

Monitors serve an important role when in editing mode as the properties they
measure can be modified by selecting the monitor and then using the mouse wheel
to adjust the value up or down. By default, the smaller portion of the 
associated molecule will be the part that is moved. This can be reversed by 
holding down the *Ctrl* key while using the mouse wheel. To achieve fine 
control of the values, hold down the *Shift* key while using the mouse wheel.

Hydrogen Bonds
--------------

Both internal (intramolecular) and external (intermolecular) hydrogen bonds can 
be displayed. Hydrogen bonds are determined by typing all of the atoms as either 
acceptors, donors, both, or neither. Then the hydrogen bond energy is calculated 
between all acceptors and donors based on the ChemScore scoring 
function which takes into account both interatomic distance as well as the 
coordination geometry (\ [Eldridge-1997]_\ ). This function provides a relative score between 0 and 1.0
for the energy of the hydrogen bond. For all hydrogen bonds with an energy 
greater than 0, the bond is drawn as a dotted green line. The thickness of the 
line as well as the spacing between the dots correlates to the bond energy. 
Therefore, thicker more solid lines have higher energy than thinner more dotted 
lines. An example of both internal and external hydrogen bonds can be seen in 
:ref:`Table: Hydrogen Bonds<figure_hydrogen_bonds>`.

.. _figure_hydrogen_bonds:

.. list-table:: Hydrogen Bonds
  :widths: 30 30
  :header-rows: 0 
  
  * - .. image:: images/hbonds.png
        :align: center
    - .. image:: images/hbonds_internal.png
        :align: center
  * - External Hydrogen Bonds
    - Internal Hydrogen Bonds

.. _grid_visualization:

Grid Visualization
==================

Grids are spatial arrays of data that are sampled at regular intervals.  Grids 
may contain electrostatic samples of spatial regions, density samples, and 
other potential fields.

A grid can have a variable number of contours. Each contour has an index 
starting at 1 for the first contour. Additionally, every contour has its own 
individual color and a threshold value which can be positive or negative (also
known as the "contour level"). There are three different display styles for
grids contours: *Solid*, *Mesh* and *Cloud*.

Grid Types
==========

As mentioned in the previous section, there are multiple different predefined 
grid types that are supported including: *Electrostatic*, *ET*,
*FRED*, *Generic*, *Difference Map*, and *Regular Map*.

Electrostatic
-------------

Electrostatic grids are the only type of grid that can be actually be generated 
within |product| as opposed to simply being visualized. Electrostatic grids are 
created for individual molecules using OpenEye's **Zap** toolkit (for more information, 
please see the **Zap** toolkit documentation). The creation of
the grid requires the presence of partial charges on the input molecule. If
partial charges were already present on the molecule, those will be used in the
calculation. However, if no partial charges were present (or the user decides to
ignore them, which can be set in the :ref:`application preferences<preferences>`), temporary 
partial charges will be calculated using MMFF94 or AM1-BCC (\ [Jakalian-2000]_\ , [Jakalian-2002]_\ ).
If a molecule has greater than 50 atoms, MMFF94 charging will 
be done even if AM1-BCC was selected. However, for proteins an alternate 
residue based charging model is available and can be selected in the 
preferences. This model assigns partial charges based on residue information 
as is shown below:

.. table::

  =============== =============== ===============
  Residue         Residue Atom    Partial Charge
  =============== =============== ===============
  ASP             OD1, OD2        -0.5
  GLU             OE1, OE2        -0.5
  LYS             NZ              +1.0
  ARG             NE              +1.0
  =============== =============== ===============

The grid spacing is dynamically determined based on the number of atoms in
the input molecule. However, it is possible to specify a fixed spacing in 
the grid preferences. Be warned, however, that specifying very fine spacings
(< 2.0 Angstroms) may consume a surprisingly large amount of memory, (in some
cases more than may be available on the computer), which can lead to program 
failure. This should be considered a very advanced feature to be used only when
necessary and when all other data has been saved. Finally, it has been observed 
in research at OpenEye that adding salt to the electrostatic calculation has a 
beneficial effect on the grids generated. The salt concentration can be 
specified in the preferences. The default concentration is 0.04 M. The maximum 
concentration that can be specified is 0.1 M.

Electrostatic grids (as well as ET grids) are special in that they are always
generated with two default contours: a positive one and a negative one. These
contours cannot be deleted and new contours cannot be added. The positive 
contour is colored blue by default and the negative contour is colored red. The
contour levels of the two contours are coupled together and so changing one 
will change the other.

ET
-------------

ET (or Electrostatic Tanimoto) grids are generated by OpenEye's BROOD and EON
applications. When viewed in |product| they behave, and are treated essentially
the same, as Electrostatic grids.

FRED
-------------

FRED grids are shape potential grids that are created by OpenEye's FRED 
application. In |product|, the behave just like Generic grids except that their
default contour color is purple instead of blue.

Generic
-------------

Generic grids are effectively the most basic grids and act as the primary 
grid workhorses. They are completely customizable and have bare-bones 
settings. They default to having just one contour with a default color of
blue. Additional contours can be added as well as removed. These default
values can be changed in the *Grids* section of the application
preferences.

Reentrant Grids
===============

.. list-table::
  :widths: 30 30 30
  :header-rows: 0
  
  * - .. image:: images/reentrant1.png
        :align: center
    - .. image:: images/reentrant2.png
        :align: center
    - .. image:: images/density.png
        :align: center
  * - Infinite grid
    - Infinite grid rendered at a different center
    - Non-reentrant grid

Some grids have fixed extents and some grids are infinitely reentrant in space.
Reentrant grids obviously cannot be displayed in their entirety, so instead 
only the region around the center of the current scene is displayed. Grids that 
are being rendered as reentrant can be distinguished from non-reentrant grids 
by the absence of grid corners which define the extents of non-reentrant grids.

.. _surface_visualization:

Surface Visualization
=====================

Surfaces are infinitely thin three dimensional connected regions that represent 
objects such as molecular or accessible surfaces of molecules. Surfaces can be 
selected (or scribed), cropped, colored, and made transparent in part or in 
whole. 

Display Styles
--------------

Surfaces can be visualized in one of three display styles: Solid, Mesh, and 
Points. These individual display styles can be seen in 
:ref:`Table: Surface Styles<figure_surface_styles>`.

.. _figure_surface_styles:

.. list-table:: Surface Styles
  :widths: 25 25 25
  :header-rows: 0
  
  * - .. image:: images/solidsurf.png
        :align: center
    - .. image:: images/meshsurf.png
        :align: center
    - .. image:: images/pointsurf.png
        :align: center
  * - Solid
    - Mesh
    - Point

.. _surface_colors:

Surface Color
-------------

There are a number of surface specific coloring schemes in addition to the 
standard single color scheme and some examples are illustrated in
:ref:`Table: Surface Colors<figure_surface_colors>`. The following schemes are 
discussed below: atom color, curvature, distance, electrostatics, grid, 
hydrogen bond potential, hydrophobicity, and surface potential.

.. _figure_surface_colors:

.. list-table:: Surface Colors
  :widths: 25 25 25
  :header-rows: 0
  
  * - .. image:: images/surfcolor_palette.png
        :align: center
    - .. image:: images/surfcolor_atom.png
        :align: center
    - .. image:: images/surfcolor_curvature.png
        :align: center
  * - Single color
    - Color by atom
    - Color by curvature
  * - .. image:: images/surfcolor_dist.png
        :align: center
    - .. image:: images/surfcolor_electrostatic.png
        :align: center
    - .. image:: images/surfcolor_hbond.png
        :align: center
  * - Color by distance
    - Color by electrostatics
    - Color by hydrogen bond potential
  * - .. image:: images/surfcolor_hydrophobic.png
        :align: center
    -
    -
  * - Color by hydrophobicity
    -
    -

Atom Color
^^^^^^^^^^^^^

The *atom color* scheme colors each vertex on the surface using the color
of the nearest atom to that vertex in the molecule that the surface was created
from (see 
:ref:`Table: Surface Colors<figure_surface_colors>`). This scheme will not work if the 
surface was not created from a molecule and also if that molecule is not 
currently present.

Curvature
^^^^^^^^^^^^^

The *curvature* scheme colors each vertex on the surface according to the
curvature of the surface at that vertex using a pink-to-cyan gradient where
cyan indicates high convexity and pink indicates high concavity (see 
:ref:`Table: Surface Colors<figure_surface_colors>`).

Distance
^^^^^^^^^^^^^

The *distance* scheme colors each vertex by its distance from either the
selected set of atoms or the visible set of atoms (if none are selected at the
time of coloring). Each band of color represents a distance of one Angstrom from 
the selected set. The color banding is continuously repeated as the distance 
increases, but the colors fade to white with each repetition to show the distance 
effect (see :ref:`Table: Surface Colors<figure_surface_colors>`). 

Electrostatics
^^^^^^^^^^^^^^

The *electrostatics* scheme colors each vertex on the surface according to
the electrostatic potential at that vertex using a red-to-blue gradient from 
-7.0 to +10.0 (see :ref:`Table: Surface Colors<figure_surface_colors>`). This 
range can be changed if desired in the :ref:`application preferences<preferences>` 
in the *Surfaces* section.

The electrostatic potential at the surface is calculated using OpenEye's **Zap**
toolkit (for more information, please see the **Zap** toolkit documentation). By 
default, |product| will use the molecule's input partial charges in the 
calculation (if any were specified). However, if no partial charges were 
specified, |product| will assign partial charges using either MMFF94 (the 
default) or AM1-BCC. The choice of charge model 
can be specified in the application preferences. If a molecule has greater 
than 50 heavy atoms, MMFF94 will always be used in place of AM1-BCC regardless of 
the set preferences.

Proteins have an alternative charging option based on residue information. The
charge model can be seen in the table below. This model is used by default (if
no partial charges were specified), but it can be disabled in the application
preferences.

.. table::

  =============== =============== ===============
  Residue         Residue Atom    Partial Charge
  =============== =============== ===============
  ASP             OD1, OD2        -0.5
  GLU             OE1, OE2        -0.5
  LYS             NZ              +1.0
  ARG             NE              +1.0
  =============== =============== ===============

Grid
^^^^^^^^^^^^^

The *grid* scheme colors each vertex on the surface according to the grid
potential at that vertex using a red-to-blue gradient from the minimum grid 
value to the maximum grid value. The grid potential is determined by mapping 
the specified grid onto the surface.

Hydrogen Bond Potential
^^^^^^^^^^^^^^^^^^^^^^^

The *hydrogen bond potential* scheme colors each surface vertex according to the
hydrogen bond class (Acceptor=Red, Donor=Blue, Both=Magenta) of the nearest atom in the 
surface's molecule (see :ref:`Table: Surface Colors<figure_surface_colors>`). 
This scheme will 
not work if the surface was not created from a molecule and also if that 
molecule is not currently present.

Hydrophobicity
^^^^^^^^^^^^^^

The *hydrophobicity* scheme colors each vertex according to a specified 
hydrophobic color scale based on the OEXLogP values of the underlying atoms.
More hydrophobic areas are brown, while more hydrophilic areas are blue.
This scheme will not work if the surface was not created from a 
molecule or if that molecule is not currently present.

Surface Potential
^^^^^^^^^^^^^^^^^

The *surface potential* scheme colors each vertex according to the 
potential value at that vertex using a red-to-blue gradient from the surface
potential minimum to the surface potential maximum. This scheme differs from
the *electrostatic* scheme in that the coloring is based on the stored 
potential values as opposed to calculated potential values. Typically, surfaces
generated within |product| will not have any stored potential values. However,
surfaces created externally using OpenEye's **Spicoli** toolkit, for example, can 
store values in the potential field and as such can be colored accordingly.

Selection
---------

For surfaces created from molecules, the minimum selectable part
is the surface corresponding to a single atom.  A line of atom surfaces
can be selected by selecting one spot on a surface and then by holding down 
the *Shift* key when selecting another. This starting selection can be 
grown (and shrunk) using the :ref:`Selection<style_control_selection>` pane 
in the Style Control. 
Double-clicking on the surface will select the entire surface. 
For surfaces created without a molecule (usually outside of |product|), the 
minimum selectable part of a surface is a single vertex, and the above
operations work on vertices instead of atoms.

Symmetry
========

|product| supports symmetry operations.  This support includes a 
submenu under the *Edit* menu which controls displaying symmetry in the 3D window, 
and some items in the popup menu of the list window which allow setting or 
editing symmetry parameters.

Symmetry information may be read from certain files.  When |product| reads
PDB-format files which have valid CRYST1 records, symmetry information is
taken from that record for all molecules read from that file.  Similarly,
when |product| reads MTZ-format reflection files the symmetry information
is read from that file and, of course, |product| will read symmetry
information if it is present in an ``.oeb`` file.

When symmetry display is enabled, all symmetry operators which would result in 
a molecule within a certain distance (the *symmetry radius*) of the screen 
center are displayed. This means that as the view is translated, certain 
symmetry *replicates* will appear and disappear as they move into or out of
the symmetry zone.  There is, therefore, no need to manually re-calculate
the symmetry after translating the model.

Symmetry Menu
-------------

The Symmetry menu is located in the *Style* menubar.  The items
in the symmetry menu are:

* *Edit cell*  This item allows editing or setting of the unit
  cell and space group parameters of the active object, which will generally
  be either a reflection data set or a molecule.  In addition to the
  interactive symmetry display, information entered here will also be used
  for the CRYST1 record if the molecule is written as a PDB file.

* *Show unit cell* This toggles the display of the
  crystallographic unit cell of molecules which have symmetry information
  specified.

* *Show symmetry*  This toggles the display of symmetry-related
  molecules, hereafter called "replicates".  If enabled, *all* visible
  molecules with symmetry information will display symmetry.

* *Realize symmetry* The symmetry display above is only for display purposes.  
  If the user wishes to actually expand a molecule to
  produce one with "real coordinates" for the replicates, the symmetry
  must be "realized".  This option will prompt the user to determine if
  the current molecule(s) should be symmetry-expanded "in place" or if
  a new copy of the molecule(s) should be created and then symmetry
  expanded.  Only the symmetry operators currently enabled are used in the
  expansion.

* *Symmetry radius*  All symmetry operators which would produce a
  molecule within the symmetry radius of the screen center are shown.
  With a large symmetry radius, this may result in more replicates than
  symmetry operators, as each operator may be used more than once with
  different translations.  As a special case, if the symmetry radius is
  0.0, then each operator is used exactly once, with a translation which
  places the center of mass of the molecule in the default unit cell
  (i.e. the cell at the origin).

* *Symmetry operators* This submenu lists the symmetry operators
  for the *focused* molecule.  It is possible to toggle individual
  symmetry operators on and off.  This option is very useful for (e.g.)
  producing the biologically active dimer using crystal symmetry.  If
  there are no operators listed in this submenu, then either a) no object
  has the focus, b) the focused object is not a molecule, or c) the
  focused molecule does not have symmetry information.  Currently,
  symmetry information is only read from the CRYST1 record of PDB files.

* *No symmetry color* No special coloring will be used for
  symmetry replicates.

* *Single symmetry color* A single (distinct) color will be used
  for all symmetry replicates.

* *Color by operator* Each symmetry operator is assigned a color.
  All symmetry replicates resulting from the same operator (e.g. X, -Y, Z)
  have the same color no matter which unit cell they are in

* *Unique color* Each replicate is given a distinct color, so
  that no two replicates have the same color.  Since the number of
  replicates can change depending on the symmetry radius and/or the current
  center, this has the somewhat unfortunate side-effect that occasionally
  translations cause every molecule to be recolored.

.. note::

   After realizing symmetry, if "Show symmetry" is left on there
   could be a very large number of molecules on screen as each new molecule
   is also symmetry expanded.



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. _examples:

*********************
Examples
*********************

|product| ships with a large collection of example data as well as example
scripts. The examples are contained in the "examples" directory in the 
|product| installation. This directory can be directly accessed from within
|product| by selecting the "Open Examples Directory" option in the "Help" 
menu.

A fast way to get started exploring the example data and scripts is to open
the ``add_menu_updating.vpy`` script (see :ref:`Opening Files<opening_files>`) which will add 
an "Examples" menu to the main menu bar. This new menu will contain an entry
for each example data file and script provided. Selecting any one of these
options will open the associated file in the current instance of |product|.

Data
====

|product| ships with a directory of example data for the user to experiment with 
in the event that other input files are not immediately available. Included in 
this directory are:

* ``cox2_good.sdf.gz`` - This is a large set of Cox-2 inhibitors which 
  contains associated molecular data which makes this an excellent example file
  for use in the spreadsheet.

* ``MMFF94.mol2.gz`` - This is another large set of small molecules but 
  it contains a significantly greater amount of diversity among the molecules than
  the previous file. This file is an excellent example file for browsing 
  through a large data set as well as for exploring the many different ways that
  shape and chemistry may be visualized with |product|.

* ``1ll5.grd`` - This is a grid file containing electron density data 
  corresponding to crystallography data of the ligand structure found in the
  following file. It provides an excellent example of |product's| grid visualization 
  capabilities and also works well to provide a context for the associated
  ligand file.

* ``1ll5.lig.pdb.gz`` - This small molecule is a beta-lactamase 
  inhibitor positioned in its crystallographically determined binding location. 
  This file combined with the actual beta-lactamase protein found in the 
  following file provide an excellent example of how |product| can be used to 
  visualize small molecule-protein interactions. When visualizing this molecule, 
  be sure to observe the three excellent hydrogen bonds it makes with the protein.

* ``1ll5.nolig.pdb.gz`` - This file contains the crystallographically 
  determined structure of a beta-lactamase protein. Its bound inhibitor can be
  found in the previous file. This file is an excellent example of the many
  ways that proteins can be visualized in |product|. Be sure to observe its many
  internal hydrogen bonds, particularly in the active site.

* ``1ll5.omega.oeb.gz`` - This file contains a large number of 
  conformations of the beta-lactamase ligand (``1ll5.lig.pdb.gz``) generated 
  with OpenEye's conformer generation program *OMEGA*. This file is an 
  excellent example of |product's| ability to handle multi-conformer molecules as well 
  as its ability to view *OMEGA* output. It is important to note that this 
  file is not in the same coordinate space as the three previous files and as 
  such should not be expected to appear in the same location on screen with the 
  above files.

Scripts
=======

|product| ships with a large directory of example scripts to both highlight 
the many different aspects of |product's| scripting capability and to help 
guide the user to begin developing their own scripts. Each one of the 
example scripts provided will be discussed in detail in the following 
sections.  Note that not all of the example scripts will actually do anything
interesting when you load them directly into VIDA.  Many of them illustrate
the creation of useful functions, but may not actually call these functions.

The location of the example scripts is platform-specific, but can be found
from within |product| by selecting the "Open Examples Directory" option in the "Help" 
menu.

.. _add_menu.vpy:

add_menu.vpy
------------

This example shows how to add a new menu to the top level main menu (if it
does not already exist). Note that the call to ``MenuAddSubmenu`` returns
the menu name to be used to reference that menu in subsequent functions.
It is important to use the returned name to avoid potential naming clashes
when accessing the menu.

.. oe:source:: add_menu.vpy
   :frag:     ADD_MENU
   
Once the top level menu has been created, this example shows how to add 
submenus to the newly created menu.

.. oe:source:: add_menu.vpy
   :frag:     ADD_SUBMENUS
   
Lastly, this example details how to populate the newly created submenus with
the relevant items and their associated Python commands. In this case, the
script looks for the *Examples* directory that ships with |product| and then
scans that directory for example data and scripts which are then referenced
in the appropriate submenus.

.. oe:source:: add_menu.vpy
   :frag:     POPULATE_SUBMENUS

.. _add_menu_item.vpy:

add_menu_item.vpy
-----------------

This example shows how to add a new entry to an already existing menu. The
new entry when clicked on in the menu will execute the specified Python
command. 

.. oe:source:: add_menu_item.vpy
   :frag:     ADD_MENU_ITEM

.. _add_menu_updating.vpy:

add_menu_updating.vpy
---------------------

This example shows how to create a new menu which is populated by a specified
Python command each time the menu is shown. In this example, each time the
user clicks on the *Examples* menu, the specified ``UpdateExamplesMenu`` 
function will be called before the menu is actually shown.

.. oe:source:: add_menu_updating.vpy
   :frag:     ADD_MENU

The ``UpdateExamplesMenu`` function is defined below. The first thing this
function does is to clear the previous contents of the menu by calling the
``MenuRemoveAll`` function. It then searches for the *Examples* directory that
is provided by |product| and then scans that directory for example data and
scripts which are then referenced in the appropriate submenus.

.. oe:source:: add_menu_updating.vpy
   :frag:     POPULATE_MENUS

The process by which the menus are created and populated here is somewhat 
different from the :ref:`add_menu.vpy` example due to the dynamic nature of
the menu creation in this example.

.. _add_toolbar_button.vpy:

add_toolbar_button.vpy
----------------------

This example shows how to add a simple button to the main application toolbar
which when pressed will execute the specified Python command (in this case
`DeleteAll`).

.. oe:source:: add_toolbar_button.vpy
   :frag:     ADD_TOOLBAR_BUTTON

It is worth nothing that ``ToolbarRemove`` is called before 
``ToolbarAddViaNamedIcon`` in order to ensure that multiple buttons will not
be created and thus fill up the toolbar if the script is run multiple times.

.. _add_toolbar_toggle.vpy:

add_toolbar_toggle.vpy
----------------------

This example shows how to add a simple toggle button to the main application
toolbar. A *toggle* button is different from a standard *push* button in that 
it has two potential states and can display a different icon and execute 
different Python commands based on the current state.

.. oe:source:: add_toolbar_toggle.vpy
   :frag:     ADD_TOOLBAR_TOGGLE

As seen in the example above, a toggle button also supports specification of an
*update* command which may be executed to determine the current state of the 
button. The specified *update* code is normally executed when a call to 
``ToolbarUpdate`` or ``ToolbarItemUpdate`` is made.

.. oe:source:: add_toolbar_toggle.vpy
   :frag:     OVERRIDE_TO_ENABLE_UPDATES

To ensure that this particular toggle button is kept in sync with the state of
application, the ``AppMainWindowSet`` function is overridden to include a call 
to ``ToolbarItemUpdate``. This is particularly important as there are other 
common pathways within |product| which can have the same effect as toggling 
this button (such as changing the main window through the *Windows* main menu).

.. _calc_et.vpy:

calc_et.vpy
-----------

This example shows how to create a function using the **OEChem** and **Zap**
Python toolkits from OpenEye to calculate the electrostatic Tanimoto between
two molecules currently loaded in |product|.

.. oe:source:: calc_et.vpy
   :frag:     CALC_ET

The ``CalculateET`` function retrieves copies of the specified molecules from
|product|, prepares them for the calculation and then performs the actual
calculation. The resulting Tanimoto value is then returned by the function.

.. oe:source:: calc_et.vpy
   :frag:     CALC_ET_LIST

The ``CalculateETForList`` function expects a |product| list ID as a parameter. 
The function will then assign the first molecule in the list to be the 
reference structure against which the ET will be calculated for all the other
molecules in the list.

Instead of returning a list of ET values, the calculated ET is stored as a data
field in the application spreadsheet using the ``DataAdd`` function.

.. _calculate_clashes.vpy:

calculate_clashes.vpy
---------------------

This example shows how to use the **OEChem** toolkit within |product| to 
detect and then visualize intermolecular clashes.

.. oe:source:: calculate_clashes.vpy
   :frag:     CALCULATE_CLASHES

The ``CalculateClashes`` function takes the IDs of two molecules and a cutoff
distance used to determine the intermolecular clashes. The clashes are 
determined by calling the **OEChem** function ``OEGetNearestNbrs``. Any clashes
that are found are then visualized as distance monitors (colored red) between 
the clashing atoms.

.. _cluster_browsing.vpy:

cluster_browsing.vpy
--------------------

This example is one of the most complicated examples included in this set as
it incorporates many aspects of |product| scripting into a single example. This
example shows how one can create their own custom cluster browsing interface 
within |product| using clustering information stored in the SD data of the 
relevant molecules.

The first part of the example attempts to locate an associated '.ui' file which 
defines the layout of the widget used in this example. The '.ui' file is 
expected to be located in the same directory as the script. If the '.ui' file 
is not found, the script will throw an exception.

.. oe:source:: cluster_browsing.vpy
   :frag:     LOCATE_UI_FILE

A picture of the widget template defined by the '.ui' file can be seen in the 
figure :ref:`below<figure_cluster_browsing_ui>`. This widget was created using 
the *Qt Designer* application and 
will be loaded into an actual class using PySide2.

.. _figure_cluster_browsing_ui:

.. figure:: /_images/cluster_browsing_ui.png
   :scale:  75
   :align:  center
   
   **cluster_browsing Widget Template**

The actual widget class is created below using PySide2. The class constructor 
performs the required initializations, loads the ui file, and sets up the
necessary connections between the internal widgets and the classes methods.

.. oe:source:: cluster_browsing.vpy
   :frag:     DEFINE_WIDGET
   
Once the ``ClusterBrowser`` widget class has been defined, an actual instance 
of that class needs to be created. In order to ensure that the 
``ClusterBrowser`` can be embedded into frame around the main window, a 
``QDockWidget`` is created to contain the ``ClusterBrowser`` and then added
to the right-hand side of the main window.

In addition, a menu item is added to the *Tools* menu which will prompt the
user to specify an input file and then will show the ``ClusterBrowser``
widget.

.. oe:source:: cluster_browsing.vpy
   :frag:     CREATE_WIDGET

As described above, the molecules are expected to contain cluster information
in their associated SD data. This data can be viewed and processed in the 
spreadsheet. To help organize this information, a custom sorting function is
defined below.

.. oe:source:: cluster_browsing.vpy
   :frag:     SORT_FXN
   
The ``ViewClustersID`` function defined below takes as a parameter the ID of a 
list of molecules already loaded into |product| which contain the appropriate 
SD data. This function then creates a new filtered spreadsheet called "Ideas"
which only contains the cluster centroids (or "Ideas"). For each "Idea" there
is an associated "Idea Group" of other molecules. A new filtered spreadsheet
is also created for each individual "Idea Group", although it is hidden from 
the main spreadsheet tab by default.

This function also populates the drop-down menu in the ``ClusterBrowser`` 
widget defined above with an entry for each of the "Idea Groups".
   
.. oe:source:: cluster_browsing.vpy
   :frag:     VIEW_CLUSTERS
   
The ``ViewClusterFile`` function loads a specified molecule file and then 
passes the ID of the newly created list to the ``ViewClustersID`` function
to setup the view. Before calling this function, the spreadsheet window is
hidden to prevent flickering as many spreadsheet operations take place in
the ``ViewClustersID`` function.

.. oe:source:: cluster_browsing.vpy
   :frag:     VIEW_CLUSTER_FILE
   
The ``ViewIdeaGroup`` function takes the index of an "Idea Group" as a 
parameter. If the idea group exists, the associated spreadsheet will be shown.
In addition, the first 12 molecules in the "Idea Group" are displayed in tiled
mode in the main window (either 2D or 3D, depending on which option the user 
has selected).

.. oe:source:: cluster_browsing.vpy
   :frag:     VIEW_IDEA_GROUP

.. _docking_view.vpy:

docking_view.vpy
----------------

This example shows how to create a function which replicates the behavior of
the ``FRED View`` tool available under the *Tools* menu. The function takes a
protein ID, a ligand ID and an optional list of IDs corresponding to docking
results. 

.. oe:source:: docking_view.vpy
   :frag:     DOCKING_VIEW

As expected from the ``FRED View`` behavior, this function makes the 
protein-ligand complex visible and centers the view on the ligand in the 
active site. Furthermore, it adds a surface to the protein, colors and crops 
the surface to a certain distance from the ligand, and hides residues a 
certain distance from the ligand. The function also adds residue information
labels as well as turns on the display of hydrogen bonds.

.. _fix_file_omega.vpy:

fix_file_omega.vpy
------------------

This example incorporates widget creation using PySide2 and interaction with
the **OmegaTK** toolkit. The example shows how **OmegaTK** can be used to 
generate new conformations for a molecule within |product| and furthermore how
the user can fix certain portions of the molecule during the conformer 
generation process.

The first part of the example shows how the widget is created using PySide2
from an associated '.ui' file. The '.ui' file is expected to be located in the 
same directory as the script. If the '.ui' file is not found, the script will 
throw an exception. In addition, this part of the example also creates the 
OEOmega object which will be used later to generate the conformations.

.. oe:source:: fix_file_omega.vpy
   :frag:     CREATE_WIDGET
   
A picture of the widget template defined by the '.ui' file can be seen in the 
figure :ref:`below<figure_fix_file_omega>`. 

.. _figure_fix_file_omega:

.. figure:: /_images/fix_file_omega_ui.png
   :scale:  75
   :align:  center
   
   **fix_file_omega Widget Template**

The following example code details the actual function that will be called
to generate the new conformations. It shows how configuration information is
pulled from the widget as well as how the fixed portion of the molecule is
determined and specified to the Omega object.

.. oe:source:: fix_file_omega.vpy
   :frag:     GENERATE_CONFS

This final section of code connects up the function defined above to the
appropriate button and then creates a menu item in a 'Special' menu to open
the widget.
   
.. oe:source:: fix_file_omega.vpy
   :frag:     CONNECT_FUNCTIONS

.. _load_and_split_pdb.vpy:

load_and_split_pdb.vpy
----------------------

This example shows how to load a file directly from the PDB and then split
that file into its individual components. This first section details the
function which fetches the molecules corresponding to the specified PDB codes
and then loads them into |product|.

.. oe:source:: load_and_split_pdb.vpy
   :frag:     LOAD_FROM_PDB

The following section details the ``LoadAndSplitPDBs`` function which
calls the ``LoadMoleculesFromPDB`` function defined above and then
iterates over the newly loaded molecules, splits them into their individual
components, and then removes the original complex.

.. oe:source:: load_and_split_pdb.vpy
   :frag:     SPLIT_PDB

This final section shows how a new menu item is created to prompt the user for
the desired PDB codes and then to call the above function. This section also 
shows how to replace the command associated with a menu item in the event that
the menu item has already been created.

.. oe:source:: load_and_split_pdb.vpy
   :frag:     ADD_MENU_ITEM

.. _molecule_alignment.vpy:

molecule_alignment.vpy
----------------------

This example shows how to create a moderately complex widget using PySide2 to
perform molecule alignments using one of a variety of techniques including: 
shape & color, RMSD, or sequence. 

The following block of code shows the function which performs the shape and 
color alignment of two specified molecules using the **OEChem** and **OEShape** 
toolkits.

.. oe:source:: molecule_alignment.vpy
   :frag:     SHAPE_ALIGN

The following block of code shows the function which performs the RMSD 
alignment of two specified molecules using the **OEChem** toolkit. Note that 
before the alignment is done, the graphs of the two molecules are compared by
the generation of canonical SMILES.

.. oe:source:: molecule_alignment.vpy
   :frag:     RMSD_ALIGN

The following block of code shows the function which performs the sequence
alignment of two specified proteins using the **OEChem** toolkit. Note that a 
check for residue information is performed on both molecules to ensure that
a sequence alignment is even feasible.

After the alignment is performed in this function, the two molecules are both
made visible, uniquely colored and displayed in ribbon style.

.. oe:source:: molecule_alignment.vpy
   :frag:     SEQUENCE_ALIGN

The following section shows how the main widget is hand-coded (as opposed to
using a '.ui' file from *Qt Designer*) using PySide2.

.. oe:source:: molecule_alignment.vpy
   :frag:     CREATE_WIDGET

This next section shows the definition of all the functions that provide the
interface between the widget and the desired actions.

.. oe:source:: molecule_alignment.vpy
   :frag:     CREATE_WIDGET_FUNCTIONS

This final section shows how the widget buttons are connected up to the support
functions defined in the section above.

.. oe:source:: molecule_alignment.vpy
   :frag:     CONNECT_FUNCTIONS

.. _open_from_pdb.vpy:

open_from_pdb.vpy
-----------------

This example shows how to load one or molecule molecules directly from the PDB.
The following section details the function which fetches the molecule(s) from
the PDB corresponding to the specified PDB code(s) and then loads them into 
|product|.

.. oe:source:: open_from_pdb.vpy
   :frag:     LOAD_FROM_PDB
   
This final section shows how a new menu item is created to prompt the user for
the desired PDB codes and then to call the above function. This section also 
shows how to replace the command associated with a menu item in the event that
the menu item has already been created.

.. oe:source:: open_from_pdb.vpy
   :frag:     ADD_MENU_ITEM

.. _override_open_1.vpy:

override_open_1.vpy
-------------------

This example shows how to override the ``Open`` function in |product| to 
customize the behavior when a file is opened. In this case, the original
function is cached so that it can be called later within the new function.
Once the file has been loaded, this function iterates over all the newly
loaded molecules looking for atoms with formal charges. If a formal charge
is found, a label corresponding to the charge is added to that atom.

.. oe:source:: override_open_1.vpy
   :frag:     OVERRIDE_OPEN

.. _override_open_2.vpy:

override_open_2.vpy
-------------------

This example shows how to override the ``Open`` function in |product| to
customize the behavior when a file is opened. In this case, the original
function is cached so that it can be called later within the new function.
Once the file has been loaded, this function iterates over all the newly
loaded molecules looking for molecules that do not have a dimension of 3.
In cases where the dimension is not 3, 3D coordinates are generated for the
molecule using Omega.

.. oe:source:: override_open_2.vpy
   :frag:     OVERRIDE_OPEN

.. _search_chemspider.vpy:

search_chemspider.vpy
---------------------

This example shows how to search `ChemSpider <http://www.chemspider.com/>`_ 
using the active molecule as a query. The active molecule is converted to a
SMILES string which is inserted into the ChemSpider search URL.

.. oe:source:: search_chemspider.vpy
   :frag:     SEARCH_CHEMSPIDER
   
The following section shows how the above function is bound to a button which
is placed in the main application toolbar.
   
.. oe:source:: search_chemspider.vpy
   :frag:     ADD_TO_TOOLBAR

.. _search_pubchem.vpy:

search_pubchem.vpy
------------------

This example shows how to search `PubChem <http://pubchem.ncbi.nlm.nih.gov/>`_
using the active molecule as a query. An IUPAC name is generated for the active
molecule using the OpenEye **Lexichem** toolkit. The generated name (if valid) is then
inserted into the PubChem search URL.

.. oe:source:: search_pubchem.vpy
   :frag:     SEARCH_PUBCHEM
   
The following section shows how the above function is bound to a button which
is placed in the main application toolbar.

.. oe:source:: search_pubchem.vpy
   :frag:     ADD_TO_TOOLBAR

.. _simple_pyside2.vpy:

simple_pyside2.vpy
-----------------------

This example shows how to create a very simple widget with a functioning button 
using PySide2 and how to display it within |product|.

.. oe:source:: simple_pyside2.vpy
   :frag:     SIMPLE_PYSIDE2

.. _void_volumes.vpy:

void_volumes.vpy
----------------

This example shows how to create a function which generates and then loads into
|product| the calculated void volume between a protein and a ligand. 

.. oe:source:: void_volumes.vpy
   :frag:     CALC_VOID_VOLUMES


.. _extensions:


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


*********************
Extensions
*********************

|product| provides an *Extension* facility to allow users to
modify and extend the user interface and general functionality of the program
using Python scripting.  |product| extensions can expose functionality of all the 
OpenEye Toolkits (with appropriate licenses) or third party applications,
and can also be used to customize |product's| user experience.
They provide a convenient way to carry out regular tasks, streamline 
corporate workflows, and connect |product| to other systems.  A simple example 
might be the ability to search a corporate database by corporate compound ID 
and load that molecule into |product|.

An individual extension is implemented as a Python module which, once installed, 
is imported into |product| at startup. Extensions can be added, removed, 
updated, and/or disabled from the :ref:`Extension Manager<extension_manager>`.

.. _example_extensions:

Example Extensions
==================
A number of example extensions are available in the |product| distribution for
use as-is or as starting points for writing custom extensions (Python source code
for these is included).  The provided extensions are:

- **Alternate Location Browser**: Browse through alternate conformations of a protein (as defined in a PDB file) and take snapshots of selected configurations. *(Additional license required: none)*
- **Binding Site Align**: Align proteins based on binding site residues. *(Additional license required: none)*
- **Bump Checker**: Displays intermolecular bump interactions. *(Additional license required: none)*
- **Center on Ligand**: Automatically locates and centers the view on a ligand in a protein-ligand complex. *(Additional license required: none)*
- **Color by Atom Properties**: Colors atoms by atom-level properties. *(Additional licenses required: none)*
- **Color by SD Data**: Colors molecules by SD data values. *(Additional licenses required: none)*
- **Docking**:  Performs docking of ligands against pre-prepared receptors.  *(Additional license required: **OEDocking TK**)*
- **FastROCS Client**: Submits a search to a FastROCS server, and loads the results into |product|.  *(Additional license required: none.  Also requires access to a FastROCS server.)*  
- **Fit**:  Performs shape-based alignments. *(Additional licenses required: **Shape TK**, **Omega TK**)*
- **Interaction Map**: Displays pattern-based intermolecular interactions. *(Additional licenses required: none)*
- **Ligand Minimizer**: Perform minimizations in an active site. *(Additional licenses required: **Szybki TK**)*
- **Molecule Alignment**: Perform molecular alignments based on shape & color, sequence or RMSD. *(Additional licenses required: none. Optional: **Shape TK**)*
- **OMEGA**: Generate molecule conformations using the OMEGA software. *(Additional licenses required: **Omega TK**)*
- **Void Volumes**: Create void volumes around a ligand in a protein-ligand complex. *(Additional licenses required: **Spicoli TK**)*
- **3D Molecule Filter**: Filters lists of aligned molecules, *e.g.*, ROCS results, based on positions of features in 3D. *(Additional licenses required: none)*

Although these extensions are distributed with |product|, you will need to 
install them with the :ref:`Extension Manager<extension_manager>` before using them.

.. _extension_manager:

Extension Manager
=================

The *Extension Manager* is accessed under *Edit > Extensions*, and provides
a way to add, activate, and remove extensions.  Its use is 
illustrated here for the example extensions that ship with |product|.

.. _add_extensions:

Add Extensions
--------------

To "subscribe" to the set of example extensions, open
the *Extension Manager*, and click on the *Manage Subscriptions...* button
to open the Manage Subscriptions dialog, then click the folder icon to browse 
to the directory
where the example extensions are located.  This will be under the OpenEye
installation directory, in the subdirectory examples/vida/[version]/extensions.

.. _figure_add_examples:

.. figure:: /_images/add_examples.png
   :scale:  80
   :align:  center
   
   **Basic steps to add extensions** 

There is a file in this directory named examples.pyxs.  This type of file is
called a subscription, and simply contains a list of URLs pointing to 
available extensions.  Select this file, then click the Open button to install
all of the subscription's extensions.  The list of extensions in the
subscription will be shown in the *Manage Subscriptions* dialog.  You can
disable individual extensions using the checkboxes that appear beside each
extension name.
 
Once a subscription has been added, an entry for each available extension
will be displayed. Every extension has
a name and a version (to enable updates), as well as a brief description and a
list of any other required OpenEye toolkits for the extension to run. Additionally,
each extension appears with four buttons: **Info**, **Refresh**, **Delete**, 
and **Enable**.  

All of the example extensions, once added, will appear in the *Extensions* menu
in |product's| main window, although custom extensions can be made to show
up in other menus, as buttons in toolbars, or as other user interface elements.

.. _current_extensions:

Installed Extensions
--------------------
   
The *Installed Extensions* list can be seen in 
:ref:`Figure: Installed Extensions<figure_current_extensions>`. It provides the 
user with the ability to view which extensions are installed as well as to 
update, uninstall, or disable the extension.
   
.. _figure_current_extensions:

.. figure:: /_images/current_extensions.png
   :scale:  80
   :align:  center
   
   **Installed Extensions**
   
Clicking on the **About** button for an extension will display more detailed
information about the extension than is seen in this section. Clicking on the
**Update** button will cause |product| to check for an updated version of the
extension and if found, install it. Clicking on the **Delete** button will
cause the extension to be uninstalled when |product| exits. Clicking on the 
**Disable** button will prevent this extension from being imported the next
time |product| is run. A disabled extension will still be listed in the *Installed
Extensions* section and can be reenabled by clicking on the **Enable** button.

.. _updating_extensions:

Updating Extensions
-------------------
  
|product| checks for extension updates at startup and will install 
the updates directly if found.  Extensions can also be manually updated using
the **Update** buttons in the Installed Extensions list.

Managing Subscriptions
----------------------

The **Manage Subscriptions...** button opens a dialog with a list of your current
subscriptions.  In this dialog you can add or remove a subscription.  Removing
a subscription will uninstall all of its extensions.  You can also renew a 
subscription, which will update all of its extensions at once. In the 
**Existing Subscriptions** list, you can enable or disable individual extensions
using the checkboxes next to the extension names.
 
.. _figure_manage_subscriptions:

.. figure:: /_images/manage_subscriptions.png
   :scale:  75
   :align:  center

   **The Manage Subscriptions Dialog**

.. _creating_extensions:

Creating Extensions
===================

Creating an extension for |product| is very easy. At its simplest level, a 
|product| extension is simply a directory containing an ``__init__.py`` file 
and any associated data files or additional scripts. Once this directory is
installed, the Python interpreter will import this extension every time the
application starts. The process of importing the extension will cause all the
code in the ``__init__.py`` file to be run.

The OEVidaExtension Base Class
------------------------------

Using the OEVidaExtension base class can simplify the creation of an
extension script.  When an extension is derived from OEVidaExtension, 
the following are automatically handled for you:

* Importing of the PySide2 and other modules
* Adding the extension to the Extensions menu
* Loading of a Qt .ui file and creating a docked window from it
* Providing Python access to the individual widgets in a Qt .ui file
* Calling a one-time initialization function within the extension script

The basic steps for creating an extension using OEVidaExtension are:

1. If your extension needs a user interface, create a .ui file using Qt Designer.  Give it the same first name as your extension.
2. Create a .pyx file (:ref:`see below<distributing_extensions>`) containing information about the extension.  The "title" record in this file is the part OEVidaExtension cares about.  This step is optional during development of an extensions, but must be done before the extension is installed or deployed.
3. Create a Python script with a class derived from OEVidaExtension
4. Give your class an InitializeUI() method, where initialization of the user interface takes place
5. Create an object from your class.  You're done!

The following script illustrates basic use of the OEVidaExtension class:

.. .. ..oe:source:: simple_extension.py

Details for Using the OEVidaExtension Class
-------------------------------------------

The constructor for OEVidaExtension accepts the following arguments:

* **extensionPath** *(Required)*: This should be the ``__file__`` special variable, and is used to find the .pyx and .ui files.
* **menuName** *(Optional)*: Specifies what menu the extension should appear in.  If omitted, this defaults to 'Extension'.  If you want to specify a submenu, *e.g.*, 'Extensions > Proteins', use the form '/Extensions/Proteins'.  Note the leading forward slash character.
* **windowSubmenu** *(Optional)*: This specifies an optional name of a submenu in the Window menu, where this extension's window can be toggled on and off.  The default value is '/Extensions', which puts an entry in an Extensions submenu of the Window menu.
* **command** *(Optional)*: Specifies a Python command to be issued when this extension is invoked from the menu.  If left blank, selecting the extension from the menu will make its window visible.
* **uiFile** *(Optional)*: If the .ui file's name does not match the extension's name, it can be specified here.
* **title** *(Optional)*: Specifies a title to be used in the menus and on the title bar of the extension's window.  Used only if a title cannot be found in a .pyx file.  This can be useful while developing an extension, if a .pyx file has not yet been created.

The constructor will create two member variables that may be useful:

* **self.ui**: This is an object whose members represent the named widgets within the extension's .ui file.  For example, if a QPushButton named "myPushButton" is defined in the .ui file, you can refer to it using ``self.ui.myPushButton`` within the script.
* **self.dockWidget**: This is a QDockWidget containing the extension window.  If your script needs to hide, show, or otherwise access the extension's window, it can do so using this variable.

A class derived from OEVidaExtension must implement a method called
InitializeUI(), which performs one-time initialization of the class.  This
method is also responsible for connecting the Qt widgets in the user
interface to the methods in your class.

Some extensions won't need a .ui file (for example, a menu item that 
performs an action directly).  In such a case, be sure to provide a
``command`` argument to the constructor, since the default menu action 
is to display the extension's (in this case nonexistent) window.

Extension Preferences
---------------------

The OEVidaExtension class provides several methods for managing preferences for extensions.  
This allows extensions to remember values from one |product| session to the next.  These 
preferences are stored as key-value pairs, and are preserved in state (.oes) files so that 
extensions can be set to a particular starting point when a state file is loaded.  Preferences 
can be private to an individual extension, or can be "shared" among all extensions.  The methods 
for managing preferences are:

* ``SetPref(self, key, value, shared = False)`` -- Sets the named preference to the specified value.  In this and other methods, the *shared* parameter specifies whether this preference is to be shared by all extensions.  If *shared* is true, other extensions will be notified when its value has changed, via the SharedPrefChanged method (see below).
* ``GetPref(self, key, defaultValue, shared = None)`` -- Returns the value of a preference.  If no such preference exists yet, *defaultValue* is returned.  If *shared* is True, a shared preference value is returned.  If *shared* is False, a private preference value is returned.  When *shared* is None, the private value is returned if it exists; otherwise the shared value is returned.
* ``RemovePref(self, key, shared = False)`` -- Removes a preference.
* ``ClearPrefs(self, shared = False)`` -- Removes all preferences for an extension.
* ``SharedPrefChanged(self, key, value)`` -- Called when a shared preference has changed.  The default implementation of this function does nothing.  You can reimplement it in a class derived from OEVidaExtension if you want your extension to do something when shared preferences change.

Notification Methods
--------------------

The OEVidaExtension class provides two methods to allow extensions to be notified when |product|
is finished starting and when it is about to close.  The default implementations of these methods
do nothing, but you can reimplement them in derived classes to perform actions on startup and
shutdown.  These methods are:

* ``StateReset(self)`` -- Called when the state of |product| has been reset.  This happens at program startup, when a state (.oes) file has been loaded, or when all objects have been cleared using the ``DeleteAll()`` function.
* ``AppShutdown(self)`` -- Called when |product| is about to exit, but before preferences have been saved.  Reimplement this method if your extension needs to save some preferences or perform other tasks before closing down.

.. _distributing_extensions:

Distributing Extensions
=======================

Extensions are distributed as directory archives (e.g. tar or zip files) 
coupled with a meta-file containing detailed information about the extension.
The meta-file is a simple plain text file named with a .pyx file extension.
This file is intended to provide all the associated details about the extension 
in an easily accessible way. The data contained in the file includes:

* Author
* Title
* Description
* Version
* Name of the directory to be extracted
* Required version of |product|
* Any required OpenEye toolkits
* File's own URL (so the file always knows where it came from)
* URL of the directory archive containing the extension.
  Note that this URL can be a "short" filename, which implies that the archive
  can be found in the same directory as the .pyx file.
* An optional specification of the order in which the extension should be loaded

.. .. ..oe:source:: example.pyx
   :caption:  A simple example of an extension meta-file (.pyx)
   :refnum:   1

When distributing multiple independent extensions it may be useful to organize
them together into groups called *Extension Sources* or subscriptions.
|product| may subscribe
to an *Extension Source* to get a list of available extensions for 
installation. The *Extension Source* itself (as described in 
:ref:`add_extensions`) is a simple plain text file named with a .pyxs file 
extension which contains a title followed by a list of URLs to a collection of
extension meta-files.  These URLs can be simple file names, in which case
|product| will assume these reside in the same location as the .pyxs file.

.. .. ..oe:source:: extensions.pyxs
   :caption:  A simple example of an extension source file (.pyxs)
   :refnum:   2

Automatic Subscriptions
-----------------------

Users can be automatically subscribed to an extension source through the
environment variable |product_ext_url|.  When this environment variable is
set to the URL of a .pyxs file, |product| will install the full set of 
contained extensions without requiring any user intervention.  To automatically
subscribe to multiple extension sources, set the |product_ext_url| variable to
a comma-separated list of URLs.



.. _file_io:


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


*********************
File I/O
*********************

Opening Files
=============

.. _opening_files:

There are multiple mechanisms by which a file can be loaded in |product|. The 
simplest method is to select the *Open* option in the *File* menu. This will
launch a file selection dialog which prompts the user for the desired file(s)
which will subsequently be loaded. A short list of the most recently opened
files can also be found in the *File* menu under the *Recents* (or *Open 
Recents* on Mac OS X) submenu. Selecting an option in this submenu will load
the associated file. There is an *Open All* option at the bottom of the
submenu. Files can also be loaded by specifying them on the command line when
starting |product|, by dragging the file of interest onto the |product| desktop
icon, or by dragging the file of interest into the *List Window*.

In addition to the *Open* menu item, there is a separate *Open State* item 
which filters out all files except for state files. State files can be opened
using any of the mechanisms described above, but their special nature 
warrants its own option. 

There is also an *Open Special* submenu which contains three default options: 
*Script*, *From PDB*, and *MTZ*. The *Script* option prompts for a file, but filters
out all files except for Python scripts. The *From PDB* option prompts for a
PDB ID and then fetches the associated molecule directly from the PDB. The *MTZ*
option prompts for a crystallographic MTZ file, and then allows the user
to select the maps and fields to be loaded from the file.  The
*Open Special* submenu also serves as an excellent target area for adding
custom open operations via the scripting interface.

Molecules
---------

.. _opening_molecules:

Multiple molecular file formats are supported for reading and include :

* OpenEye binary format (version2: .oeb)
* OpenEye design unit format (.oedu)
* MDL, RDF, and SDF
* Tripos Mol2, Mol2H
* Daylight SMILES, canonical SMILES, and isomeric SMILES
* ChemDraw CDX
* ISIS Sketch
* MacroModel
* MOPAC
* PDB, MMCIF
* XYZ

As is often the case with file formats, the meaning and use of certain 
fields within a format may change over time which can potentially lead 
to problems interpreting those files. |product|, using OpenEye's **OEChem** 
toolkit, makes its best effort to interpret all files correctly; however, it 
does provide a mechanism to allow the user to override the handling of certain 
formats (SMILES, PDB, Mol2, XYZ, and MacroModel). The ability to change the 
*flavor* of a specific format can be done in the application preferences.
:ref:`Figure: Molecule flavors<figure_flavors>`.

.. _figure_flavors:

.. figure:: /_images/flavors.png
   :scale:  75
   :align:  center
   
   *Molecule flavors*

An important flavor to be aware of is the *Data* flavor of the PDB format. 
Enabling this flavor allows VIDA to properly handle alternate residue locations
specified in the PDB file. 

In addition to changing the flavor of a format, there are a few other 
advanced options available when reading molecules including aromaticity model
specification and conformer joining. The desired aromaticity model to be 
applied can be specified in the pull down menu next to the *Aromatic Model* 
label. The *Join Conformers* checkbox controls whether or not adjacent 
molecules in an input file will be tested on reading to determine whether they
are unique compounds or simply different conformers of the same molecule. The
specific test to be performed can be specified in the pull down menu next to the
checkbox. For more specific details on the available aromaticity models and 
conformer tests, please see the **OEChem** documentation.

.. note::
  
   Because these advanced options are available 
   through the application preferences, they will be remembered by |product| and
   automatically applied in future *Open* operations unless they are subsequently
   modified or restored.

Grids
-----

.. _opening_grids:

Multiple grid and map formats are supported for reading and include:

* OpenEye grids
* ASCII grids
* GRASP/DelPhi grids
* CCP4 maps
* XPLOR maps
* MTZ maps

**MTZ** maps are a little special in the sense that the contents
of the files do not follow a standard format and the relevant
data columns for reading phases and amplitudes can be
named arbitrarily.  By default, |product| attempts to 
find common column names that are used by standard refinement
packages.

If a **MTZ** file cannot be opened, an error message is displayed
suggesting the use of the menu item `File/Open Special/MTZ...`

To have more control over which maps are created, use the `File` menu
option `Open Special/MTZ...`.  This opens a dialog that allows selection of both the MTZ
columns and the desired output maps.

.. _figure_mtz:

.. figure:: /_images/mtz.png
   :scale:  75
   :align:  center

   *MTZ Open Dialog*

Simply select the appropriate columns and map types to generate and
click "OK".

Surfaces
--------

.. _opening_surfaces:

Multiple surface formats are supported for reading and include:

* OpenEye surfaces
* GRASP surfaces

State Files
-----------

.. _opening_state:

The entire state of a session can be stored in a single file called a *State
File* (.oes). A state file contains all of the molecules, grids, and surfaces
that were loaded in |product| at the time the state file was created. In 
addition, the state file preserves the actual view, layout, and properties of 
that session. State files provide an extremely convenient way to save sessions
for later work or to share with collaborators. Furthermore, state files are the
fastest method of reading and writing large data sets.

To load a state file, choose the *Open State* option in the *File* menu and 
then select the desired state file. State files can also be loaded from the 
command line. It is important to note that loading a state file during a run 
will clear the current state before loading the new one. Therefore, be sure to
save the current state before loading a new state if keeping the current state
is desired. Furthermore, since state files contain the entire state of the
application that generated them, loading a state file will overwrite local 
preferences; however, they will not be saved on exit.

.. note::

   State files are not backwards compatible with older versions of VIDA

Python Scripts
--------------

.. _opening_python:

|product| supports reading of Python scripts compatible with Python version
3.7+. |product| supports two additional file extensions for Python scripts (.pyv
and .vpy) to enable users to associate those file extensions with |product| 
without adversely affecting the association of unrelated Python scripts.

For more details about Python scripting in |product|, see the chapter on 
:ref:`scripting` as well as the associated API manual.

Closing Files
=============

.. _closing_files:

When a file is opened in |product|, its contents are loaded into its own
individual list. To close a given file, simply right-click on the associated 
list in the *List Window* and select the *Delete* option. This will close the 
file and remove the contents from the application. However, if an object is 
present in multiple lists, deleting one of those lists will not delete that 
object from the other lists. It is important to note that deleting a list, does
not affect the actual file that was read.

To close all of the currently loaded files, select the *Clear All* option in
the *File* menu. In addition to clearing everything that is loaded, this option
effectively restores the state of the application to what it was when the 
application was started.

Saving Files
============

.. _saving_files:

|product| is capable of saving multiple types of files including molecules, 
grids, surfaces, and state files. The details of the individual formats can be
found in the relevant sections below.

.. note::

    VIDA does not currently support writing to oedu file format

.. _figure_prompt_ids:

.. figure:: /_images/prompt_ids.png
   :scale:  50
   :align:  center
   
   **Prompt dialog**

A file can be saved by choosing the *Save* option in the *File* menu. This will
launch a dialog prompting the user to select which objects to save (see 
:ref:`Figure: Prompt Dialog<figure_prompt_ids>`). There are two sets of buttons 
at the top of this dialog which provide
mechanisms for filtering the available options. The three buttons on the top 
left toggle the display of molecules, surfaces, and grids respectively. The two
buttons on the top right provides filters for showing only the *Marked* and/or
*Visible* objects respectively. Once one or more objects have been selected and 
the **OK** button is pressed, a file dialog will appear allowing the user to 
specify the desired file. The file formats listed in the file dialog filter 
will reflect which file formats are supported based on the objects selected.
Only the OpenEye binary format supports writing multiple object types 
(molecules, grids, and/or surfaces) to the same file.

This process can be expedited by simply right-clicking on the desired 
objects and selecting the *Save* option. This allows the user to bypass the
selection dialog and go directly to the file dialog.

Molecules
---------

.. _saving_molecules:

Multiple molecular file formats are supported for writing and include:

* OpenEye binary format v2 (.oeb)
* MDL, RDF, and SDF
* Tripos Mol2, Mol2H
* Daylight SMILES, canonical SMILES, and isomeric SMILES
* ChemDraw CDX
* MacroModel
* Molecular Formula (MF)
* MOPAC
* FASTA
* PDB
* XYZ

As is often the case with file formats, the meaning and use of certain fields
within a format may change over time which can potentially lead to problems
interpreting those files. |product|, using OpenEye's **OEChem** toolkit, writes all
files according to the standard; however, it does provide a mechanism to allow
the user to override the handling of certain formats (SMILES, SDF/MDL, PDB, 
MOL2, MF, MOPAC, and MacroModel). The ability to change the "flavor" of a 
specific format can be done in the application preferences as seen in 
:ref:`Figure: Molecule flavors<figure_flavors>`.

In addition to changing the flavor of a format, there are a few other advanced
options available when writing molecules including aromaticity model 
specification and conformer splitting. The desired aromaticity model to be 
applied can be specified in the pull down menu next to the *Aromaticity Model*
label. For more specific details on the available aromaticity models, please
see the **OEChem** documentation.

.. note::
  
   Because these advanced options are available 
   through the application preferences, they will be remembered by the application
   and automatically applied in future *Save* operations unless they are 
   subsequently modified or restored.

Grids
-----

.. _saving_grids:

Multiple grid formats are supported for writing and include:

* OpenEye grids
* ASCII grids
* GRASP/DelPhi grids

Surfaces
--------

.. _saving_surfaces:

Multiple surface formats are supported for writing and include:

* OpenEye surfaces
* GRASP surfaces

State Files
-----------

The entire state of a session can be stored in a single file called a *State
File* (.oes). A state file contains all of the molecules, design units, grids, and surfaces 
that were loaded in |product| at the time the state file was created. In
addition, the state file preserves the actual view, layout, and properties of
that session. State files provide an extremely convenient way to save sessions
for later work or to share with collaborators. Furthermore, state files are the
fastest method of reading and writing large data sets.

.. note::

   State files are not backwards compatible with older versions of VIDA

.. _figure_save_state_compress_contours:

.. figure:: /_images/compress_grid_contours.png
   :scale:  75
   :align:  center
   
   **Compress Grid Contours**

|product| supports a "mini" state file option which only writes out 
objects that are currently visible or referenced in the display bookmarks. This
can provide for substantial savings in disk size and load time. This 
mini-state can be further compressed by selecting the "Compress grid contour
information" option in the *General* section of the application preferences
:ref:`Figure: Compress Grid Contours<figure_save_state_compress_contours>`.
Selecting this option zeroes all non-contour related positions in the grid 
which greatly improves its compressibility. This should only be done if there 
is no expectation that the user loading the resulting state file will want to
look at grid contour levels other than those already defined when the file was
generated.

.. _figure_save_state:

.. figure:: /_images/save_state.png
   :scale:  75
   :align:  center
   
   **Saving State**

To save a state file, select the *Save State* option in the *File* menu and
specify the desired state file. The state file type can be selected using 
the file format filter as seen in 
:ref:`Figure: Saving State<figure_save_state>`.

Importing Files
===============

External spreadsheet data can be imported into |product| and associated with
currently loaded objects. Both comma separated files (.csv) and tab delimited
files (.txt) are supported by default. Once a file has been selected, an 
import dialog will appear which allows the user to customize the column
delimiters, column headers, as well as the criteria on which rows are matched
to currently loaded objects. For more details on importing spreadsheet data,
please see the Spreadsheet chapter.

Exporting Files
===============

Multiple special file types can be exported from |product| including data,
images, and scripts. Exact details about these files can be found in the
relevant sections below.

Data
----

Spreadsheet data can be exported in three formats: comma separated files (.csv)
, tab delimited files (.txt), and PDF (.pdf). Data can be exported by selecting the 
"Spreadsheet" option in the *Export* submenu in the top-level *File* menu.
Selecting this option will launch a file dialog which allows the user to 
specify the output file. Once the desired file has been chosen, another dialog
will appear which allows the user to select which spreadsheet and which 
columns in that spreadsheet should be exported. For more specific details on 
exporting spreadsheet data please see the Spreadsheet chapter.

Images
------

**POV-Ray**

The current scene in the 3D display can be exported to a POV-Ray input file
which can be used to generate very high quality and resolution images. To 
export a POV-Ray file, select the *POV-Ray* option in the *Export* submenu
in the *File* menu. The application will then prompt the user to specify a file
to which the scene will be saved.

Python
------

A complete history of the application's operations can be written out as a 
Python script. This script can be exported by selecting the *Script History*
option in the *Export* submenu in the *File* menu.

Drag and Drop
=============

A powerful drag and drop interface is provided for passing molecules, images of
molecules, and molecular data between applications. Multiple mechanisms of 
transferring data via the drag and drop interface are supported.

* Dragging a list of filenames into the List Window will cause those files to 
  be loaded.
* Dragging a list of SMILES into the List Window will cause those SMILES to be
  parsed into new molecules and stored in a new list called "Pasted". These new
  molecules will not be assigned 3D coordinates and therefore will not be 
  visible in the 3D display.
* Dragging a list of IUPAC or common chemical names into the List Window will 
  cause those names to be parsed into new molecules (using OpenEye's **Lexichem**
  toolkit) and stored in a new listed called "Pasted". Please note, this
  functionality requires a separate license for the **Lexichem** toolkit available
  from OpenEye. These new molecules will not be assigned 3D coordinates and 
  therefore will not be visible in the 3D display.
* Dragging molecules from other molecular visualization programs into the List
  Window will cause those molecules to be loaded into a new list called 
  "Pasted". The ability to load molecules from other applications depends on how
  the other applications place molecules on the clipboard. Currently supported
  clipboard formats include SMILES, ChemDraw CDX, ISIS Sketch, MDL SD Files, 
  and OpenEye OEB files. Furthermore, for other molecular visualization 
  programs that support a drag and drop interface, molecules can be dragged 
  from the List Window into those applications.
* Dragging molecules from the List Window into other applications will cause
  molecules, molecular data, or molecular images to be transferred to that 
  application depending on how that application expects to receive data. For
  instance, dragging molecules into a text editor will enter a list of SMILES
  corresponding to the dragged molecules.
* Dragging a 2D depiction from the Spreadsheet will cause that image to be 
  loaded in the associated application if possible.
* Dragging molecules within the List Window can be used to organize files and
  molecules.  See the :ref:`List Management<lists>` section for more details.
* DesignUnits cannot be modified with Drag-and-Drop at this time

Copy and Paste
===============

A copy and paste interface exists for passing
molecules, images of molecules, and molecular data between applications. The
*Copy* option can be found in the *Edit* menu and can also be performed by
pressing *Ctrl+C* on the keyboard. This will copy all of the molecules in the
current scope to the clipboard, unless the active window is the Spreadsheet in
which case it will copy all of the selected Spreadsheet data to the clipboard
instead.

The *Paste* option can be found in the *Edit* menu and can also be performed by
pressing *Ctrl+V* on the keyboard. This will paste any molecules found on the
clipboard into a new list called "Pasted".

 




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


Help
====

Help with |product| can be found under the *Help* menu in the main menubar, which will link
to the documentation on the OpenEye website: `<https://docs.eyesopen.com>`_. The *Help* menu 
provides an *About* option, access to documentation, licensing utilities, access to *Examples*, 
access to the *User Directory*, as well as the ability to file a bug report.

About
-----

The *About* box provides extensive details about the running version of 
|product| as well as the system on which that |product| is running. It also 
provides licensing information and direct access to the license file in use.



.. _install_VIDA:

################################
Installation and Platform Notes
################################

:ref:`Follow the standard instructions for installation, licensing, and removal <app-installation>`.

If a valid license is not found in one of the default locations, the user will 
be prompted to specify the location of the license file. The user may specify 
a local file, a file on a network/shared drive, or a network URL. If the 
specified file contains a valid license, the license file will be copied to a 
local cache so that it does not have to be found each time.

When the license file expires, a new license will automatically be searched for
in the location that was specified for the current license. If a valid license 
is found in that location, it will automatically by copied over and used 
without any user action required. If a valid license file cannot be found, the 
user will again be prompted to locate one. When there are fewer than 30 days
remaining on the current license, the application title bar will change to 
report the number of days remaining.

Once VIDA has started, the user can view the actual license file being used 
(*that is*, the locally cached copy), specify a new license file, or force an update
of the current license from the originally specified location. These options
can be accessed in the ``License`` submenu of the main ``Help`` menu.

Enterprise Installation for Windows
-----------------------------------
It is possible to perform a "silent installation" of VIDA by running the 
installer with the ``/S`` flag.  During a silent installation, no progress 
or other installation windows will be displayed.  If this flag is used, 
the installer
should be run from an administrative account to avoid the appearance of a
"User Account Control" dialog during installation.  No reboot is required
after installation.

By default, the OpenEye file extensions ".oes" (VIDA state files), ".oeb"
(OpenEye binary files), and ".vpy" (VIDA Python scripts) are associated with
the VIDA application. Users can optionally associate Mol files (.mol, .sdf,
.sd), PDB files (.pdb, .ent), Mol2 files (.mol2), and grid and surface files 
(.grd, .agd, .srf, .oesrf) with VIDA, but by default these optional 
associations are not made. 




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


.. _lists:

*********************
List Management
*********************

The organization of molecules into lists and the ability to easily browse 
through these lists is an extremely important and central concept to |product|. 
As such a List Window is provided to aid in the navigation and organization of 
lists. Furthermore, there exist many mechanisms to create, modify, and delete 
lists which will be discussed in more detail later in this chapter.

Introduction
============

The List Window is one of the primary navigation and organization mechanisms in
|product|. It displays all of the currently loaded files and their contents 
(molecules, grids, surfaces, etc.) into hierarchical lists for easy browsing 
and organization.

The List Window can be seen in 
:ref:`Figure: List Window<figure_listwindow>` and contains multiple 
columns for controlling the various states and properties of the associated 
objects. The first column displays the name. The second column (with the green 
sphere icon at the top) is the *Visible* state column . The third column (with 
the padlock icon at the top) is the *Locked* state column. The fourth column 
(with the flag icon at the top) is the *Marked* state column. The fifth column 
contains the unique identifier assigned to that object. The sixth and last column
contains the number of entries that are contained below that entry (e.g. number
of molecules in a list, number of conformers in a molecule, etc).  More details on
the List Window columns are provided in the :ref:`List Columns<list_columns>` section.

.. _figure_listwindow:

.. figure:: /_images/listwindow.png
   :scale:  75
   :align:  center
   
   **List Window**

Browsing
========

Every list in the List Window, as well as many of the other objects, can be 
expanded in the List Window to reveal further detail or the members contained 
within them.  A small box with a "+" sign inside to the left of an object's 
name indicates that that object can be expanded. Molecules, for example, may be
expanded to reveal conformers, molecular structure, or potentially other 
related children objects such as surfaces or grids. A single mouse click on the 
box will expand that object to reveal its contents. Double-clicking on the object
name will turn on in-place renaming of that object.

Views
=====

.. _figure_listwindow_flat:

.. figure:: /_images/listwindow_flat.png
   :scale:  75
   :align:  center
   
   **Flat View**

.. _figure_listwindow_spread:

.. figure:: /_images/listwindow_spread.png
   :scale:  75
   :align:  center
   
   **Spreadsheet View**

The List Window provides three different views onto the loaded data. Which view
is shown is controlled by the three buttons at the bottom of the List Window. 
The first view is a traditional hierarchical view, described above, and seen in 
:ref:`Figure: List Window<figure_listwindow>`. The second view is a flat view 
(see :ref:`Figure: Flat View<figure_listwindow_flat>`) in which the list 
hierarchy has been removed, but all the contents are shown in the same original 
order. The third view is a spreadsheet view (see 
:ref:`Figure: Spreadsheet View<figure_listwindow_spread>`) which shows only 
those objects that appear within the associated spreadsheet (as specified by 
the drop down box next to its button). Furthermore, the order of the objects in 
this view parallels the current sorting order in the application spreadsheet. 

.. _list_columns:

List Columns
============

There are multiple columns available for each object in the list. Some columns 
are simply informative, such as the unique identifier, while others are 
functional as well as informative.

Clicking on an object's name will make that object the *Focused* object. In the 
List Window, the *Focused* object's name is displayed in bolded text and there 
will be a small blue box around the dot in the second column (the *Visible* column).
An example of this can be seen in 
:ref:`Figure: List Window<figure_listwindow>`, where the molecule "1-1 cox2" is 
*Focused*.

The second column is the *Visible* column.  The *Visible* column has 
a green dot icon in its column header. This column displays and controls the 
*Visible* property for objects. If an object is *Visible* there will 
be a green dot identical to the one in the column header present in that 
object's *Visible* column. If that object is also the *Focused* 
object, there will be a small blue box around the dot in that column as well.
Clicking on the icon in the header of this column will make all lists 
visible.

If a given object has children, the visibility of its children can also be
controlled in this column. Child objects have an additional layer of control
regarding visibility in that they can be hidden, visible, or can mimic its
parent's visibility. If an object is set to mimic's its parents visibility, 
an upright triangle is shown instead of the standard green dot (as can be seen
in :ref:`Figure: Mimic Visibility<figure_list_window_child>`. Clicking in this 
column cycles through these three states in the 
following order: hidden, mimic, visible. Please note that molecular structure 
(atoms, residues, chains, etc) are not considered children objects and as such 
always mimic the parent molecule's visibility if they are marked visible with 
a green dot. 

.. _figure_list_window_child:

.. figure:: /_images/listwindow_child.png
   :scale:  75
   :align:  center
   
   **Mimic Visibility**

The third column is the *Locked* column.  The *Locked* column has a 
small, grey padlock icon in its header. If an object is *Locked* there 
will be a grey padlock identical to the one in the column header present in 
that object's *Locked* column.  Clicking on the lock icon in this column's
header will lock all objects.

The fourth column is the *Marked* column. The *Marked* column has a
red flag icon in its header. If an object is *Marked* there will be
a red flag identical to the one in the column header present in that
object's *Marked* column.  Clicking on the flag icon in this column's header
will mark all objects.

The fifth column is the *ID* column.  An object's ID is 
simply a unique identifier that can be useful to identify specific objects 
when running various commands. Each top level object has its own unique 
ID, but child objects like conformers and atoms are all a part of their 
parent molecule's ID.  

The sixth and final column is the *Number* column. This column contains the
number of entries available beneath the current object. For lists, this will
display the number of molecules in that list. For molecules, this will display
the number of conformers (if there is more than 1).

Columns can be shown or hidden as desired by right-clicking in the header of 
the List Window. These changes will be remembered in the :ref:`Preferences<preferences>` 
and thus persist between sessions.

.. _figure_list_window2:

.. figure:: /_images/listwindow2.png
   :scale:  75
   :align:  center
   
   **Multiple Objects**

The *Visible*, *Locked*, and *Marked* properties can be toggled 
by clicking on their associated columns in the List Window. If multiple objects
are highlighted simultaneously and the click occurs in a column associated with
the highlighted region, that change will apply to all of the highlighted 
objects. In :ref:`Figure: Multiple Objects<figure_list_window2>`, the highlighted 
objects have been made *Visible* by clicking in that column. The *Focused* 
object has changed as a result as well.

*Visible*, *Locked*, and *Marked* properties of the *Focused* object can be toggled using the V, L, and M keys, respectively.

List Manipulation
=================

The List Window operates on the basic concept that every potentially viewable 
object is placed inside a list. As a result, the root items in the List 
Window are always lists. These lists can be combined, subsetted, and 
manipulated into new lists. The properties of all the objects in a list can be 
set together by clicking in the columns of their containing list. Finally, 
objects can easily be removed from and inserted into lists.

Creating Lists
--------------

New lists can be created in several ways. The simplest way is to select some
number of molecules from a list and drag them to the top of the List Window.

The "New List" submenu in the *File* menu provides a number of list creation
methods, including using the AND of two or more lists (intersection), the 
OR of two or more lists (union), the XOR of two lists (union - intersection), 
or from the currently *Marked* set of objects.

The AND list contains only those objects which are in all of the source lists. 
The OR list contains all of the objects contained in its individual source 
lists. The XOR list contains the objects which are in only one of the source 
lists, but not both. Finally, the *Marked* list creates a new list which 
contains all of the currently *Marked* objects.

Another way to create a new list is by right-clicking on an individual list 
and selecting the "Subset" submenu from the popup menu. This menu contains 
four entries -- "By Marked", "By Query", "By Not Marked" and "By Not 
Query". The "By Marked" option creates a new list containing all of the 
*Marked* objects from within the list. The "By Not Marked" option creates 
a list with all of the objects from the list which are not *Marked*. "By 
Query" generates a dialog which prompts for a substructure query that if the
objects match, those objects will be placed in the new list. The "By Not 
Query" behaves the same way, except that it puts the objects that do match the
query into the new list.

The last way to create a new list is from the "Find" menu entry in the 
*Edit* menu. This mechanism searches all of the currently loaded molecules 
by either Amino Acid Sequence, SMARTS, a regular expression against the 
molecule title, or by a Query molecule (as a substructure search).  After 
clicking the "Search" button, the matching results will be displayed on the 
right-hand side of the dialog. The entire set or just specific individual 
results can be selected within the dialog to populate the new list. 

Reorganizing Lists
------------------

The List Window supports "drag and drop" of lists and the items they contain.
This allows lists to be reordered, molecules to be reordered within a list,
and molecules to be dragged from one list to another.  New lists can be 
created by dragging molecules out of a list to the List Window's top level.

.. note::

   OEDesignUnit entries cannot be edited at this time

Deleting from Lists
-------------------

As previously mentioned, objects can also be removed from lists. There are two 
ways to remove an object from a list. The first mechanism is to delete
the object (by selecting the "Delete" option from the right-click menu). 
Deleting an object will remove it from ALL of the lists to which it 
belongs. Choosing the "Remove from List" option from the same right-click 
menu will remove the object from the specified list only, leaving it perfectly 
intact in any other lists that it might belong to. When the last object is 
removed from a list, the list itself will be removed.



.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:

.. _menus:

*********************
Menus
*********************

This chapter contains a listing of the menu options available in |product|. 
Where possible, each section also contains a listing of the
Python code that is run when that option is selected.  All Python menu commands
are wrapped in a standard exception handling block:

.. oe:source:: menus.py
   :frag:     CODE_WRAPPER

File
====

Open
----

.. oe:source:: menus.py
   :frag:     FILE_OPEN

Open State
----------

.. oe:source:: menus.py
   :frag:     FILE_OPEN_STATE
   
Open Special
------------

From PDB...
^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_OPEN_SPECIAL_PDB

Script...
^^^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_OPEN_SPECIAL_SCRIPT

MTZ...
^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_OPEN_SPECIAL_MTZ

Clear
-----

Marked
^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_CLEAR_MARKED
   
Not Marked
^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_CLEAR_NOT_MARKED

Visible
^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_CLEAR_VISIBLE
   
Not Visible
^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_CLEAR_NOT_VISIBLE

Clear All
---------

.. oe:source:: menus.py
   :frag:     FILE_CLEAR
   
Save
----

.. oe:source:: menus.py
   :frag:     FILE_SAVE
   
Save Marked
-----------

.. oe:source:: menus.py
   :frag:     FILE_SAVE_MARKED
   
Save State
----------

.. oe:source:: menus.py
   :frag:     FILE_SAVE_STATE
   
New List
--------

From AND
^^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_NEW_LIST_FROM_AND
   
From OR
^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_NEW_LIST_FROM_OR
   
From XOR
^^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_NEW_LIST_FROM_XOR

From Marked
^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_NEW_LIST_FROM_MARKED

New Molecule
------------

From Name
^^^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_NEW_MOLECULE_FROM_NAME

From Merge
^^^^^^^^^^

All three options under this menu (*Scoped*, *Marked*, and
*Visible*) execute the following code. 

.. oe:source:: menus.py
   :frag:     FILE_NEW_MOLECULE_FROM_MERGE
   
The SCOPE parameter is assigned a value according to which option was selected 
(SelectedScope, MarkedScope, and VisibleScope respectively).

From Split
^^^^^^^^^^

**Components**

.. oe:source:: menus.py
   :frag:     FILE_NEW_MOLECULE_FROM_SPLIT_COMPONENTS
   
**Selected**

.. oe:source:: menus.py
   :frag:     FILE_NEW_MOLECULE_FROM_SELECTED

**Marked**

.. oe:source:: menus.py
   :frag:     FILE_NEW_MOLECULE_FROM_MARKED

Import
------

Spreadsheet
^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_IMPORT_SPREADSHEET

Export
------

Script History
^^^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_EXPORT_SCRIPT_HISTORY
   
Screenshot
^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_EXPORT_SCREENSHOT

Spreadsheet
^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_EXPORT_SPREADSHEET
   
POV-Ray
^^^^^^^

.. oe:source:: menus.py
   :frag:     FILE_EXPORT_POVRAY

Recents
-------

All of the options in this menu call the following command:

.. oe:source:: menus.py
   :frag:     FILE_RECENTS

The FILENAME parameter is assigned to the filename specified in the option 
that was selected under this menu.

Recent Directories
------------------

All of the options in this menu call the following command:

.. oe:source:: menus.py
   :frag:     FILE_RECENT_DIRS

The FILENAME parameter is assigned to the filename specified in the option 
that was selected under this menu.

Exit
----

.. oe:source:: menus.py
   :frag:     FILE_EXIT

Edit
====

Undo
----

.. oe:source:: menus.py
   :frag:     EDIT_UNDO

Undo History
------------

Redo
----

.. oe:source:: menus.py
   :frag:     EDIT_REDO
   
Redo History
------------

Copy
----

.. oe:source:: menus.py
   :frag:     EDIT_COPY

Copy Image
----------

.. oe:source:: menus.py
   :frag:     EDIT_COPY_IMAGE

Paste
-----

.. oe:source:: menus.py
   :frag:     EDIT_PASTE

Select
------

All Visible
^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     EDIT_SELECT_ALL_VISIBLE

Expression
^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     EDIT_SELECT_EXPRESSION

Query
^^^^^

.. oe:source:: menus.py
   :frag:     EDIT_SELECT_QUERY

Invert
^^^^^^

.. oe:source:: menus.py
   :frag:     EDIT_SELECT_INVERT

None
^^^^

.. oe:source:: menus.py
   :frag:     EDIT_SELECT_NONE

Mark
----

All Visible
^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     EDIT_MARK_ALL_VISIBLE
   
Query
^^^^^

.. oe:source:: menus.py
   :frag:     EDIT_MARK_QUERY

None
^^^^

.. oe:source:: menus.py
   :frag:     EDIT_MARK_NONE

Hide
----

All
^^^

.. oe:source:: menus.py
   :frag:     EDIT_HIDE_ALL

Selected
^^^^^^^^

.. oe:source:: menus.py
   :frag:     EDIT_HIDE_SELECTED

Marked
^^^^^^

.. oe:source:: menus.py
   :frag:     EDIT_HIDE_MARKED

Not Selected
^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     EDIT_HIDE_NOT_SELECTED

Not Marked
^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     EDIT_HIDE_NOT_MARKED

None
^^^^

.. oe:source:: menus.py
   :frag:     EDIT_HIDE_NONE

Find
----

By LINGO Similarity
^^^^^^^^^^^^^^^^^^^

Creates a new list of molecules, based on the LINGO similarity measure to a
query molecule.  LINGO is a fast text-based similarity measure that uses the
canonical, isomeric SMILES strings of molecules for comparisons.

.. seealso::

   * [Vidal-2005]_

.. oe:source:: menus.py
   :frag:     EDIT_FIND_BY_LINGO

By SMARTS
^^^^^^^^^

.. oe:source:: menus.py
   :frag:     EDIT_FIND_BY_SMARTS

By Query Molecule
^^^^^^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     EDIT_FIND_BY_QUERY

By Title
^^^^^^^^

.. oe:source:: menus.py
   :frag:     EDIT_FIND_BY_TITLE

Find on Disk
------------

.. oe:source:: menus.py
   :frag:     EDIT_FIND_ON_DISK

Clear Scripting Log
-------------------

.. oe:source:: menus.py
   :frag:     EDIT_CLEAR_SCRIPTING_LOG
   
Extensions
----------

.. oe:source:: menus.py
   :frag:     EDIT_EXTENSIONS

Preferences
-----------

.. oe:source:: menus.py
   :frag:     EDIT_PREFERENCES
   
View
====

Fullscreen
----------

.. oe:source:: menus.py
   :frag:     VIEW_FULLSCREEN

Data
====

Sort Spreadsheet
----------------

.. oe:source:: menus.py
   :frag:     DATA_SORT_SPREADSHEET

Filter Spreadsheet
------------------

.. oe:source:: menus.py
   :frag:     DATA_FILTER_SPREADSHEET

Create Column
-------------

.. oe:source:: menus.py
   :frag:     DATA_CREATE_COLUMN

Create Empty Column
-------------------

.. oe:source:: menus.py
   :frag:     DATA_CREATE_EMPTY_COLUMN

Format Columns
--------------

.. oe:source:: menus.py
   :frag:     DATA_FORMAT_COLUMNS

Organize Columns
----------------

.. oe:source:: menus.py
   :frag:     DATA_ORGANIZE_COLUMNS

Advanced Depiction Options
--------------------------

.. oe:source:: menus.py
   :frag:     DATA_ADV_DEPICTION_OPTS

Show Statistics
---------------

.. oe:source:: menus.py
   :frag:     DATA_SHOW_STATISTICS

Style
=====

Color
-----

Palette
^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_COLOR_PALETTE
   
Unique
^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_COLOR_UNIQUE

Restore
^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_COLOR_RESTORE

Molecules
^^^^^^^^^

All but two of the options (*Carbon* and *Reference*) in this menu 
call the following function.

.. oe:source:: menus.py
   :frag:     STYLE_COLOR_MOLECULES
   
The SCHEME parameter is assigned based on which menu option was selected 
according to the table below.

.. table:: Color schemes
  
  =====================  =====================  
  *Amino*                'amino'
  *Alternate Locations*  'alt location'          
  *BFactor*              'bfactor'        
  *Chain*                'chain'          
  *CPK*                  'cpk'            
  *CPKNew*               'cpknew'         
  *Element*              'element'        
  *Formal Charge*        'formal charge'  
  *Group*                'group'          
  *Partial Charge*       'partial charge' 
  *Residue*              'residue'        
  *Shapely*              'shapely'        
  =====================  =====================  

The *Carbon* menu option calls the following function.

.. oe:source:: menus.py
   :frag:     STYLE_COLOR_MOLECULES_CARBON
   
The *Reference* menu option calls the following function.

.. oe:source:: menus.py
   :frag:     STYLE_COLOR_MOLECULES_REFERENCE
   
Surfaces
^^^^^^^^

All of the options in this menu call the following function.

.. oe:source:: menus.py
   :frag:     STYLE_COLOR_SURFACES
   
Both the SCHEME and PARAMS parameters are assigned based on which option
was selected according to the table below.

.. table:: Color schemes and parameters

  ================================= ================== ==========================
  *Atom Color*                      'atom'             ''
  *Curvature*                       'curvature'        ''
  *Distance*                        'distance'         ''
  *Electrostatic*                   'electrostatics'   ''
  *Hydrogen Bond Potential*         'hydrogen bonds'   ''
  *Hydrophobicity*                  'hydrophobicity'   ''
  *Surface Potential*               'potential'        '' 
  ================================= ================== ==========================

The *Grid* menu options calls the following function.

.. oe:source:: menus.py
   :frag:     STYLE_COLOR_SURFACES_GRID

Transparency
^^^^^^^^^^^^

All of the options in this menu call the following function.

.. oe:source:: menus.py
   :frag:     STYLE_TRANSPARENCY
   
The N parameter is assigned to a value between 0 and 255 based on which option
was selected. A value of 255 corresponds to 0 percent transparency and a value of 
0 corresponds with 100 percent transparency. The specific values used in the menu 
are: 255, 230, 204, 179, 153, 128, 102, 77, 61, 26, 0.

Selection
---------

Crop Selected
^^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_SELECTION_CROP_SELECTED

Crop Unselected
^^^^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_SELECTION_CROP_UNSELECTED

Display
-------

Molecules
^^^^^^^^^

All of the options in this menu call the following function.

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_MOLECULES

The STYLE parameter is assigned based on which option was selected according
to the table below.

.. table:: Molecule Styles

  =================  =================
  *Wireframe*        'wireframe'      
  *Stick*            'stick'          
  *Ball and Stick*   'ball and stick' 
  *CPK*              'cpk'            
  *Stars*            'stars'          
  *Hidden*           'hidden'         
  =================  =================

**Hydrogens**

All of the options in this menu call the following function.

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_HYDROGENS

The STYLE parameter is assigned based on which option was selected according 
to the table below.

.. table:: Hydrogen Styles

  ============= =============
  *All*         2 
  *Polar*       1 
  *None*        0 
  ============= =============

**Non-Bonded Atoms**

Both of the options in this menu call the following function with the HIDE 
parameter assigned based on which option was selected (*Show* assigns
HIDE to False and *Hide* assigns HIDE to True).

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_NONBONDED

**C-Alpha Trace**

Both of the options in this menu call the following function with the DRAW 
parameter assigned based on which option was selected (*Show* assigns
DRAW to True and *Hide* assigns DRAW to False).

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_CALPHA

**Ribbons**

Both of the options in this menu call the following function with the DRAW 
parameter assigned based on which option was selected (*Show*} assigns
DRAW to True and *Hide*} assigns DRAW to False).

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_RIBBONS

**Atom Labels**

The *Atom Labels* submenu provides a variety of labeling of options. The
"Custom..." option launches a dialog which allows the user to build up more
complex and customized labels. This dialog is launched using the following
Python command:

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_ATOM_LABELS_VIEWER

All of the other options in the submenu all call the following Python command
but with different string arguments:

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_ATOM_LABELS

The arguments used can be found in the table below:

.. table:: Atom Label Arguments

  ======================= =======================
  Name                    '%n' 
  Index                   '%i' 
  Element                 '%e' 
  Isotope                 '%iso' 
  Type                    '%t' 
  Integer Type            '%it' 
  Implicit H Count        '%h' 
  Map Idx                 '%m' 
  Partial Charge          '%p' 
  Formal Charge           '%f' 
  Atom Radius             '%rad'
  Residue Info            '%r' 
  Residue Info (CA)       '%car' 
  B-Factor                '%bf'
  C-Alpha B-Factor        '%cab' 
  Degree                  '%d' 
  Is Chiral               '%c' 
  Chirality               '%chi' 
  Hybridization           '%hy' 
  Has Stereo Specified    '%sts' 
  Is In Ring              '%rng' 
  OEChem Idx              '%oei' 
  Symmetry Class          '%sy'
  Atom Comment            '%cm'
  Atom Occupancy          '%occ'
  MMFF Atom Type          '%mmff'
  Generic Data            '%gd(<GENERIC_DATA_TAG>)'
  None                    '' 
  ======================= =======================

**Bond Labels**

The *Bond Labels* submenu provides a variety of labeling of options. The
"Custom..." option launches a dialog which allows the user to build up more
complex and customized labels. This dialog is launched using the following
Python command:

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_BOND_LABELS_VIEWER

All of the other options in the submenu all call the following Python command
but with different string arguments:

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_BOND_LABELS

The arguments used can be found in the table below:

.. table:: Bond Label Arguments

  ======================= =======================
  Name                    '%n' 
  Index                   '%i' 
  Type                    '%t' 
  Integer Type            '%it' 
  Order                   '%o' 
  Length                  '%l' 
  Is Chiral               '%c' 
  Chirality               '%chi' 
  Has Stereo Specified    '%sts' 
  OEChem Idx              '%oei' 
  Generic Data            '%gd(<GENERIC_DATA_TAG>)'
  None                    '' 
  ======================= =======================

**Electrostatic Potential**

Both of the options in this menu call the following function with the DRAW 
parameter assigned based on which option was selected (*Show* assigns
DRAW to True and *Hide* assigns DRAW to False).

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_ES_GRID

**Molecular Surface**

Both of the options in this menu call the following function with the DRAW 
parameter assigned based on which option was selected (*Show* assigns
DRAW to True and *Hide* assigns DRAW to False).

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_MOLECULAR_SURFACE

**Accessible Surface**

Both of the options in this menu call the following function with the DRAW 
parameter assigned based on which option was selected (*Show* assigns
DRAW to True and *Hide* assigns DRAW to False).

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_ACCESSIBLE_SURFACE

**Hydrogen Bonds**

*Add Targets*

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_HYDROGEN_BONDS_ADD

*Remove Targets*

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_HYDROGEN_BONDS_REMOVE

*External Hydrogen Bonds*

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_HYDROGEN_BONDS_EXTERNAL

*Internal Hydrogen Bonds*

.. oe:source:: menus.py
   :frag:     STYLE_DISPLAY_HYDROGEN_BONDS_INTERNAL

Grids
^^^^^

*Solid*

.. oe:source:: menus.py
   :frag:     STYLE_GRIDS_SOLID

*Mesh*

.. oe:source:: menus.py
   :frag:     STYLE_GRIDS_MESH

*Cloud*

.. oe:source:: menus.py
   :frag:     STYLE_GRIDS_CLOUD

*Grid Corners*

.. oe:source:: menus.py
   :frag:     STYLE_GRID_CORNERS

*Electrostatic*

.. oe:source:: menus.py
   :frag:     STYLE_GRID_ELECTROSTATIC

*ET*

.. oe:source:: menus.py
   :frag:     STYLE_GRID_ET

*FRED*

.. oe:source:: menus.py
   :frag:     STYLE_GRID_FRED

*Generic*

.. oe:source:: menus.py
   :frag:     STYLE_GRID_GENERIC
   
*Difference Map*

.. oe:source:: menus.py
   :frag:     STYLE_GRID_DIFFERENCE_MAP

*Regular Map*

.. oe:source:: menus.py
   :frag:     STYLE_GRID_REGULAR_MAP

*Add Contour*

.. oe:source:: menus.py
   :frag:     STYLE_GRID_ADD_CONTOUR

*Delete Contour*

.. oe:source:: menus.py
   :frag:     STYLE_GRID_DELETE_CONTOUR

Surfaces
^^^^^^^^

All of the options in this menu except one (*Restore*) call the following 
function.

.. oe:source:: menus.py
   :frag:     STYLE_SURFACES

The STYLE parameter is assigned based on which option was selected according 
to the table below.

.. table:: Surface Style Arguments

  ==========  ==========
  *Solid*     'solid'  
  *Mesh*      'mesh'   
  *Points*    'points' 
  ==========  ==========

The *Restore* option calls the following function.

.. oe:source:: menus.py
   :frag:     STYLE_SURFACE_RESTORE

Graphics
--------

Depth Cue
^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_GRAPHICS_DEPTHCUE

Slabbing
^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_GRAPHICS_SLABBING

Mirror Slabs
^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_GRAPHICS_MIRROR_SLABS

Slab Level
^^^^^^^^^^

All of the options in this menu call the following function.

.. oe:source:: menus.py
   :frag:     STYLE_GRAPHICS_SLAB_LEVEL

The N parameter is assigned to a value between 10 and 80 corresponding to the 
desired percent of the scene to be contained within the slabbing planes.

Render Quality
^^^^^^^^^^^^^^

All of the options in the menu call the following function.

.. oe:source:: menus.py
   :frag:     STYLE_GRAPHICS_RENDER_QUALITY

The LOD parameter is assigned based on which option was selected according to
the table below.

.. table:: Level of Detail Parameters

  ==============  ==========
  *Fastest*       1 
  *Fast*          2 
  *Good*          3 
  *Better*        4 
  *Best*          5 
  *Presentation*  6
  ==============  ==========

Note: *Presentation* quality is optimized for creating output images with a white 
background.

Stereo
^^^^^^

*Off*

.. oe:source:: menus.py
   :frag:     STYLE_GRAPHICS_STEREO_OFF

*Splitscreen*

.. oe:source:: menus.py
   :frag:     STYLE_GRAPHICS_STEREO_SPLITSCREEN

*Stencil*

.. oe:source:: menus.py
   :frag:     STYLE_GRAPHICS_STEREO_STENCIL

*Angle*

.. oe:source:: menus.py
   :frag:     STYLE_GRAPHICS_STEREO_ANGLE

*Separation*

.. oe:source:: menus.py
   :frag:     STYLE_GRAPHICS_STEREO_SEPARATION

*Cross-Eyed*

.. oe:source:: menus.py
   :frag:     STYLE_GRAPHICS_STEREO_CROSS_EYED

Symmetry
--------

Edit Cell
^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_SYMMETRY_EDIT_CELL
   
Show Unit Cell
^^^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_SYMMETRY_SHOW_UNIT_CELL

Show Symmetry
^^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_SYMMETRY_SHOW

Realize Symmetry In Cell
^^^^^^^^^^^^^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_SYMMETRY_REALIZE_IN_CELL

Realize Symmetry
^^^^^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_SYMMETRY_REALIZE

Symmetry Radius
^^^^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_SYMMETRY_RADIUS

Symmetry Operators
^^^^^^^^^^^^^^^^^^

No Symmetry Color
^^^^^^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_SYMMETRY_NO_COLOR

Single Symmetry Color
^^^^^^^^^^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_SYMMETRY_SINGLE_COLOR

Color By Operator
^^^^^^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_SYMMETRY_COLOR_HELPER

Unique Color
^^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     STYLE_SYMMETRY_UNIQUE_COLOR

Bookmarks
=========

Add
---

.. oe:source:: menus.py
   :frag:     BOOKMARKS_ADD

Organize
--------

.. oe:source:: menus.py
   :frag:     BOOKMARKS_ORGANIZE

Animated
--------

.. oe:source:: menus.py
   :frag:     BOOKMARKS_ANIMATED

Tools
=====

FRED View
---------

.. oe:source:: menus.py
   :frag:     TOOLS_FRED_VIEW

EON View
--------

.. oe:source:: menus.py
   :frag:     TOOLS_EON_VIEW

ROCS View
---------

.. oe:source:: menus.py
   :frag:     TOOLS_ROCS_VIEW

Select
======

The Select menu provides a number of ways to select groups of atoms for use
in various tasks, like coloring atoms, creating surfaces, etc.  Most
selection operations involve only molecules which are visible in the 3D Window.
The Select menu also provides the ability to name sets of atoms and store them
for later retrieval.  These sets can be combined with the current selection 
through logical operations, allowing a high degree of flexibility in creating
selection sets.

Clear
-----

Clears all selected atoms and bonds.

All
---

Selects all visible atoms and bonds.

Invert
------

Inverts the current selection with respect to visible atoms.

Protein
-------

Operations in this menu are protein-centric.

Backbone
^^^^^^^^

Selects backbone atoms only.

Sidechains
^^^^^^^^^^

Selects side chain atoms.

C-Alphas
^^^^^^^^

Selects alpha carbon atoms in a protein.

Residue #...
^^^^^^^^^^^^

Allows selection of atoms by residue number.  A dialog will prompt for
residue numbers and chain ID's to include in the selection.

Residue Type...
^^^^^^^^^^^^^^^

Selects standard amino and nucleic acid residues by type.  A dialog will
prompt for residue names to be included in the selection.

Complete Residues
^^^^^^^^^^^^^^^^^

Selects all atoms in any residue that has at least one atom selected.

Zero Occupancy
^^^^^^^^^^^^^^

Selects all atoms with an occupancy value of zero.

Partial Occupancy
^^^^^^^^^^^^^^^^^

Selects all atoms with an occupancy value less than 1.0.

Alt Locations
^^^^^^^^^^^^^

Selects all residues with alternate location specifiers.

Waters
^^^^^^

Selects all water molecules.

Atom Numbers...
---------------

Selects atoms by their OEChem index value.  A dialog will prompt for the atom
numbers to include in the selection.

By Distance...
--------------

Selects residues within a specified distance of the currently selected atoms.
A dialog will appear to allow the distance to be specified with a slider.  A
checkbox in this dialog provides an option to exclude the originally selected
atoms from the final selection.

Heteroatoms
-----------

Selects all atoms that are not carbon or hydrogen.

Charged
-------

Selects all atoms with a non-zero formal charge.

SMARTS Pattern...
-----------------

Selects all atoms matching a SMARTS query pattern. A dialog will prompt for the
SMARTS pattern to use.

Expression...
-------------

Selects atoms using an expression from |product's| selection language.  A
dialog will prompt for the expression to use.

Store
-----

These options allow the storage of the current selection into a new or existing
atom set.

New Set...
^^^^^^^^^^

Creates a new atom set after prompting for a set name.

Into <Set_Name>
^^^^^^^^^^^^^^^

Replaces the contents of the named set *Set_Name* with the current selection.

Recall
------

From <Set_Name>
^^^^^^^^^^^^^^^

Selects the atoms in the named set *Set_Name*.

Combine
-------

Combines the current selection with named sets.

Include
^^^^^^^

Adds the atoms from the named set to the current selection (a logical OR
operation).

Exclude
^^^^^^^

Removes atoms from the named set from the current selection (logical NOT
operation).

Intersect
^^^^^^^^^

Selects the atoms that are in both the named set and the current selection
(logical AND operation).

Delete Set
----------

Deletes the named set.  This does not delete any atoms.

Hide Selected
-------------

Turns off the visibility of all selected atoms.

Hide Unselected
---------------

Turns off the visibility of all unselected atoms in visible molecules.

Window
======

Main Window
-----------

2D Viewer
^^^^^^^^^

.. oe:source:: menus.py
   :frag:     WINDOW_MAIN_WINDOW_2D

3D Viewer
^^^^^^^^^

.. oe:source:: menus.py
   :frag:     WINDOW_MAIN_WINDOW_3D

Spreadsheet
^^^^^^^^^^^

.. oe:source:: menus.py
   :frag:     WINDOW_MAIN_WINDOW_SPREADSHEET

2D Preview
----------

.. oe:source:: menus.py
   :frag:     WINDOW_2D_PREVIEW

2D Viewer
---------

.. oe:source:: menus.py
   :frag:     WINDOW_2D_VIEWER

3D Viewer
---------

.. oe:source:: menus.py
   :frag:     WINDOW_3D_VIEWER

List Window
-----------

.. oe:source:: menus.py
   :frag:     WINDOW_LIST_WINDOW

Process Manager
---------------

.. oe:source:: menus.py
   :frag:     WINDOW_PROCESS_MANAGER

Scripting Window
----------------

.. oe:source:: menus.py
   :frag:     WINDOW_SCRIPTING_WINDOW

Spreadsheet
-----------

.. oe:source:: menus.py
   :frag:     WINDOW_SPREADSHEET

Style Control
-------------

.. oe:source:: menus.py
   :frag:     WINDOW_STYLE_CONTROL

Help
====

About
-----

.. oe:source:: menus.py
   :frag:     HELP_ABOUT

Documentation
-------------

All of the items in this menu open a specific document. The script
to open the document can be found below:

.. oe:source:: menus.py
   :frag:     HELP_DOCUMENTATION
   
The actual document path that is used is:

* `User Manual (HTML) <https://docs.eyesopen.com/applications/vida/index.html`>_.

License
-------

Open
^^^^

.. oe:source:: menus.py
   :frag:     HELP_LICENSE_OPEN

Set
^^^

.. oe:source:: menus.py
   :frag:     HELP_LICENSE_SET

Update
^^^^^^

.. oe:source:: menus.py
   :frag:     HELP_LICENSE_UPDATE

Open Examples Directory
-----------------------

.. oe:source:: menus.py
   :frag:     HELP_OPEN_EXAMPLES_DIR

Open User Directory
-------------------

.. oe:source:: menus.py
   :frag:     HELP_OPEN_USER_DIR
   
File Bug Report
---------------

.. oe:source:: menus.py
   :frag:     HELP_FILE_BUG




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


*********************
Preferences
*********************

.. _preferences:

Every user has his or her own individual preferences with regards to how 
molecules, grids, and surfaces should look and how applications should behave. 
For this reason, a Preferences dialog is available which allows customization of 
the application to the user's preference. An snapshot of the Preferences dialog can 
be seen in 
:ref:`Figure: Preferences<figure_preferences>`.

.. _figure_preferences:

.. figure:: /_images/preferences.png
   :scale:  75
   :align:  center
   
   **Preferences**

On the left-hand side of the dialog is column containing preference categories. 
These categories include: *General*, *Molecules*, *Grids*, 
*Surfaces*, *3D Display*, and *Custom Views*. Clicking on any of 
these categories will update the right-hand side of the widget to display the 
options corresponding to the selected category.

At the bottom of the dialog, the *Restore* button will restore the current 
preferences to the default ones.  The *Apply* button will apply and save the
current preferences.

Preferences are stored in a binary file (``preferences.oeb``) in the
:ref:`User Directory <user_dir>`. While the preference file shares the same file extension as
the OpenEye's  binary database file, it cannot be read into |product| using 
the "Open" menu item in the *File* menu. The preferences file is loaded 
automatically when the applications starts and is saved back to disk when the 
application exits. Deleting this file is equivalent to clicking on the *Restore* 
button in the dialog box.

There is also a file in this same directory which called |product|.ini which 
contains machine specific settings like the list of recent files, preferred 
layouts, and hardware stereo options. Deleting this file will restore these
settings to the defaults as well.

This directory can be opened from within |product| by selecting the "Open User
Directory" menu item in the *Help* menu.




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


.. _processes:

*********************
Processes
*********************

The Process Manager allows the user to start, monitor, terminate, and load 
results from processes external to |product|. As part of this functionality, 
it is possible to write out currently loaded molecules (or grids) to files 
which can be used as input to the external processes. Furthermore, it is 
possible to create "pipes" which chain together the input and output of 
individual processes into a larger process.

.. _figure_process:

.. figure:: /_images/process.png
   :scale:  75
   :align:  center
   
   *Process Manager*

The Process Manager contains two tabbed windows called "Processes" and 
"Status" respectively as can be seen in Figures X.Y and X.Y. The 
"Processes" tab contains the list of available 
processes and the functionality to create and edit them. The "Status" tab 
displays all of the currently active and recently completed processes and
information about their state. It also displays the commandline output 
generated by each of the processes.

.. _figure_process_output:

.. figure:: /_images/process_output.png
   :scale:  75
   :align:  center
   
   *Output generated by a completed process*

Beneath the list of processes in the "Processes" tab is a collection of four
buttons. The button on the left with the play icon starts the currently 
selected process. The next button with the plus icon clears the editor on the
right hand side to allow for creation of a new process. The next button with
the link icon changes the editor on the right hand side to allow for creation
of a new pipe (see Figure X.Y). The last button with the 
delete icon deletes the current selected set of processes from the list of 
available processes.

Processes
=========

When creating a new process or editing a current one, there are a number of 
available options. At the top of the editor there is a field for the 
process name (which will be displayed in the list of available processes seen
on the left as described above) as well as a field for the actual location of 
the application to be run. The "Browse" button to the right of this field can 
be used to find the location of the desired application.

Beneath this is a large text entry box which allows for specification of any 
desired command line arguments to the application. It is not necessary to 
enter the application name here. 

For most applications, at least one filename will have to be specified as a
command line argument. This can be done multiple ways. If the file to be 
specified is always going to be located in the same location, the filename
can be entered directly into the text entry box as a command line argument. If
the location of the file is not likely to be constant, a prompt can be 
specified as opposed to an actual filename. To add a prompt, click on the "Add
File Prompt" button to the right of text entry box. If the
desired file will need to be created each time, it is possible to create the 
desired file at start-time by writing out selected molecules (or grids) directly 
from |product|. To use this feature, click on the "Add Input" button to the 
right of the text entry box. At start-time, the user will be prompted to select 
the desired molecules (or grids), which will then be saved to a file which will 
be passed as a command line argument to the process. 

In addition to being able to specify specific input files, it is possible to
specify an output file which can potentially be read back into |product| when
the process is completed. As discussed above, it is possible to a specify 
specific filename in the command line or to use a prompt, but if it desired to
load the resulting file, the "Add Output" button should be clicked to specify
the file. 

Besides being able to specify filenames, it is often desirable to be able to
specify other variable arguments at start-time. To do this, click on the "Add 
Text Prompt" button which will add a prompt argument to the command line 
arguments. At start-time the user will be asked to specify the desired text to 
be passed to the process. 

Lastly, at the bottom of the Process Editor is a "Python Handler" field which 
allows for specification of a Python function to be run when the process is 
completed. This allows for handling of output not normally handled by |product| or 
for  output which is not specified on the command line.

Adding Input
------------

The Input Editor allows the user to specify a mechanism by which an input file
is provided to the process to be run. At the top of the editor are two mutually
exclusive options, the first is the "Temporary" check box which indicates that
the file to be used will be a temporary file which will be removed after the 
process has completed. The other option is a field which allows specification 
of a specific filename to be used. In both cases, the user has a choice as to 
how this file will be populated: saving molecules, saving grids, or running a
specified Python function which will handle the population of the file. If 
molecules or grids are chosen, a file format to save these in must be specified 
in the pull-down box next to the selected option. 

If a Python function is specified to populate the input file, the desired 
filename can be obtained by using the keyword "@FILE@" in the function 
specification. This keyword will be substituted with the real filename at
start-time before the Python function is called.

Finally, there is a checkbox at the bottom of the dialog to specify whether or 
not this is a default input. The default input entry is used when constructing 
pipes.

.. _figure_process_edit_input:

.. figure:: /_images/process_edit_input.png
   :scale:  75
   :align:  center
   
   *Process Input Editor*

Adding Output
-------------

The Output Editor allows the user to specify a mechanism by which an output 
file of the process to be run is handled by |product|. At the top of the dialog
are two mutually exclusive options, the first is the "Temporary" check box 
which indicates that the output file is a temporary file and will be removed
after it has been handled by |product|. The other option is a field which allows
specification of a specific filename to be used for the output file. If this
option is selected, the file will not be deleted after it is handled.

Once the above has been specified, the user can specify how |product| should 
handle the file when the process is finished. There are three possible options,
the first is to open the file, the second is to ignore the file, and the last
is to call a Python function to handle the resulting file. If it is desired to
open the file, the file format that the process should use to generate the 
output file must be specified so that |product| will know how to properly load
the results.

If a Python function is specified to handle the output file, the actual
filename can be obtained by using the keyword "@FILE@" in the function
specification. This keyword will be substituted with the real filename at 
process completion time before the Python function is called.

Finally, there is a checkbox at the bottom to specify whether or not this is a 
default output. The default output entry is used when constructing pipes.

.. _figure_process_edit_output:

.. figure:: /_images/process_edit_output.png
   :scale:  75
   :align:  center
   
   *Process Output Editor*

Adding Prompts
--------------

As described previously there are two types of prompts that are available for 
specification on the command line: a text prompt and a file prompt. 

The Text Prompt Editor (see Figure X.Y(a)) allows the 
user to add a text prompt to the process as well as to specify what the 
caption of the prompt will be. Specification of an informative caption is
helpful in allowing the user to know what information is being requested.

.. list-table::
  :widths: 30 30
  :header-rows: 0
  
  * - .. image:: images/process_prompt_text.png
        :align: center
    - .. image:: images/process_prompt_file.png
        :align: center
  * - Text Prompt Editor
    - File Prompt Editor

The File Prompt Editor (see Figure X.Y(b)) allows the 
user to add a file prompt to the process as well as to specify what the caption
of the resulting prompt will be. Specification of an informative caption is 
helpful in allowing the user to know what specific file or type of is being 
requested. 

The result of both of these prompts are passed as command line arguments to 
the process in the order in which they appear in the main text entry box in the
Process Editor (see Figure X.Y).

Pipes
=====

.. _figure_pipe_editor:

.. figure:: /_images/pipe_edit.png
   :scale:  75
   :align:  center
   
   *Pipe Editor*

Once a number of processes have been created, they can be "piped" together
using the Pipe Editor (see Figure X.Y). On the left-hand side
of the editor is a list of all the currently defined processes. On the right is
an ordered list of processes to be run and in which order to run (top to 
bottom).

When chaining processes together into a pipe, it is important that they have 
default input and output fields specified. The default output of a given 
process is passed into the default input of the following process. When the
final process is completed, the user will be notified and the final output
file will be handled based on its specification in the associated process.




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


.. _query:

**************************
Selection Language
**************************

Introduction
============

|product| has several built-in scripting commands, such as *Visible*,
*Select*, *Lock*, *Mark* and *Subset* which take a string argument, where that
string is written in the query language described here.  This query language is
somewhat similar to the command language of the program GRASP.  The query 
language provides a powerful query syntax where atoms, bonds, conformers and 
molecules may be queried to see if they match certain properties.  Triangles, 
vertices and surfaces may be similarly queried.

A fairly simple example is the following command:

``Select("ch='A' && rn=10")``

This command will select all atoms in chain A and in residue 10 for every
molecule currently in memory.

A more complex query is the following:

``Select("id=5 && (r=$hydrophobic || rn=(10,50))")``

which selects every hydrophobic residue or residues with numbers between
10 and 50, but only matches atoms in the molecule with ID 5.

As the examples indicate, the general syntax of the query language is based
on *expressions*.  Each expression consists of a *property*, a
mathematical *operator* and a *value*.  Expressions may be combined using a 
syntax similar to the C and/or Python programming languages.  Boolean 
operations are supported via the *and* operator ``&&``, as well as the 
*or* operator ``||``.  Nesting of parts of the query is possible via 
parentheses ``(`` and ``)``. The operators can also be spelled out as in 
Python: ``and`` and ``or`` are valid for boolean operators.

Operators
=========

|product's| query language supports a full range of mathematical
operators for testing a property's value against the value(s) specified in
the query string.  Supported are =, !=, >, <, >=, and <=.

Lists and Ranges
================

In addition to being able to specify a single value for a property, it is
also possible to specify a *list* of values, or a *range* of
values.  Lists and ranges are provided as a convenience, since they allow
queries matching groups of atoms in a compact manner.

* *LIST* A list is a series of values enclosed in square brackets, 
  for example: ``rn=[4,12,38]``.  This is exactly equivalent
  to ``(rn=4 || rn=12 || rn=38)``; each listed residue is selected.
  It is also possible to negate a list: ``rn!=[4,12,38]``
  selects all residue *except* 4, 12, and 38, and is therefore exactly
  equivalent to ``(rn!=4 && rn!=12 && rn!=38)``.

* *RANGE* A range is a pair of values enclosed in parentheses,
  e.g. ``rn=(1,10)``.  All residues between 1 and 10, inclusive are
  selected, so this command is exactly equivalent to ``(rn>=1 && rn<=10)``.
  Negated ranges are also possible: ``rn!=(1,10)`` is equivalent to
  ``(rn<1 || rn>10)``, and therefore selects atoms *not* in the
  given range.

Lists and ranges are only valid with the = operator and the !=
operator.  It is not legal (and nonsensical) to try to evaluate an
expression such as ``rn>(1,10)``.

Properties
==========

The following properties are defined and may be used for selection:

* *id* - This unsigned integer property limits the match for the
  part of the query it appears in to match only the object with the given ID as
  shown in the list window.  Example: ``id=3``

* *a* - Atom name. This string property matches the atom name.
  Example: ``a=' CA '``.  [Note: The spaces before and after the atom 
  name within the quotes are important.] It may also use the pre-defined sets
  ``a=$sch`` to match side-chain atoms and ``a=$backbone`` or
  ``a=$ba`` to match backbone atoms.

* *an* - Atom number. This integer property matches the atom number.
  Example: ``an=5``.

* *r* - Residue name. This string property matches the residue name.
  Example: ``r='ALA'``.  See also the pre-defined sets in the next
  section titled "Macros/Pre-defined sets".

* *rn* - Residue number. This integer property matches the residue number.
  Example: ``rn=(1,50)``.

* *ch* - Chain. This string property matches the chain.  The chain
  should be a single letter.  Example: ``ch='A'``.

* *model* - Model number. This integer property matches atoms with
  the given PDB-style model number (i.e. for different NMR models). 
  Example: ``model=2``.

* *altloc* - Alternate Location indicator. This string property
  matches atoms with the given PDB-style AlternateLocation property.  The string
  should be a single letter.  Example: ``altloc='A'``.

* *icode* - Insertion code. This string property matches atoms with
  the given PDB-style insertion code. Example: ``icode='B'``.

* *occ* - Occupancy. This floating point property matches atoms with
  the given occupancy property. Example: ``occ>=0.5``.

* *b* - B-factor. This floating point property matches atoms with
  the given crystallographic temperature (B) factor. Example: ``b>=50.0``.

* *q* - Partial charge. This floating point property matches atoms with
  the given partial charge. Example: ``q>0``.

* *Q* - Formal charge. This floating point property matches atoms with
  the given formal charge. Example: ``Q>0``.

* *radius* - Radius. This floating point property matches atoms with
  the given radius. Example: ``radius<1.4``.

* *ac* - Atom color. This unsigned integer property matches atoms with
  the given atom color.  The color should be specified as a packed
  integer, e.g. from ``GetPackedColor`` method on an ``OEColor`` object. 
  Example: ``ac = OEColor(255, 255, 128).GetPackedColor()``.

* *elem* - Element number. This unsigned integer property matches
  atoms with the given element number. Example: ``elem=6``.

* *weight* - Molecular weight. This floating point property matches
  molecules with the given molecular weight.  Example: ``weight>10000``.

* *IsAminoAcid* - This boolean property matches atoms whose residue
  name is the same as an amino acid residue recognized by **OEChem**.  Example:
  ``IsAminoAcid=1``.  Equivalent to ``r=$aa``.

* *IsNucleicAcid* - This boolean property matches atoms whose residue
  name is the same as a nucleic acid recognized by **OEChem**. A, C, G, T, U.
  Example: ``IsNucleicAcid=1``.  Equivalent to ``r=$dna``.

* *IsWater* - This boolean property matches atoms which are in
  a water molecule, as recognized by **OEChem**. Example: ``IsWater=1``.
  Equivalent to ``r=$wat``.

* *IsSubstrate* - This boolean property matches atoms which are not
  protein, nucleic acid or water, as determined by the above queries. Example: ``IsSubstrate=1``.
  Equivalent to ``(IsAminoAcid=0 &&  IsNucleicAcid=0 &&  IsWater=0)``.

* *type* - This string property may be one of "mol", "atom",
  "bond", "tri", "vert" or "surf".  This limits the matches for the
  part of the query it appears in to match either molecules, atoms, bonds,
  triangles, vertices or surfaces, respectively.  Example:
  ``type='atom'``

* *index* - This unsigned integer property limits the matches for
  the part of the query it appears in to items with the given index.  Each
  atom, bond, triangle, etc., has an index assigned when the item is
  created.  Since the indices are generally not exposed to the user, this
  command is probably of limited utility without OEChem-level access to the
  molecules in memory.  Example: ``id=2 && type='atom' && index=10``

* *query* - This string property performs a substructure search
  where the argument is treated as a SMARTS pattern, and so limits the query
  to atoms which match the SMARTS pattern.  Example: ``query='cccn'``

* *subset* - This string property matches all atoms which are in
  the previously-defined subset with the given name.  Subsets may be defined
  via the ``Subset`` command, so the ``subset`` query provides a way
  of creating shorthand references to other complex queries.  Example, first
  define a subset: ``Subset('mysubset','rn=5 && id=2')``.  Then the
  subset may be used as: ``subset='mysubset'``.

* *key* - This unsigned integer property limits the match for the
  part of the query it appears in to match only objects with the given key.
  Example: ``key=100000001``.

* *pkey* - This unsigned integer property limits the match for the
  part of the query it appears in to match only objects whose parent has the
  given key.  Example: ``pkey=100000001``.

Macros/Pre-defined sets
=======================

In addition to explicitly naming residues and atoms, |product| defines
several macros which may be used in query strings.  These macros are
prefixed with a dollar sign ($).  Macros are generally used with the
"residue name" (i.e. ``r=``) property, although a few are used with
the "atom name" (i.e. ``a=``) property.  The definitions for these
sets are largely borrowed from RasMol.

	* ``r=$aliphatic``: ALA, GLY, LEU, VAL, ILE, PRO
	* ``r=$hydroxyl``: SER, THR, TYR
	* ``r=$sulfur``: CYS, MET
	* ``r=$aromatic``: TYR, HIS, TRP, PHE
	* ``r=$charged``: ASP, GLU, ARG, LYS
	* ``r=$amide``: GLN, ASN
	* ``r=$hydrophobic``: ALA, GLY, LEU, VAL, ILE, PRO, MET, PHE, TRP
	* ``r=$polar``: SER, THR, CYS, TYR, HIS, ASP, GLU, ASN, GLN,	ARG, LYS
	* ``r=$neutral``: ALA, GLY, LEU, VAL, ILE, PRO, SER, THR, CYS, MET, PHE, TYR, TRP, ASN, GLN
	* ``r=$acidic``: ASP, GLU
	* ``r=$basic``: ARG, LYS
	* ``r=$small``: ALA, GLY, SER
	* ``r=$medium``: VAL, PRO, THR, CYS, ASP, ASN
	* ``r=$large``: ILE, MET, PHE, TYR, HIS, TRP, GLU, GLN, ARG, LYS
	* ``r=$cyclic``: HIS, PRO, TYR, TRP, PHE
	* ``r=$dna``: ADE, A, GUA, G, CYT, C, THY, T, URA, U
	* ``r=$aa``: all amino acids
	* ``r=$at``: ADE, A, THY, T, URA, U
	* ``r=$cg``: CYT, C, GUA, G
	* ``r=$purine``: ADE, A, GUA, G
	* ``r=$pyrimidine``: CYT, C, THY, T, URA, U
	* ``r=$wat``: WAT, H2O, HOH, TIP, SOL
	* ``r=$substrate``: this is defined as ``r!=$wat &&  r!=$aa	&&  r!=$dna``.

There are two atom name macros as well, ``a=$backbone`` (which may be
abbreviated as ``a=$ba``), which matches specifically protein backbone
atoms, and a sidechain macro, ``a=$sch``, which matches protein sidechain
atoms.  Both of these can be negated (``a!=$backbone`` or ``a!=$sch``).

Scripting with ScratchScope
===========================

In addition to the built-in commands ``Visible``,
``Select``, ``Lock``, ``Mark`` and ``Subset``, it's quite
straightforward to use a selection string with any command which operates
on a *scope*, by binding the selection string to the *ScratchScope*.

For example the following function defines an atom coloring command
``ac``:

::

  def ac(color,str):
    Subset("scratch",str)  # use string to make named subset
    ScratchSet("scratch")  # bind it to scratch scope
    AtomColorSetScoped(OEggColor(color),ScratchScope) # use it

With two small helper functions, these types of functions can be made even
easier to create:

::

  def ScratchSubset(str):
      Subset("scratch",str)
      ScratchSet("scratch")
      return ScratchScope

  def ScratchSubsetList(str):
      Subset("scratch",str)
      ScratchSet("scratch")
      return ScratchList()

With these functions defined, the ``ac`` function above and functions
similar to it can be easily defined.  For example:

::

  def ac(color,str):
      AtomColorSetScoped(color,ScratchSubset(str))

  def lc(color,str):
      LabelColorSetScoped(color,ScratchSubset(str))

  def center(str):
      ViewerCenterSetScoped(ScratchSubset(str))

  def show(str):
      Visible(ScratchSubsetList(str), True)

  def hide(str):
      Visible(ScratchSubsetList(str), False)

In this manner, any of the |product| scripting commands which take a scope
argument can be easily expanded to take a selection string.


.. _vida_releasenotes:

Release History
===============

.. toctree::
   :maxdepth: 3

   version5_0_7
   version5_0_6
   version5_0_5
   version5_0_4
   version5_0_3
   version5_0_2
   version5_0_1
   version5_0_0
   version4_4_0
   version4_3_0
   version4_2_0
   version4_1_1
   version4_1_0
   version4_0_3
   version4_0_0
   version3_0_0
   version2_1_2
   version2_1_1
   version2_1_0
   version2_0_2



VIDA 5.0.7
================================================================================

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

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

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



VIDA 2.0.2
================================================================================

Improvements
------------

* Added "Style" menu to the main menubar which replicates the functionality 
  of the style control (useful in low-resolution settings)
* Added "Center" and "Color" options to the popup dialogs
* Enabled display of named network drives in the file dialog
* Enabled use of native file dialogs instead of custom **VIDA** file dialog as 
  a preference.
* Improved 3D visualization support for lower-end graphics cards	
* Increased default line width in 3D scene for better visibility
* Enabled transparent display of grids (via the "Style" menu)
* Added simple spreadsheet import preview dialog to help select the proper 
  column delimiter (tab vs. comma)    
* Added ``SpreadsheetCurrentSet()`` function which allows specification of 
  current spreadsheet via scripting interface
* Improved the SD file reader for better handling of badly formatted
  SD files
* Improved the handling of situations in which the atom indices 
  specified in input files differ from the order in which they are
  specified
* Improved start-up time as license detection mechanisms have been
  significantly improved

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

* Fixed right-click on empty 2D depiction crash
* Fixed spreadsheet import failure on linux
* Fixed mainwindow snapshots such that file dialog does not obscure the 
  image to be captured
* Fixed license detection routines such **VIDA** will properly detect installed 
  licenses and not cause start-up problems if the license file is moved
* Fixed all other reported crashes not otherwise listed

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

* Fixed a bug in the detection of a user's home directory in networked 
  environments on Microsoft Windows
* Fixed a bug in "measurement" mode where the first atom or bond picked 
  was not being drawn as selected
* Fixed a bug where spreadsheet filtering performed via the scripting 
  interface would not behave as expected if the specified spreadsheet was 
  not the same as the current spreadsheet
* Fixed an uncommon situation in which the locked and visible controls in 
  the list window do not work as expected
* Fixed the handling of certain "escape characters" in filenames specified 
  on the commandline, files dragged onto the **VIDA** icon, and the 
  "startup.py" file such that they no longer prevent the opening of those 
  files


VIDA 2.1.0
================================================================================

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

* Added interactive text annotation of molecules
* Added the ability to start, monitor, terminate, and load results from 
  external processes
* Added a protein sequence viewer as part of the 2D depiction widget
* Added the ``oechemlite`` Python module, enabling significantly
  greater scripting functionality within VIDA
* Added the ability to create arbitrary sphere monitors via the 
  scripting API (see Python API for documentation of the new method
  ``CreateSphereMonitor(...)``)
* Added support for fullscreen display
* Added new \emph{cloud} visualization style for grids
* Added support for copy and paste of molecules from ISIS/Draw
* Added support for use of the Maestro mouse map in the 3D display
* Added support for saving screenshots in JPG format in addition to PNG

Improvements
------------

* Cleaned up the appearance of the right-click popup menus
* Added a "Style" option to the right-click popup menus, when appropriate 
  to the context, which mirrors the main "Style" menu
* Added significantly greater detail to info labels created when holding 
  down the "ctrl" (or "alt" on Mac) key when moving the mouse in the 3D or
  2D views
* Added two default filtered spreadsheets to the application: "Molecules"
  and "Proteins"
* Filled out the scripting API for greater control of the GUI - in 
  particular for menus and toolbar
* Greatly improved the electrostatic coloring scheme for protein surfaces
* Added the ability to change the font used by the application

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

* Fixed a crash when trying to generate electrostatic contours on 
  extremely small molecules (e.g. water)

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

* Fixed a number of preferences that were not being properly saved or
  obeyed by the application
* Fixed the undo stack such the initial setup of the 3D display cannot
  be undone by accident
* Fixed the display of angle monitor measurements from radians to degrees
* Fixed the display of the text scale widget such that it is not hidden
  on low resolution monitors
* Made sure that when saving images and state files, a proper file 
  extension is added to the filename, even if one was not specified


VIDA 2.1.1
================================================================================

Improvements
------------

* Filled out Sybyl mouse map in more detail
* Added "fixed size text" option for labels (see Preferences) such that
  the label font size remains fixed independent of zooming in the scene,
  however the font size can be adjusted using the "Text Scale" slider
  in the Style Bar window
* Added the ability to specify the font for labels when using "nice fonts"
  for labels (see Preferences)
* Added a "custom" option to the atom and bond label dialogs to allow for
  easier specification of custom labels without having to use scripting
  commands
* Improved the drawing of labels such that they always appear in front of
  the object they are labeling
* Improved the ability to see the selected state of partially selected 
  residues in the sequence view
* Added file dialog filter option to allow reading of ASCII formatted 
  grids (*.agd*)
* Added support for native builds on Intel Macs

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

* Fixed a problem with reading spreadsheet information in state files 
  generated by **VIDA** 2.0.x which caused extra tabs to appear in the 
  spreadsheet
* Fixed a problem with writing spreadsheet information correctly in 
  **VIDA** 2.1
* Fixed a crash when reading a badly formatted state file (potentially
  generated by the bug fixed above)
* Fixed a crash when attempting to import a nonstandard whitespace
  delimited spreadsheet (whitespace is not a supported spreadsheet 
  delimiter)
* Fixed a crash on certain video cards when attempting to display 
  "fixed size text" labels
* Fixed a crash caused by dragging state files onto the application icon
  in order to open them
* Fixed an application hang when reading badly formatted XPLOR maps
* Fixed an application hang when reading a badly formatted OEB file
* Fixed a memory leak generated when running a large number of scripting
  commands

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

* Fixed a problem where extra atom labels could appear on molecules when 
  saved to state
* Fixed a problem where CTRL-mouse over atom displays were not seen when
  using non-VIDA mouse maps
* Fixed a bug in the "Text Scale" slider where its position did not always
  reflect the current scale being used
* Fixed a bug where ``OE_DIR`` and ``OE_LICENSE`` environment variables were not 
  being properly exported to the Process Manager on Mac OS X such that 
  spawned applications could not find a valid ``oe_license.txt`` file
* Fixed a bug where exporting a CSV file on Microsoft Windows attached an 
  extra return character causing a blank line to appear between each row 
  when read into Microsoft Excel
* Fixed a few cases where the display of depictions in the spreadsheet
  was not obeying the set preferences
* Fixed a bug where extra calls to undo cleared the redo stack
* Turned off the writing of empty data fields when writing molecules to
  SD or OEB formats. This can be turned back on if truly desired from the 
  Preferences

VIDA 2.1.2
================================================================================

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

* Added "Copy Image" function under the Edit menu which takes a 
  screenshot of the current main window and places it on the clipboard
* Added "Map Index" atom label corresponding to the value returned
  by the OEChem function OEAtomBase::GetMapIdx().

Improvements
------------

* Updated menu system to be compliant with standard UI design 
  practices (such as '...' usage when menu option launches a dialog)
* Updated menu system on Mac OS X to follow common Mac paradigms 
  (e.g. "Open Recents" and "Preferences..." options)
* Reorganized File menu for more logical placement of options 
* Collapsed "New > List >" submenu structure to a single
  "New List >" submenu which appears after the Open, Save
  block
* Added "New Molecules >" submenu which contains a "From Split"
  submenu which provides the "Split Molecules" functionality
  from the old Edit menu. 
* Renamed "Clear All" option to "Clear" and moved up in the menu
  above Save block
* Removed "Abort Script" option as it was redundant (Stop button 
  next to progress bar performs this function) and also could 
  generally not be accessed while a script was running
* Reorganized Edit menu for more logical placement of options as well
  as to provide some commonly performed operations in a single place
* Moved "Split Molecules" functionality to File menu
* Added new "Select" submenu which contains the following options:
  All Visible, Query, Invert, and None
* Added new "Mark" submenu which contains the following options:
  All, Query, None
* Added new "Hide" submenu which contains the following options:
  All, Selected, Marked, Not-Selected, Not-Marked, and None
* Removed the following options as they were redundant given the
  above additions: Hide All, Clear Marked
* Alphabetized list of available windows in the Window menu
* Batch shell window no longer appears when running on Windows
* Redesigned process manager window for easier use
* Significantly improved the quality of POV-ray exports and reduced
  the output file size
* Improved the rendering of electrostatic grids

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

* Upgraded to OEChem 1.4.1 which fixed a number of bugs associated
  with handling bad input files
* Fixed a cross-platform compatibility issue in state files

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

* Fixed "MolecularEnergy()" calculation method in spreadsheet to 
  correctly report energies on multi-conformer molecules
* Fixed "SpreadsheetFilter()" command such that it operates on the 
  specified spreadsheet instead of the current spreadsheet
* Ensured that all current environment variables are properly passed
  to processes started from the process manager
* Fixed the icon on the hydrogen display button to accurately reflect 
  what will occur when the button is pressed
* Fixed a Mac OS X bug where double-clicking on a molecule file started
  **VIDA** but did not actually load the file that was clicked on

VIDA 3.0.0
================================================================================

*August 2011*

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

* Added dynamic help system
* Added new 2D depiction color schemes: black on white, white on black,
  color on white and color on black
* Added new molecule coloring schemes: amino, chain, group, cpk, cpknew,
  shapely, bfactor, formal charge, and partial charge
* Added new surface hydrophobicity scales: charifson, eisenberg, 
  kyte-dolittle, and white-octanol
* Added support for reading attached grids and surfaces in OEB files
* Added support for reading **Spicoli** geometric annotations
* Added support for reading **FRED** receptor files
* Added new hydrogen style: polar hydrogens only
* Added multiple new atom and bond label types (including one for **OEChem** 
  generic data)
* Added new 3D display mouse maps for Coot and PyMol

Improvements
------------

* Anti-aliasing of text and 2D depictions
* Much better control over placement of dock windows
* Dock windows can be stacked on top of each other in tabs
* Single toolbar at the top of the application
* Additional popup toolbars placed around edge of main window
* Enabled grid contour transparency
* Hydrogen style is now a molecule specific property instead of
  a global property
* C-Alpha trace display is now a molecule specific property instead of
  a global property
* Ribbon display is now a molecule specific property instead of 
  a global property
* Many miscellaneous 3D rendering improvements and accelerations
* Many miscellaneous user interface improvements

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

* Upgraded to OEChem 1.5 which fixed a number of bugs

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

* Fixed a problem on some graphics cards where only aromatic rings would
  be drawn when a molecule was in stick mode

VIDA 4.0.0
================================================================================

*AuguAgust 2009*

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

* Added a 1D/2D molecule input dialog which supports SMILES, names, and
  interactive building.
* Added a 3D editing mode which enables significant modification of the
  current molecule including in-vacuo minimization with MMFF94.
* Added support for DNA/RNA ribbon style visualization 
* Added support for displaying and controlling alternate residue 
  conformations (turn on *ALL* flavor when reading PDB files to enable this)
  as well as a number of coloring schemes associated with alternate residues
* 2D depiction in 3D display is now selectable
* Add object-type specific tool buttons to the bottom display which provide 
  context sensitive operations such as coloring and style options.
* Added the ability to import all of OpenEye's Python toolkits for use
  within VIDA, provided that the user has a license for those toolkits.
* Added the ability to transfer molecules, grids, and surfaces between the
  main application and the bundled OpenEye Python toolkits.
* Added support for PythonQt scripting within **VIDA**.
* Added support for PyQt scripting with **VIDA** (separate license required
  from Riverbank computing).
* Added interactive protein depictions in the spreadsheet.
* Added many new atom properties to the atom spreadsheet.
* Added a residue spreadsheet which is capable of controlling alternate
  residue conformations.
* Added the ability to load molecules directly from the PDB 
  ( "File > Open Special > From PDB" )
* Added the following command line arguments:

  ``-e`` - Runs the associated file through the Python interpreter and populates the sys.argv variable with the remaining command line arguments

  ``-eonview`` - Loads the associated files and processes them using the built in *EON* view

  ``-fredview`` - Loads the associated files and processes them using the built in *FRED* view

  ``-rocsview`` - Loads the associated files and processes them using the built in *ROCS* view

  ``-import`` - Loads the associated files and immediately launches the spreadsheet import dialog

* **PICTO** application now ships with **VIDA**. **PICTO** requires a valid **VIDA** license.

Improvements
------------

* Significantly increased the speed of searches performed within **VIDA**.
* Significantly improved and expanded the scripting examples that come
  with the distribution.
* Significantly optimized the loading of OEB molecule files which contain
  attached grids.
* When displaying *Marked* molecules, now only the carbon atoms (as 
  opposed to all) are colored using the *Marked* color unless the 
  non-carbon atoms are specifically *Marked* themselves.
* Optimized the AtomDataGet function when working with multi-conformer
  molecules.
* Vastly improved the display and usability of the embedded 3D toolbars

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

* Fixed rendering problems associated with having multiple overlapping
  transparent surfaces displayed simultaneously.
* Fixed the handling of triple-quoted strings in the **VIDA** interpreter.
* Fixed a bug which was preventing scripts from being aborted while running.
* Fixed a problem where SD data was being lost on read if one or more 
  conformers in a multiconformer molecule did not have the same SD data
  fields as the rest.

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

* Fixed a number of erroneous tooltips.
* Fixed a few spelling errors in prompts and widgets.
* Fixed the behavior of the drop-down selections in the 
  constraints and extra molecule buttons in the FRED View controller.
* Fixed the hybridization, isotope, and symmetry atom labels.
* Fixed a bug where the ColorSetScoped function did not color selected
  atoms if SelectedScope was explicitly specified as opposed to BestScope.
* Fixed the MoleculeMergeScoped function to ensure that residue
  information is not lost when two molecules are merged together.
* Fixed the standard deviation function in the spreadsheet.
* The "Create Spreadsheet" option for list entries in the list windows
  now works as expected.
* Fixed the coordinates returned in the AtomData class by the AtomDataGet
  function when working with multi-conformer molecules.
* Silenced a large number of annoying and unnecessary warnings that would
  appear in the scripting window

VIDA 4.0.3
================================================================================

*June 2010*

Improvements
------------

* Fixed extension loading to enforce rules more consistently & clearly.  Added a dialog
  to notify a user when an extension fails to load at startup.
* Menu items which throw exceptions other than a cancel runtime exception now will display
  a dialog rather than failing quietly.
* Bookmark widget buttons are a touch larger to make them easier to click.
* Augmented menu API to add functions MenuGetAllItems, MenuItemIsAMenu, MenuDisplayNameGet
  and MenuDisplayNameSet.  It should now be possible to determine complete menu
  structure at runtime.
* Sketching a new molecule is much improved.  It now features a simple click and click-and-drag
  interface.
* The invert stereo button in the 2D sketcher & 3D editor is now the default.  It also has
  a slightly improved icon.

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

* Hitting the down arrow in the spreadsheet could result in the current row 
  being reset to the first row, making it impossible to scroll with the arrow
  keys.
* After a lot of editing & deletion, the list window could end up with a 
  corrupted display.
* Some children objects were not properly preserving visibility in state files.  
  Affected types included monitors, and surfaces and grids which were toggled 
  in the style control.
* Files containing Unicode characters previously might fail to load.  They should
  now load properly.
* Improperly constructed extensions could cause problems for the extension manager. 
  The previously might look loaded even though they were not. **VIDA** now handles 
  erroneous extensions correctly.
* The right click "Minimize" option in builder mode attempted to call a non-existent
  function
* Screenshots in .jpg format resulted in empty files on Microsoft Windows
* In some cases, the save dialog would only allow a single item to be clicked.

Minor Bug Fixes
---------------
  
* Stereochemistry in the 2D depictions was not displayed in the spreadsheet or the 2D 
  preview window.
* On some platforms, the graphics widget that controls slabbing and depthcue in the 
  style control can dramatically slow down VIDA, especially for spreadsheet operations.  
  When it is collapsed, this slow down does not occur.  As a temporary work around, 
  the collapsed state of the style control (including the graphics widget) is now remembered
  between sessions.
* Documented the AppVersion, AppVersionMajor, AppVersionMinor and AppVersionBugFix commands.  


VIDA 4.1.0
================================================================================

*August 2011*

New Features
------------
* Simultaneous 2D and 3D editing of small molecules.
* Ability to rotate and translate molecules independently in the builder.
* Simplified authoring of extensions, and inclusion of a number of new example extension scripts.
* Ability to add annotations to existing objects, and have those annotations appear in the List Window.
* Adjustment of torsion angles within rings to change ring puckers and interconvert axial and equatorial substitutions.
* Option to use the MMFF94s force field when building molecules.
* Improved set of fragment templates in the sketcher

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

* Fixed a crash when saving state files after loading a large number of proteins.
* Fixed a crash when editing cells in a spreadsheet.
* Centering on selected atoms would sometimes require a change in visibility before 
  taking effect.  This has been fixed.
* Fixed a bug which caused rows to sometimes disappear when cells in a spreadsheet 
  were edited.
* Spreadsheet depictions are now being updated as molecules are edited.
* An issue which caused the view to occasionally jump unexpectedly during molecule rotations was fixed.
* Fixed a problem which sometimes caused crashes while creating measurements in the "All" scope.
* Changing colors/styles of grids now operates on the proper scope, rather than on all visible grids.
* Addressed issues with the builder and sketcher which sometimes caused fragments to be joined incorrectly.
* Fixed a bug which sometimes caused right-click menus to become inoperative.

Minor Bug Fixes
---------------
* Hotkeys for Marked/Locked/Visible now work on selected rows in the spreadsheet, not 
  just the active molecule.
* Fixed a bug where changes to the spreadsheet cell formats weren't being propagated 
  immediately to the spreadsheet.
* Fixed a bug to have **VIDA** remember the hidden/visible state of depictions in a 
  spreadsheet from one session to another.
* Fixed an issue with the spreadsheet so that users can't edit non-editable cells, 
  such as computed values (e.g., molecular weight, number of rotors) and user-defined 
  python expressions.
* Fixed a sizing problem with the 2D Sketcher window, which had caused some tools 
  in its toolbar to be hidden.
* When a spreadsheet is created from a list, it is now made the current spreadsheet.
* Fixed an issue which would cause blank entries to sometimes appear in the List Window.
* Fixed a rendering problem which caused circles to be displayed incorrectly.
* Corrected an issue in which text would be incorrectly wrapped within labels.
* Display of symmetry-related molecules now updates automatically as the view is translated.
* Surface created in the FRED View are now added to the List Window and can be deleted individually.
* Grid contours are now contoured by default at the original resolution of the grid file.
* Contours of a grid can now be temporarily shown, similarly to conformers, by clicking on their names in the List Window.
* All child objects of grids now show in the List Window.  Previously only the contours would show.
* Corrected an issue which sometimes caused incorrect hydrogen geometries during building.
* Addressed several issues affecting performance and behavior of spreadsheets.
* Fixed an issue that could sometimes cause incorrect stereochemistries to appear in 2D depictions.
* Fixed a bug which caused stereochemistry to be omitted from molecules when copying to the clipboard.
* Corrected strange lasso behavior in the sketcher.

Platform support
----------------
Support for Ubuntu 10 (x64) and RedHat Enterprise v6 (x64) was added.
RedHat Enterprise v3 is no longer supported.

VIDA 4.1.1
================================================================================

*November 2011*

New Features
------------
* Ability to save and restore preferences in extensions.  Many of the example extensions were updated to make use of this new capability, and now preserve settings between **VIDA** sessions.
* Capability to customize molecule lookup and property calculation functions in the builder.
* Adjustable jitter and a new coloring method for grids rendered using the "cloud" style.
* Ability to disable OpenGL hardware rendering via Preferences, to circumvent issues with certain video drivers (most notably, the Intel HD Graphics drivers for Windows).
  

Major Bug Fixes
---------------
* Fixed a crash that sometimes occurred when performing distance selection on proteins.
* Addressed an issue which could cause bond visibilities to become corrupted.
* Fixed an issue which could cause long delays entering build mode in sessions with large molecules.
* Multi-conformer molecules with child molecules were not being displayed properly in the List Window.  This has been fixed.
* Resolved a crash that could occur during torsion measurements on Linux machines.
* Fixed a problem with excessive memory consumption when surfaces were scribed and cropped multiple times.
* Corrected a severe slowdown caused by an interaction of some extensions with a molecule selection dialog.
* Fixed an issue which made check-ins of multiconformer molecules very slow.

Minor Bug Fixes
---------------
* Changed the way FRED View displays binding site residues in the absence of a reference ligand.
* Lasso selection in the 2D Sketcher was leaving hydrogens in the 3D window unselected.  This has been corrected.
* An issue preventing **VIDA** from reading files with capitalized or mixed-case file extensions was fixed.
* A problem which caused torsion measurements on Windows platforms to be incorrectly rendered was fixed.
* Fixed a bug which prevented users from being able to set surface coloring defaults.
* Made performance improvements to some of the **VIDA** extensions.

VIDA 4.2.0
================================================================================

*September 2012*

New Features
------------
* A "telemodeling" feature has been introduced (as an included **VIDA** extension),
  and allows interactive sharing of **VIDA** sessions over a network.
* 3D graphics shading calculations have been redone, to provide much nicer 
  looking rendering of 3D objects.
* Solid-rendered 3D objects now include edge outlines to improve clarity.
* **VIDA**'s spreadsheet has been updated with several new features:

  - Depictions now use the new **OEDepict TK**, and can be displayed in color.
  - Atom selection is reflected in the spreadsheets.
  - Structures from SMILES strings can now be displayed in spreadsheet cells.
    Just put the string "(smiles)" anywhere in the column name.
  - URL's in the spreadsheet are now treated as active hyperlinks.
  - Row heights can be adjusted all at once, to interactively scale (and hide)
    molecular depictions.
  - The VIDA Name column has been removed.
  - New columns can be added via a "+" button in the spreadsheet headers 

* Spreadsheets can now be exported directly to PDF files.
* Filenames of files opened within **VIDA** now show in the title bar of **VIDA**'s
  main window.
* The behavior of the "Recents" menu has been changed, so that it now displays
  both recently opened and recently saved files, including **VIDA** state (.oes)
  files.  In addition, a "Recent Directories" menu has been added.
* A "protein sequence" coloring scheme has been added which colors protein 
  molecules using a gradient from N-terminus (blue) to C-terminus (red).
* The Extension Manager has been rewritten to simplify the user interface.
* **VIDA** can now automatically subscribe to sets of VIDA Extensions pointed to 
  by the environment variable, VIDA_EXTENSIONS_URL.
* Several rarely-used icons have been removed from **VIDA**'s main window, and the
  "Style Toolbar" at the top of the 3D window is now empty by default.
* An example docking extension is now provided, to allow docking of molecules
  against a pre-prepared receptor for customers with an **OEDocking TK** license.
* New commands for disabling and clearing **VIDA**'s "Undo" stack have been added
  to the scripting API.  These can be used to prevent repeated operations from
  building up large amounts of "undo" memory unnecessarily.
* **VIDA** can now read MTZ crystallographic reflection files from several common 
  refinement programs and generate regular and difference maps from them.
* A new preference setting allows molecules without 3D coordinates to be 
  displayed in the 3D window.
* Monitors (for distances, torsions, etc.) can now be deleted from within the 
  "Measure" option in the Mouse Toolbar.
* **VIDA** now incorporates the released versions of OpenEye toolkits, including
  the newer **OEDocking TK**, **OEDepict TK**, and **Grapheme TK**.
* The Preferences dialog behavior has been modified to allow updating of 
  preferences without dismissing the dialog.
* The installer for Windows now allows association of user-selectable file
  types with **VIDA**.
* Load times have been significantly improved for files containing large 
  numbers of molecules.
  
Major Bug Fixes
---------------
* Under certain conditions, working with a protein with alternate conformations
  could cause corruption of state files.  This has been corrected.
* A problem causing failure of molecule check-ins after deleting and re-adding
  hydrogens has been fixed.
* A severe graphics slowdown on Windows machines with Intel HD Graphics video 
  has been addressed by new OpenGL rendering methods.
* A bug which caused atom names to sometimes be lost when merging molecules 
  has been fixed.
* Stereochemistry is now preserved when pasting structures from ChemDraw or
  reading .cdx files.
* A graphics bug which made all 3D labels show up in black on certain video
  cards has been corrected.

Minor Bug Fixes
---------------
* Molecules created by typing a name in the builder would be named with a
  SMILES string instead of the type-in name, unless a valid **Lexichem TK** license
  was found.
* MoleculeColorByScope() and related functions have been fixed to work properly
  with molecule keys in the Scratch Scope.
* Molecule surfaces are now automatically updated when the molecule is edited.
* On machines with desktops spanning multiple monitors, **VIDA** could sometimes
  place the main window and Preferences dialog offscreen.
* The **VIDA** icon now shows correctly when the application is pinned to the 
  taskbar in Windows.
* Disabled inner contours from **FRED** receptor files are no longer displayed.
* Previously, users could see very slow performance in the File/Save dialog, 
  when trying to select all molecules with the topmost checkbox. This problem 
  has been eliminated.

Platform support
----------------
Support for Ubuntu 12 (x64) and Mac OS X 10.7 has been added.

VIDA 4.3.0
================================================================================

*August 2014*

New Features
------------
* "Drag and Drop" is now supported for rearranging items in the List Window.
* Advanced depiction options, including atom property maps from the **Grapheme 
  TK**, substructure highlighting, and 2D structure alignment, are available 
  for depiction in the 2D window and spreadsheet.
* Improved surface rendering using the new "atom splitting" feature from the 
  **Spicoli TK**.
* Atom-based selection of surfaces.
* Atom and surface selection is now indicated using bright outlines instead of 
  atom coloring.
* A new "Select" menu provides a wide range of ways to select atoms.  The 
  menu also allows creation and manipulation of named sets of atoms.
* A surface hydrophobicity coloring scheme based on atomic XLogP contributions 
  was added.
* A new surface "curvature" coloring scheme was added that combines the 
  previous "concavity" and "curvature" schemes.
* An additional **VIDA** extension for coloring molecules by SD data is included.
* An example "Cluster Browsing" script, for viewing clustered molecule data, 
  is included.
* Many enhancements were made to the Extensions Manager dialog, to allow better
  handling of extension subscriptions.  Other extension improvements include 
  the ability to specify the order in which extensions are loaded, and the 
  ability to use the VIDA_EXTENSIONS_URL environment variable to specify 
  multiple auto-subscriptions.
* Molecular surfaces can now be created over sets of selected atoms, and can 
  be regenerated via the Style Control.
* The **VIDA** spreadsheet can now include generic data stored on molecules and 
  conformers.
* The List Window now allows clicking on column headers to show/hide, mark, 
  and lock all items in the list.
* The builder now issues a warning (and opportunity to cancel) if a protein 
  molecule has been put into Edit mode.
* Extension authoring was made easier by allowing local filenames in .pyx 
  and .pyxs files.

Major Bug Fixes
---------------
* A crash from undoing conformer deletion has been fixed.
* A number of stability issues and strange window behavior under OS X 10.8+
  have been resolved.
* A crash while creating C-alpha traces for some proteins was fixed.
* Several operations in the sketcher could create radicals unexpectedly. This
  has been corrected.

Minor Bug Fixes
---------------
* Fixed a warning message when opening .cdx files.
* A problem with state files not preserving child object visibilities was 
  corrected.
* SMILES (.smi) files now contain stereochemical information by default.
* Installation of some extensions caused reading of large files to slow down
  significantly. 
* The save dialog was very slow to initialize for large files. 
* New lists created (e.g., from "Marked" molecules) now become the current 
  active list.
* Switching to stereo during a telemodeling session would lose synchronization
  between the connected sessions.
* B-Factor labels can now be shown on any atoms, not just C-alpha atoms.
* Files opened via the command line now appear in the "Recents" list.
* Fixed an issue with extension updates requiring an extra **VIDA** restart to take
  effect.
* A problem with exiting fullscreen mode was fixed.
* A crash on exit when using certain extensions on Linux machines was fixed.
* Grids rendered from CCP4 files now use the statistics embedded in the file, 
  rather than statistics generated within **VIDA**.

Platform Support
----------------
* Support for Ubuntu 14 was added.
* Support for RedHat v7 was added.
* Support for Mac OS X 10.8 and 10.9 was added.
* Mac OS X 10.6 is no longer supported.
* RedHat v4 is no longer supported.
* Windows XP is no longer supported.

Other
-----
**Vivant** is being retired, and no longer ships with **VIDA**.  Existing versions of
**Vivant** will continue to function and remain compatible with **VIDA**'s current
state files.

VIDA 4.4.0
================================================================================

*February 2018*

New Features
------------
-  A new ribbon style has been introduced into **Spicoli TK** and is now
   being used to render ribbons within **VIDA**. The new style produces
   ribbons with a smoother appearance.

-  Various improvements to the Builder/Sketcher behavior have been made,
   including:

   -  closing the Sketcher window now prompts for *Save*, *Save as New*,
      *Discard*, or *Cancel*

   -  closing the Builder now closes the Sketcher window

   -  an additional *Save As New* option appears in the toolbar and
      Builder context menu

   -  hitting *Return* now finishes adding typed-in molecules from the
      Sketcher

-  An *Unhide Atoms* option was added to the *Select* Menu.

-  Extensions can now be deactivated centrally by appending ``-remove`` to
   the extension’s entry in a PYXS subscription file. Various other
   improvements to the Extension Manager behavior were also made.

-  3D renderings of ``OEAnnotation`` objects are now selectable.

-  Several improvements have been made to the Scripting window,
   including to the *Paste* and *Drag*/*Drop* behavior.

Major Bug Fixes
---------------
-  A bug that caused waters to not show as hydrogen bond acceptors has
   been fixed.

-  An issue that caused bond torsions to rotate atoms on the wrong end
   of the bond has been fixed.

-  A crash caused by excessive memory use while centering a large number
   of molecules in All Scope mode has been rectified.

-  A bug that could sometimes cause a crash when changing the font size
   in the 3D Window has been fixed.

-  A memory leak that occurred when switching screenshots or switching
   layouts has been fixed.

-  A crash that could occur when adding large number of grids has been
   fixed.

-  A crash that could occur when shift-selecting surfaces on proteins
   has been fixed.

-  A crash that occurred when clicking the *List Window*'s *visibility*
   header button when a grid and many molecules were loaded has been
   fixed.

-  Coloring proteins using the *Alternate Locations* coloring scheme no
   longer crashes the program when applied to molecules without
   alternate locations specified.

-  A conflict between the Qt libraries installed with **VIDA** and the
   Qt libraries included in Kubuntu would cause a “Cannot mix
   incompatible Qt libraries” error message when starting **VIDA**. This
   error has been corrected by including some additional Qt libraries in
   the **VIDA** distribution.

Minor Bug Fixes
---------------
-  The *Save* dialog had been performing very slowly when a large number
   of molecules were loaded. This has been fixed.

-  Screenshots made from the 2D Viewer are no longer saved with a
   border.

-  An issue that caused a complete molecular surface to appear during
   operations on molecules with partial surfaces has been fixed.

-  A problem with synchronizing selections between atoms in the 2D/3D
   Viewers and atoms in the SMILES display in the 3D Viewer has been
   fixed.

-  Aromaticity of certain molecules with tetravalent sulfur atoms had
   previously displayed inconsistently between the sketcher and the 3D
   Viewer. This has been fixed

-  A bug that could cause electrostatic grids generated using AM1BCC
   charges to generate incorrect contours has been fixed.

-  The default electrostatic surface grid spacing has been increased.

-  In certain cases, rounding errors were causing incorrect sorting
   behavior for very large numbers in the spreadsheet. This was fixed by
   changing the internal representation for spreadsheet numbers from
   floats to doubles.

-  Changing the application layout no longer hides visible extension
   windows.

-  A problem with setting bookmark animation timings has been fixed.

-  Minor fixes to the *Extensions Manager* dialog have been made.

-  Behavior of the ``AtomLabelSetScoped`` function has been fixed to
   make long label-type arguments (e.g., “residue info (ca)”) work as
   described in the documentation.

-  A bug that made hyperlinks in the spreadsheet case insensitive has
   been fixed.

-  Some geometry issues with the Attach and Fuse operations in build
   mode have been fixed.

-  A *Donor* option had been missing from the *Select Within Focused*
   dialog. This has been fixed.

-  A bug that affected the preferences for depicting superatoms in 2D
   renderings has been fixed. In addition, a new dialog for specifying
   which functional groups to render as superatoms has been added.

-  The *Show Axes* preference under the 3D Display General preferences
   now displays the axes at the center of the 3D view.

Platform Support
----------------
-  Support for 64-bit Windows has been added.
-  32-bit Windows is no longer supported.
-  Support for Ubuntu 16 has been added.
-  Support for RedHat v7 has been added.
-  RedHat v5 is no longer supported.
-  Support for Mac OS X 10.10 Yosemite has been added.
-  Support for Mac OS X 10.11 El capitan has been added.
-  Support for macOS 10.12 Sierra has been added.
-  Support for macOS 10.13 High Sierra has been added.

Other
-----
- Version 4.4.0 will be the last version of **VIDA** supporting Python 2.7. 
  Future versions will be based on Python 3.

VIDA 5.0.0
================================================================================

*July 2021*

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

* VIDA has been updated and ships with the current toolkit release 2021.1.

* VIDA has been updated to use Python 3.

* VIDA has been updated to use Qt 5. In addition we have switched for PyQt to `PySide2 <http://wiki.qt.io/Qt_for_Python>`_, providing full access to the
  Qt library via Python.

* VIDA extensions have been updated to Python 3 and Qt 5.

* VIDA now supports opening OEDesignUnits and recognized the OEDU file format. VIDA will also show OEReceptor information if stored on the OEDesignunit.
  OEDesignUnits will not be able to be saved in this release.

* VIDA now supports opening MMCIF files.

* File->Open Special->From PDB will now download an MMCIF file if a PDB file is not available for a particular PDB code.

* Several toolbar icons have been updated

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

* Improvements have been made regarding loading of state files

Removed features
----------------

* Support for hardware stereo has been removed

* The screenshot tool has been removed



VIDA 5.0.1
================================================================================

*Fall 2021*

* Minor internal improvements have been made.




VIDA 5.0.2
================================================================================

*Spring 2022*

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

* ``mcr`` files are now a supported file type within VIDA.

* The ability to display in hardware 3D stereoscopic via OpenGL Quad Buffering on Windows
  with compatible graphics devices has been restored.  
  
Minor Bug Fixes
-------------------------------------------------------------------------------

* Reduced many warnings generated in the Scripting Window or in the terminal from which VIDA was launched.



==============
VIDA 5.0.3
==============

*Fall 2022*

Minor internal improvements have been made.



==============
VIDA 5.0.4
==============

Minor internal improvements have been made.



==============
VIDA 5.0.5
==============

Minor internal improvements have been made.



VIDA 5.0.6
================================================================================

Minor internal improvements have been made.





.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


.. _scripting:

*********************
Scripting
*********************

|product| is a scriptable application which contains a built-in Python 
interpreter. Python is an interactive, interpreter, strongly and dynamically 
typed language. More information about Python can be obtained from the `Python 
website <http://www.python.org>`_. The website contains many useful 
tutorials and other related information.

All user interaction with the application goes through a Python layer even if
the user is not aware of it. For instance, every button in |product| is 
associated with a Python command that is sent to the internal interpreter when
that button is pressed. The same integration is true of all the menu items and
other GUI controls in |product|.

.. _journal_file_ref:

Journal File
============

The journal file is a recording of every action that is performed within a 
given session of |product|. In fact, the journal file is itself a Python script 
which can be run to regenerate the state of the application at the time the
file was written.

The journal file is written to ``journal.py`` in the user directory (see 
:ref:`User Directory <user_dir>`). In the unlikely event that |product| were to quit
unexpectedly, the journal file corresponding to that run will be saved in the
same directory but with a different name containing a time stamp associated
with when the application was started (e.g. ``journal_WedMar181507132009.py``).
Journal files are particularly useful for debugging unexpected application
behavior and are of extreme benefit to the application developers when 
tracking user-reported bugs. The inclusion of journal files (if possible) with
bug reports is greatly encouraged.

.. _startup_file_ref:

Startup File
============

The startup file is a Python script located in the user directory (see
:ref:`User Directory <user_dir>`) named ``startup.py``. This script (if present) is executed
each time |product| starts.

The startup file provides the user with a convenient mechanism to customize
the appearance and functionality of |product| using Python.

.. _scripts_directory_ref:

Scripts Directory
=================

In addition to interpreting the startup file (see :ref:`startup_file_ref`)
at runtime, |product| also executes any Python scripts contained in the 
``scripts`` directory of the user directory (see :ref:`User Directory <user_dir>`). This
capability provides a simple mechanism to quickly and easily add or remove 
custom functionality to |product| without having to change the startup file.

.. _scripting_manual_ref:

Scripting API
================

The complete details of the |product| Python interface and API are fully 
described in the appendix.

.. _scripting_window_ref:

Scripting Window
================

The scripting window provides an interactive user interface to the embedded 
Python interpreter. It also displays the output from any Python commands 
issued to |product| as well as any warnings or errors reported by the 
application.

.. _figure_scripting:

.. figure:: /_images/scriptingwindow.png
   :scale:  75
   :align:  center
   
   **Scripting Window**

The scripting window supports tab completion of the built-in API methods and
hitting the tab key again after tab completion will display the API 
documentation associated with the command directly in the window.

The window history can be cleared by typing the following command 
``InterpreterClear()`` into the scripting window.

.. _openeye_toolkits_ref:

OpenEye Toolkits
================

|product| provides the ability to import any of the OpenEye Python toolkits 
directly into the interpreter. Once a toolkit has been imported, its entire
functionality is available for use within |product|. A valid license for the
imported toolkit is required in order for the import to succeed. An exception 
will be thrown at import time if a valid license cannot be found. All of the 
toolkits come directly bundled with the application, so there is no additional 
need to perform any installation. 

Molecule, grid, and surface objects can be passed back and forth between the 
main application and the Python interpreter using a handful of methods. For
stability reasons, copies of these objects must be "checked out" of |product|, 
where they can be accessed by the toolkits. If any modifications are made to 
the objects in the interpreter, these modifications can be applied to the 
associated objects in |product| by "checking in" the modified object. One 
exception to this rule, is that it is possible to make display changes to the 
original objects by calling the built-in API functions and passing in the 
unique key obtained from the object using the ``GetKey()`` method. A number of
examples follow.

.. ..oe:source:: check_out_molecule.py
   :caption:  Check out a molecule, make a modification, and check it back in 
   :refnum:   1

.. ..oe:source:: add_molecule.py
   :caption:  Add a new molecule from Python
   :refnum:   2

.. ..oe:source:: check_out_surface.py
   :caption:  Check out a surface, make a modification, and check it back in
   :refnum:   3
   
.. ..oe:source:: add_surface.py
   :caption:  Add a new surface from Python
   :refnum:   4
   
.. ..oe:source:: check_out_grid.py
   :caption:  Check out a grid, make a modification, and check it back in
   :refnum:   5
   
.. ..oe:source:: add_grid.py
   :caption:  Add a new grid from Python
   :refnum:   6

.. _oechemlite_ref:

OEChem Objects
--------------

Most of the standard scripting functions in |product| that operate on atoms,
bonds, or molecules take a unique key as a parameter.  |product| 
adds a ``GetKey()`` function to every **OEChem** object (e.g., OEMol, OESurface,
OEAtomBase, etc.) that is accessed from |product|.
In addition, |product| adds the following methods to all 
accessed objects for convenience:

* ``IsActive()``
* ``IsLocked()``
* ``IsMarked()``
* ``IsSelected()``
* ``IsVisible()``
* ``SetLocked( value = True )``
* ``SetMarked( value = True )``
* ``SetSelected( value = True )``
* ``SetVisible( value = True )``

Access to a given molecule is provided through the 
``MoleculeGet`` function. The molecule object returned is a copy of the actual 
molecule in use in |product|. However, this copy can still be used to retrieve 
information about that original molecule as well as to alter the original 
molecule's display and associated data through the standard |product| API.

.. ..oe:source:: get_molecule.py
   :caption:  Get a molecule and select all the carbon atoms
   :refnum:   1

.. _customize_ui_ref:

Customizing the User Interface
==============================

The standard |product| scripting API provides a wide variety of options to 
customize both the menus and toolbars and is detailed extensively in the appendix.

More advanced customization and extension of the user interface is possible 
through the `PySide2 module <https://pypi.org/project/PySide2/>`_, which provides Python wrappers for the Qt
widget library used by |product| for its user interface. Using 
this module within |product| enables
the user to create and interact with entirely new user interface elements.
The specific details of the PySide2 module are described in the section below. 
For more details on Qt, please visit these links: `Qt Company <https://www.qt.io>`_,
`The Qt Project <http://www.qt-project.org>`_ and `Qt for Python project <https://wiki.qt.io/Qt_for_Python>`_.

.. _pyside2_ref:

PySide2
--------

PySide2 is developed by the `Qt for Python project <https://wiki.qt.io/Qt_for_Python>`_ and
is supported by the `Qt Company <https://www.qt.io>`_.

PySide2 is a complete wrapper around the Qt library which 
enables complex user interface customization and development. 

In addition,
to a complete and fully functional API for building widgets, PySide2 can also 
build widgets using the output from 
`Qt Designer <https://doc.qt.io/qt-5/qtdesigner-manual.html>`_. 
Qt Designer
is a graphical tool for designing and building user interface elements from Qt
components. Designer can save the finished widget design to an XML file (.ui) 
which can then be passed to a widget object for creation in Python. The user 
must have a valid Qt license in order to use Qt Designer.

For more details on PySide2, please visit:
`Qt for Python project <https://wiki.qt.io/Qt_for_Python>`_




.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


.. _spreadsheet:

*********************
Spreadsheet
*********************

The spreadsheet window is used to view, compute, and analyze data associated 
with molecules and can be seen in 
:ref:`Figure: Spreadsheet Window<figure_spreadsheet_1>`. The spreadsheet window 
contains four initial spreadsheets by default: *Molecules*, *Proteins*, *Atoms* and 
*Residues*. The *Residues* and *Atoms* spreadsheets behave slightly different 
than the other two and are described later. Additional spreadsheets can be 
added during use such as the *IC50* spreadsheet shown in 
:ref:`Figure: Spreadsheet Window<figure_spreadsheet_1>`.

The *Molecules* spreadsheet is populated with all currently loaded small 
molecules (fewer than 255 atoms).  Conversely, the *Proteins* spreadsheet is 
populated with all of the currently loaded molecules that have more than 255 
atoms.

The columns and their associated values are populated from SD data. SD data can 
be found in both SDF and OEB files. Additional spreadsheet columns can be 
added from generic data, by computing Python expressions or by importing 
external data from 
a comma-separated value (.csv) or tab-separated value file (.txt).

.. _figure_spreadsheet_1:

.. figure:: /_images/spreadsheet1.png
   :scale:  75
   :align:  center
   
   **Spreadsheet Window**
 
   *The spreadsheet being used as the main window of the application*

Basic Usage
===========

Columns are divided into two basic types: data and property. Data columns are
those found in SD data and/or imported files. Property columns include:

* Depiction - This column contains either a 2D depiction of the associated 
  molecule (for small molecules) or an interactive 3D rendering of the protein
  backbone (for proteins).
* VIDA ID - This column contains the unique identifier assigned to that 
  object by VIDA.
* VIDA Name - This column contains the title of the molecule as displayed in 
  VIDA.
* Visible - This column contains an indicator (green dot) showing whether 
  the molecule is *Visible*.
* Marked - This column contains an indicator (red flag) showing whether 
  the molecule is *Marked*.
* Locked - This column contains an indicator (padlock) showing whether 
  the molecule is *Locked*.

Clicking on any data cell in the spreadsheet will cause the associated molecule to 
become the *Focused* molecule. Double-clicking on a cell in the 
spreadsheet enables modification of the data value in that particular cell. 
Some columns cannot be changed, such as the *VIDA ID* or *Depiction* columns.

Clicking the mouse on a molecule's depiction and dragging the mouse 
to another application will transfer that image to that application. This 
provides an easy way to transfer molecular images to other documents.

*Visible*, *Marked*, and *Locked* properties can be toggled for selected rows
by clicking in their columns, or by pressing the keys, V(isible), M(ark), or 
L(ock), respectively.  When a range of rows is selected, toggling properties in
any of the selected rows will toggle the same property in all of the selected
rows.

Sorting
=======

A spreadsheet can be sorted by clicking on a column header which will sort the
current spreadsheet according to the data values in the associated column. If the 
data in the column to be sorted contains both numeric and non-numeric values, 
each set (numeric and non-numeric) will be sorted independently and then 
concatenated together.  Clicking again reverses the sort order.

Multiple columns can be sorted simultaneously by selecting the "Sort 
Spreadsheet..." option from the top level *Data* menu. This will launch
a dialog that can be seen in :ref:`Figure: Sorting<figure_spreadsheet_sort>`. 
This dialog can also be launched by right-clicking on any column header and 
selecting the "Sort Spreadsheet..." option from the generated popup menu.

.. _figure_spreadsheet_sort:

.. figure:: /_images/spreadsheetsort.png
   :scale:  75
   :align:  center
   
   **Sorting**
   
   *Simple dialog to control how the current spreadsheet is sorted*

This sorting dialog allows for the selection of up to three columns. The
spreadsheet will initially be sorted by the first column selected, with ties being 
broken by the remaining columns. The sorted columns can be moved to the 
front of the spreadsheet by selecting the "Move Sorted Columns to Start"
option in the dialog.

The first time the spreadsheet is sorted, it may take longer than expected as
the data values need to be retrieved from the molecule and any expressions must
be calculated. The progress of the sort is indicated by the progress bar at the
bottom of the application. If desired, the sort can be aborted by clicking on
the stop button to the left of the progress bar.

Displaying Data
===============

The visibility of columns can be toggled by selecting the associated column 
name from the right-click popup menu generated by clicking on any column 
header.  Data column names can be found in the "Column Visibility" submenu.
Hiding the depiction column can allow for more rows to be displayed at the same
time.

Certain molecular properties, such as molecular weight, can be added as new 
columns by selecting the desired option from the "Molecular Properties" 
submenu in the right-click popup menu.  Some of these properties, such as 
Energy, might not be set on the molecule and as such the associated cell will
contain an empty value.

Organizing Columns
==================

Columns can be organized in the spreadsheet by selecting the "Organize 
Columns" option in the top level *Data* menu. This will launch a dialog 
which can be seen in 
:ref:`Figure: Column Controller<figure_spreadsheet_column_manage>`.

.. _figure_spreadsheet_column_manage:

.. figure:: /_images/columnmanage.png
   :scale:  75
   :align:  center
   
   **Column Controller**
   
   *The display of individual columns can be customized using this dialog*

The order of the columns can be controlled by selecting individual columns and
then clicking on the up or down arrow buttons to change that columns position 
in the order. Furthermore, columns can be deleted by clicking on the button 
with the red X icon. Please be aware that deleting a column will delete the 
associated data from all currently loaded molecules and spreadsheets.

Creating New Columns
====================

Columns for common molecule and atom properties can be easily added to a 
spreadsheet using the pull-down menu in the far right column of the 
spreadsheet header.  The Molecule Properties (or Atom Properties for the Atoms 
spreadsheet) submenu of this menu offers large selection of common properties
that can be used to make new spreadsheet columns.

.. _figure_spreadsheet_create_columns:

.. list-table::
  :widths: 25 25 25
  :header-rows: 0
  
  * - .. image:: images/createcolumn.png
        :align: center
    - .. image:: images/createsimplecolumn1.png
        :align: center
    - .. image:: images/createsimplecolumn2.png
        :align: center
  * - Creating a new column
    - Using a math function in the expression
    - Referencing another column

For more complicated properties, new columns can be added to the spreadsheet 
with values that are based 
on, or calculated from, molecular properties or existing spreadsheet data. To 
create a new columns, select the "Create Column" option in the top level
*Data* menu, or click the "+" button in the spreadsheet header. This will launch a dialog to guide the process and can be 
seen in :ref:`Figure: Create Column<figure_spreadsheet_create_column>`.

.. _figure_spreadsheet_create_column:

.. figure:: /_images/createcolumn.png
   :scale:  75
   :align:  center
   
   **Create Column**
   
   *Create a new spreadsheet column by specifying a Python expression*

The text entry field at the top contains the name for the new column. A new, 
empty and editable column can easily be created by supplying a new column 
name and then clicking the "Create" button.

Beneath the name is a collection of three lists containing functions
which can be used in building the expression to be evaluated when populating
the column. The first box contains a list of the already existing columns which can be used as part of an expressions. The second box contains a list of 
available molecular properties.  The third box contains a list of available 
mathematical functions. 

Beneath the boxes is a large text entry window which will contain the
desired Python expression used to calculate the new data values. Any valid 
Python expression can be specified here. Just beneath this window is a test field 
which displays the output of running the specified expression on the first row in 
the current spreadsheet.

.. _figure_spreadsheet_create_simple1:

.. figure:: /_images/createsimplecolumn1.png
   :scale:  75
   :align:  center
   
   **Math Functions**
   
   *Specifying a math function to be used in the expression*

Any of the previously mentioned functions can be added to the Python expression 
simply by selecting the desired function in the appropriate drop down box. If that 
function requires additional input (such as functions like *sqrt*), the cursor in 
the expression editor window will automatically be placed inside the function. 
Functions can be combined with standard math operators such as "\*", 
"+", "-", and "/". If a function requires additional input that
is not provided, an error will be displayed in the Test section at the bottom 
of the dialog as seen in 
:ref:`Figure: Math Functions<figure_spreadsheet_create_simple1>`. 
Frequently, the desired input is contained 
within another column which can be referenced by selecting the desired column 
from the third drop down box or simply by typing "COL('COLUMN NAME')" as seen 
in :ref:`Figure: Referencing a Column<figure_spreadsheet_create_simple2>`.

.. _figure_spreadsheet_create_simple2:

.. figure:: /_images/createsimplecolumn2.png
   :scale:  75
   :align:  center
   
   **Referencing a Column**
   
   *Referencing another column to provide data for the expression*

Once the desired expression has been assembled, the column can be created and
added to the spreadsheet by clicking on the "OK" button. 

Math Functions
--------------

A number of math functions are available for use in spreadsheet 
expressions as described in the previous section. The currently available math
functions can be found in :ref:`Table: Math Functions<table_math_functions>`.

.. _table_math_functions:

.. table:: Math Functions
   
   =============== ============================================================
   **Name**        **Description**  
   =============== ============================================================ 
   sqrt(x)         Return :math:`\sqrt{x}`. 
   log(x[,base])   The logarithm of x to the given base.  
                   If the base is not specified, returns ln(x). 
   log10(x)        The base 10 logarithm of x. 
   exp(x)          Return :math:`e^x`. 
   pow(x,y)        Return :math:`x^y`. 
   ceil(x)         Return the ceiling of x as a float.  
                   This is the smallest integral value >= x. 
   floor(x)        Return the floor of x as a float.
                   This is the largest integral value <= x. 
   =============== ============================================================

OEChem Functions
----------------

A large number of molecular properties are available for use in spreadsheet 
expressions as described above. The currently available molecular properties
can be found in :ref:`Table: OEChem Functions<table_oechem_functions>`.

.. _table_oechem_functions:

.. table:: OEChem Functions
   
   =================================== =================================================================
   **Name**                            **Description**  
   =================================== =================================================================
   Molecular Weight                    Molecular weight. 
   Energy                              Molecular energy of the molecule as specified in the input file. 
   Num Atoms                           Number of atoms in the molecule. 
   Num Bonds                           Number of bonds in the molecule. 
   Num Halides                         Number of halogen atoms in the molecule. 
   Num Carbons                         Number of carbon atoms in the molecule. 
   Num Heavy Atoms                     Number of heavy atoms (non hydrogen) in the molecule. 
   Num Hetero Atoms                    Number of hetero atoms in the molecule. 
   Num Hydrogens                       Number of hydrogen atoms in the molecule. 
   Num Hydrogen Acceptors              Number of hydrogen bond acceptors in the molecule.
   Num Hydrogen Donors                 Number of hydrogen bond donors in the molecule.
   Carbon-Hetero Ratio                 Ratio of carbons to hetero atoms in the molecule. Returns 1 if there are no carbons in the molecule. 
   Num Rigid Bonds                     Number of rigid bonds in the molecule. 
   Num Rotatable Bonds                 Number of rotatable bonds in the molecule. 
   Formal Charge                       Sum of the formal charges on all atoms. 
   Num Formal Charges                  Number of atoms with a specified formal charge. 
   Partial Charge                      Sum of the partial charges on all atoms. 
   Is Chiral                           1 or 0, indicating whether the molecule is chiral.
   SMILES                              SMILES representation of the molecule.
   Molecular Formula                   Molecular formula for the molecule.
   =================================== =================================================================

Filtering
=========

New spreadsheets may be generated from an existing one by means of filtering. The
mechanism to filter a spreadsheet is very similar to the creation of a new 
column. To create a filtered spreadsheet, select the "Filter Spreadsheet..." 
option from the top level *Data* menu, or right-click in the header of the spreadsheet
and choose "Filter...". This will launch a dialog which can be 
seen in 
:ref:`Figure: Filter Dialog<figure_spreadsheet_filter>`. This dialog will assist 
in the creation of a new 
filtered spreadsheet based on the currently viewed spreadsheet. Please note, 
that it is possible to create filtered spreadsheets on other filtered 
spreadsheets. The result of a filtering operation can be seen in 
:ref:`Figure: Filtered Spreadsheet<figure_spreadsheet_filter_complete>`.

.. _figure_spreadsheet_filter:

.. figure:: /_images/filterspreadsheet.png
   :scale:  75
   :align:  center
   
   **Filter Dialog**
   
   *Create a new spreadsheet by filtering on a specified column*

.. _figure_spreadsheet_filter_complete:

.. figure:: /_images/filtercomplete.png
   :scale:  75
   :align:  center
   
   **Filtered Spreadsheet**
   
   *A new spreadsheet created by filtering on the values in a specified column*

Filter expressions are very similar to column generation expressions, except 
that the return value of a filter expression determines whether or not that 
row will be included in the new spreadsheet. Rows for which the expression 
returns either *False* or *0* will not be included.

A wide variety of filters are possible through the judicious use of Python
in the expression. For instance, the following expression will filter only 
those matching the specified text string:

``"<100" in str(COL("IC50_uM"))``

Statistics
==========

Statistics for each numeric column can be viewed in the spreadsheet window. The
display of statistics is controlled by toggling the "Show Statistics" option 
in the top level *Data* menu. Toggling this option controls the display of
statistics for just the currently viewed spreadsheet.

The following statistical information is computed for each numeric column:

* *min* - The minimum value of the column.
* *mean* - The maximum value of the column.
* *stddev* - The standard deviation of the column.
* *skewness* - The skewness of the column.
* *kurtosis* - The kurtosis of the column.

.. _figure_spreadsheet_statistics:

.. figure:: /_images/statistics.png
   :scale:  75
   :align:  center
   
   **Statistics**
   
   *Displaying statistical information on the associated spreadsheet*

The statistics display is a dynamic view of the spreadsheet data and therefore 
when data is altered in the spreadsheet the statistics view is automatically 
updated. For large data sets, this may take some time and could cause editing 
the spreadsheet to be cumbersome. To avoid this problem, it is best to hide 
the statistics display until the editing process is complete.

Formatting Columns
==================

There are a variety of different display styles for spreadsheet columns which
can be edited on an individual basis. The customizable styles include color, 
font, significant digits, and cell height. The style for individual columns
can be edited by selecting the "Format Columns..." option in the top level
*Data* menu. This will launch the dialog seen in 
:ref:`Figure: Column Formatting<figure_spreadsheet_column_format>`.

.. _figure_spreadsheet_column_format:

.. figure:: /_images/columnformat.png
   :scale:  75
   :align:  center
   
   **Column Formatting**
   
   *Many formatting options are available for each individual column*

On the left hand side of the dialog is a list of all the currently available
spreadsheet columns, including an *All* option. Any formatting changes 
made in this dialog will be applied to the selected columns in this list.

On the right hand side of the dialog is a collection of formatting and display
options. At the top is a drop down menu of available coloring schemes which 
include:

* Red to Blue
* Blue to Red
* Rainbow
* Rainbow Backwards
* Red Yellow Blue
* Grey to Green

The selected coloring scheme will be applied to the column using the scale 
specified beneath the drop down menu determined by the minimum and maximum
values. The default values are 0.0 and 1.0 respectively, but the current
minimum and maximum values for the selected column can be computed by clicking
on the "Compute" button to the right of the minimum and maximum fields.

The "Enable 'magic column' rendering" option allows specialized rendering of 
data, based on column names and cell contents.  With this option enabled,
data in any column with a name containing "(smiles)" will be interpreted as
SMILES strings, and displayed as chemical structures.  Data in any columns with
"(link)" in the name will be interpreted as URL's.  The name of the column,
minus the "(link)" string, will be displayed in each cell as an active 
hyperlink. URL's in columns without "(link)" in the column name will be 
displayed as raw hyperlinks. See
:ref:`Figure: "Magic Column Rendering"<figure_spreadsheet_magic_columns>`.

.. _figure_spreadsheet_magic_columns:

.. figure:: /_images/magiccolumns.png
   :scale:  75
   :align:  center
   
   **Magic Column Rendering**
   
   *With "magic column" rendering enabled, columns containing "(smiles)" or
   "(link)" in the column name will be displayed as chemical structures or
   hyperlinks, respectively.*

Common HTML tags can be rendered in spreadsheet cells, with the notable 
exception of image (<img>) tags, which will not work.

Advanced Depiction Options
==========================

The advanced depiction options described in the 
:ref:`2D Display<advanced_depiction>` chapter apply to 
structure depictions in the spreadsheet, as well as the 2D Display.  See
:ref:`Figure: "Template Highlighting"<figure_spreadsheet_highlight>` and
:ref:`Figure: "Atom Property Maps"<figure_spreadsheet_propmap>` for examples.

.. _figure_spreadsheet_highlight:

.. figure:: /_images/spreadsheet_highlight.png
   :scale: 75
   :align: center

   **Template Highlighting**

   *Spreadsheet depictions with template highlighting enabled*

.. _figure_spreadsheet_propmap:

.. figure:: /_images/spreadsheet_propmap.png
   :scale: 75
   :align: center

   **Atom Property Maps**

   *Spreadsheet depictions with Partial Charge property maps enabled*

Importing/Exporting
===================

Importing
---------

Spreadsheet data can be imported from external files in a variety of formats
including comma-separated values (.csv) and tab-delimited values (.txt). To 
import a file, select the "Spreadsheet..." option in the *Import* submenu
of the top level *File* menu. This will launch a dialog to assist in the
import process which can be seen in 
:ref:`Figure: Importing (1)<figure_spreadsheet_import1>`.

.. _figure_spreadsheet_import1:

.. figure:: /_images/spreadsheetimport1.png
   :scale:  75
   :align:  center
   
   **Importing (1)**
   
   *Specifying the delimiter type and other options*

At the top of the dialog are a number of options to specify the format of the
file to be imported and at the bottom is a quick preview of what |product| 
thinks the first five rows are. Note that in the figure only four rows are
displayed in the preview because the first row is being interpreted as the
header. The preview will update dynamically to match any changes made to the 
options at the top.

Once the preview of file to be imported is satisfactory, click on the *Next*
button to specify how the rows are to be matched to currently loaded molecules and
what to do with rows that do not match (see 
:ref:`Figure: Importing (2)<figure_spreadsheet_import2>`).

.. _figure_spreadsheet_import2:

.. figure:: /_images/spreadsheetimport2.png
   :scale:  75
   :align:  center
   
   **Importing (2)**
   
   *Specifying how to match the imported data*

There are a number of mechanisms available to match data rows to the 
appropriate molecules in |product|:

* List Order - matches the order of rows in the spreadsheet with the 
  order of molecules in the selected list.
* Name - matches the molecule's name with the name in the selected
  column of the imported data.
* SMILES - matches the molecule's canonical SMILES string
  with the SMILES string in the selected column of the 
  imported data.
* Values In - matches the value in the selected column between the
  imported data and the value already in the spreadsheet.
* Do Not Match - assume that you are importing new molecules 

Unmatched rows can also be imported into the spreadsheet by creating a new
molecule in |product| to be associated with that row. The following options are
available for unmatched rows:

* By SMILES - use the SMILES string in the selected column of the
  imported data to create a new molecule.
* Ignore - Do not import unmatched data.

Exporting
---------

Spreadsheets may be exported to an external file by selecting the 
"Spreadsheet..." option in the *Export* submenu of the top level *File* menu. 
Selecting this option will launch a dialog which allows for specification of 
which columns to export (see 
:ref:`Figure: Exporting<figure_spreadsheet_export>`). Supported formats include
comma separated (.csv), tab delimited (.txt), and Portable Document Format (.pdf).

.. _figure_spreadsheet_export:

.. figure:: /_images/spreadsheetexport.png
   :scale:  75
   :align:  center
   
   **Exporting**
   
   *Specifying which spreadsheet and columns to export*

Atom Spreadsheet
================

The *Atom* spreadsheet is a specialized spreadsheet provided by default that 
contains an entry for every atom in the *Active* molecule. A wide variety of atom 
properties can be displayed in the spreadsheet. Highlighting one or more rows 
in the spreadsheet will select the associated atoms in the 3D display. Atom 
visibility and marked status can also be controlled by toggling the state of 
the relevant columns.

Residue Spreadsheet
===================

The *Residue* spreadsheet is a specialized spreadsheet provided by default that
contains an entry for every residue in the *Active* molecule. Alternate residue
conformations (if present) can be controlled by clicking on the relevant columns 
in the spreadsheet. 

.. note::

  In order to perceive alternate conformations the **ALL** input flavor must be
  turned on for the PDB file format. This can be set in the Molecule I/O section
  of the :ref:`application preferences<preferences>`.


.. _user_dir:


.. |accente|        unicode:: U+00E9
	:trim:
.. |dotdoto|        unicode:: U+00F6
	:trim:
.. |degree|        unicode:: U+00B0
	:ltrim:


User Directory
==============

|product| stores user specific information in a user writable local directory
on the computer running the application. Contained in this directory are the
user's application settings (|settings_file|), preferences (*preferences.oeb*),
journal file (*journal.py*), and a cached copy of the license file 
(*oe_license.txt*). 

The location of the user directory is specific to the operating system, the 
details of which are listed below:

**Linux / Unix**

|linux_user_dir|
  
**macOS**

|osx_user_dir|

**Microsoft Windows 10**

|vista_user_dir|

The user directory can be accessed from within |product| by clicking on the
"Open User Directory" option within the *Help* menu.


####################################
OpenEye Glossary of Terms
####################################

.. for documentation of the glossary directive, see https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary

..  glossary::

    AMI
        An Amazon Machine Image (AMI) is a supported and maintained image provided by AWS that provides the information
        required to launch an instance.

    API
    APIs
        An Application Programming Interface (API) is a process that enables two software applications to communicate with
        each other to exchange data or functionality, using a set of protocols. It functions like an intermediary between
        two applications, much like a waiter is an intermediary between a customer and the restaurant kitchen.

    apo protein
    apo proteins
        An apo protein is just the structure of the protein with no ligand bound. "Apo" simply means the protein
        structure without any ligand and "Holo" stands for the protein-ligand complex.

    asymmetric unit
        The contents of a PDB or mmCIF file from an X-ray contain an
        asymmetric unit (ASU) as the output of the experiment. This is sometimes
        equivalent to the biological unit (BU), but often requires manipulation to create a correct BU.

    AUC
        The area under the curve (AUC) of :term:`ROC curve` is an aggregate measure of
        performance across all possible classification thresholds.
        The AUC value varies between :math:`[0.0 - 1.0]`.
        The model with perfect predictions has an AUC of 1.0 while a model that always gets
        the predictions wrong has an AUC value of 0.0.
        The value 0.5 represents random prediction.
        The AUC number can be interpreted as the probability that the model ranks a random
        positive example more highly than a random negative example. See also
        `Area under the curve <https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve>`_
        in Wikipedia and :term:`ROC curve`.

    B-factor
        B-factor (temperature factor) describes the displacement of the atomic
        positions from an average value.
        The more flexible an atom is the larger the displacement
        from the mean position will be (mean-squares displacement).
        The values of the B-factors are normally between 15 to 30 (sq. Ångströms),
        but can be much higher for more flexible regions.
        B-factors can indicate the mobility of atoms and they can also
        indicate where there are errors in model building.

    biological unit
        In short, the biological unit (BU) is an object that contains the biologically relevant parts of an
        ASU, which have not been split into various molecular components and are not yet prepped for modeling. For a more
        detailed explanation of BUs, refer to `Introduction to Biological Assemblies and the PDB Archive <https://pdb101.rcsb.org/learn/guide-to-understanding-pdb-data/biological-assemblies>`_ hosted at the RCSB.

    bug-fix release
        Toolkit and Applications bug-fix releases happen between feature releases, if necessary.
        These releases provide crucial bug fixes but no new features or platform
        updates.

    canonical SMILES
        In OpenEye documentation, the term canonical SMILES is used for a unique SMILES string
        that encodes the connection table of a molecule, but no chiral or
        isotopic information.
        Consequently, two stereoisomers always share the same canonical SMILES, since
        their stereo information are ignored during the canonicalization process.
        For generating a canonical SMILES, use the
        :ref:`OECreateCanSmiString <OECreateCanSmiString>` function. OpenEye's canonical
        SMILES term corresponds to *Daylight*'s  *unique* SMILES definition.

    canonical isomeric SMILES
        In OpenEye documentation, the name :term:`canonical isomeric SMILES` is used for a unique SMILES
        string that also encodes isotopic and stereo information.
        Due to the unambiguity of canonical isomeric SMILES, they can be used as a
        universal identifier for a specific chemical structure.
        For generating a canonical isomeric SMILES, use the
        :ref:`OECreateIsoSmiString <OECreateIsoSmiString>` or the **preferred** high-level
        :ref:`OEMolToSmiles <OEMolToSmiles>` function. OpenEye's canonical isomeric SMILES terminology corresponds to *Daylight*'s
        *absolute* SMILES definition.

    chiral atom
        In OpenEye terminology, an atom is considered chiral if it is connected to four different
        substituent groups, that is, its mirror image is not superimposable.In **OEChem TK**, an easily invertible nitrogen, that is,  a nonplanar nitrogen with one attached
        hydrogen, is not considered to be chiral. This is due to the fact that trivalent
        nitrogen compound undergo rapid inversion that interconvert enantiomers. See also the
        :term:`stereo atom` definition, the SetChiral and IsChiral methods of
        :ref:`OEAtomBase <OEChem_OEAtomBase>`, and the
        :ref:`Atom Chirality <section_stereochemistry_atom>` section.

    chiral bond
        In **OEChem TK**, a double bond is considered chiral if the cis and
        trans forms of this bond represent two distinct isomers.
        A chiral bond can be either a chain bond or a ring bond that does
        not belong to any ring smaller than 8-membered. See also the
        :term:`stereo atom` definition, the SetChiral and IsChiral methods of
        :ref:`OEAtomBase <OEChem_OEAtomBase>`, and the
        :ref:`Atom Chirality <section_stereochemistry_atom>` section.


    CIP
        The CIP (Cahn-Ingold-Prelog) system is rule-based method used in
        organic chemistry to name the stereoisomers of a molecule.
        The CIP system assigns an R or S descriptor to each stereocenter
        and an E or Z descriptor to each double bond so that the
        configuration of the entire molecule can be specified uniquely.

    conformer
    conformers
        Conformation isomers are commonly called conformers. Conformational isomers
        are stereoisomers that differ from one another by rotation around a single bond.
        Conformational isomers can be converted from one to another by rotations about formally single bonds
        without making or breaking any covalent bonds.

    CPK
        CPK (Corey,Pauling,Koltun) is a popular color convention for
        distinguishing atoms of different chemical elements in molecular
        models. See also the :ref:`chapter_element_color` chapter and the
        :ref:`OEAtomColorStyle <OEDepict_OEAtomColorStyle>` namespace.


    CSV
        Comma-separated-values file format.  See also the CSV standard
        at `RFC 4180 <http://tools.ietf.org/html/rfc4180>`_ and the
        :ref:`CSV File Format <section_moltaggeddata_CSV>` section.

    cube
    cubes
        Basic computational components used to construct a
        programmed workflow for execution in Orion.  Cubes communicate
        with one another via messages and transmit data using defined input and output ports.
        Cubes can be written
        in Python, from scratch, using OpenEye APIs. These APIs,
        as well as ready-made cubes for
        general computation tasks, are provided as part of the
        :ref:`Orion Platform package <orion-platform-intro>`.
        Ready-made cubes for scientific computations are available
        in the :ref:`OpenEye Snowball package <snowball-documentation-index>`.

    CUDA
        GPU-enabled calculation.
        CUDA mode involves preloading all fingerprints into GPU memory prior to performing
        similarity calculations. While this represents the fastest way to perform similarity
        searches once the fingerprints are loaded, searches are limited by GPU memory availability
        and will fall back to the :term:`memory-mapped` CPU mode if the entire set of fingerprints
        cannot be preloaded into the GPU memory.

    CXSMILES
        The Chemaxon Extended SMILES format which adds an additional (and optional) appendix to the SMILES string to encode
        a wide variety of additional features that are not part of the SMILES representation proper.
        Only the :term:`canonical SMILES` portion of the CXSMILES information is canonically ordered.   There
        is no specification in the CXSMILES format that any ordering of information within the
        appendix is either expected or required. However, a deterministic sort order is applied to the appendix
        entries to facilitate the potential use of the CXSMILES string for structure duplicate checking
        which would consider different groupings of enhanced stereo groups as structure differentiating. See also
        `CXSMILES documentation <https://docs.chemaxon.com/display/docs/chemaxon-extended-smiles-and-smarts-cxsmiles-and-cxsmarts.md>`_


    design unit
        The design unit (DU) is an object that contains the extracted and prepared parts of a
        single :term:`biological unit` (BU), ready for modeling. The parts include

            #.  protein;
            #.  ligand (not always: an
                apo DU will not contain a ligand);
            #.  site residues;
            #.  packing residues (if any exist near the site); and
            #.  excipients (if any exist near the site).

        One can interact with each part of the DU through APIs. The APIs are listed here :ref:`OEDesignUnit <OEBio_OEDesignUnit>`.

    dock
    docking
        Docking is a molecular modeling technique used to predict the optimal binding of a protein and a ligand. In the drug
        discovery process, structure-based methods such as docking—the lock-and-key concept where the protein is the lock
        and the ligand is the key—use the structure of a target protein to discover hits and optimize leads. Docking is used to identify
        possible active molecules in a large molecule database, by examining their shapes and chemical complementarity to
        the active site.

    excipient
        An  excipient is an inert substance that is formulated with an active drug to produce its
        pharmaceutical dosage form. Excipients serve various roles, such as long-term stabilization, aiding the manufacturing
        process, and enhancing the therapeutic properties of the active drug in its dosage form, such as facilitating
        drug absorption or enhancing solubility.

    FASTA
        In bioinformatics and biochemistry, the FASTA format is a text-based format
        for representing either nucleotide sequences or amino acid (protein) sequences,
        in which nucleotides or amino acids are represented using single-letter codes.


    feature release
        Toolkit and Application feature releases take place in spring and fall.
        These releases  provide support for new platforms and major and minor
        code fixes as well as new features.

    fingerprint
        Fingerprints do not use a predefined pattern dictionary; the encoded
        fragments are enumerated exhaustively.
        Since the number of possible patterns present in molecular structures
        is extremely large, it is impractical to assign a particular bit to
        each unique pattern, as in the case of the :term:`structural key` method.
        Instead, each pattern is subjected to a hashing function that
        logically ORs into the fingerprint.
        The use of hashing inherently results in overlap of some structural
        patterns.

    floe
    floes
        Programmed workflows for execution by the web-based Orion workflow engine.
        Many
        ready-made floes are developed and delivered by OpenEye, for
        execution in the Orion environment.  For documentation of
        ready-made floes and their use, see :ref:`the Orion Suites and Modules Guide <orion-floe-guide-index>`.
        Floes can be developed using
        Orion programming interfaces (APIs) and can use either ready-made
        cubes delivered with OpenEye software or cubes of your own, developed
        with the guidance of :ref:`the Orion Programming Guide <orion_documentation_python>`.

    GRASP
        GRASP is a molecular visualization and analysis program. It is
        particularly useful for the display and manipulation of the
        surfaces of molecules and their electrostatic properties.
        (online:fx.php/Software:GRASP)

    HELM
        The Hierarchical Editing Language for Macromolecules (HELM) notation, a text-based format
        for describing complex biomolecules like peptides, oligonucleotides, and their modifications,
        using simple monomers and operators.
        See also: [Zhang-2012]_

    InChI
        From `About the InChi Standard <http://www.inchi-trust.org/about-the-inchi-standard/>`_,
        Originally developed by the International Union of Pure and Applied Chemistry (IUPAC), the
        IUPAC International Chemical Identifier (:term:`InChI`) is a character string generated by computer algorithm.
        It is a tool to be used in software applications designed and developed by those who choose to use it.
        The InChI algorithm turns chemical structures into machine-readable strings of information.
        InChIs are unique to the compound they describe and can encode absolute stereochemistry making
        chemicals and chemistry machine-readable and discoverable.
        The :term:`InChI` format and algorithm are non-proprietary and the software is open source, with ongoing
        development done by the community. A number of IUPAC working groups is currently creating standard
        for those areas of chemistry that are not yet handled by the InChI algorithm.

    InChIKey
        From `About the InChi Standard <http://www.inchi-trust.org/about-the-inchi-standard/>`_,
        The :term:`InChIKey` has been designed so that Internet search engines can search and
        find the links to a given :term:`InChI`.
        To make the ``InChIKey`` the :term:`InChI` string is subjected to a compression algorithm to create a fixed-length
        string of upper-case characters. While the ``InChI`` to ``InChIKey`` hash compression is irreversible,
        there are a number of ``InChI`` resolvers available to look up an :term:`InChI` given an :term:`InChIKey`.

    in-memory
        The in-memory mode involves preloading all fingerprints into memory
        and performing the search in the memory.
        While this represents the fastest way to perform similarity searches once
        the fingerprints are loaded, searches are limited by memory availability.

    Iridium
        Iridium [Warren-2012] is a metric used to estimate the model
        quality of a structure resulting from an X-ray crystallography experiment.
        For more information about Iridium see :ref:`the discussion in the
        product documentation <chapter_sprucetk_iridium>`.

    JSON
        Sort for JavaScript Object Notation, this is a language-independent data format that works with most common languages, such as Python,
        Java, and others in the C-family of languages.

    LINGO
        LINGO is a very fast text-based molecular similarity search method.
        It is based on fragmentation of :term:`canonical isomeric SMILES` strings into overlapping
        substrings. See also :ref:`the discussion in the OEChem documentation <OEChem_OELingoSim>`.


    MACCS
        MACCS is a 166 bit-long :term:`structural key` descriptor in which each
        bit is associated with a specific structural pattern.

    marching cubes
        (online: `Marching cubes <http://en.wikipedia.org/wiki/Marching_cubes>`_)

    MDL
        MDL refers to the original "Molecular Design Limited Information Systems" company, which developed the :term:`MOL`
        format. Later, "Molecular Design Limited" was dropped in favor of the MDL acronym. For more
        information, see https://en.wikipedia.org/wiki/MDL_Information_Systems.

    memory-mapped
        The memory-mapped mode has no load time penalty or memory limitation, but the
        search itself takes more time.

    module
    modules
        In Python, *modules* are files with the file type ``.py``.  A Python module can, and
        usually does, define multiple Python classes, methods, and other objects. For more information,
        see the official Python documentation, such as https://docs.python.org/3/tutorial/modules.html.

    MOL
        A MOL type file uses a format originally defined by Molecular Design Limited
        that encodes information about the atoms, bonds, connectivity, and coordinates
        of a molecule, in plain text. For more information, see
        the `Wikipedia definition <https://en.wikipedia.org/wiki/Chemical_table_file#:~:text=Molfile,-ctab&text=An%20MDL%20Molfile%20is%20a,sections%20for%20more%20complex%20information.>`_


    Monte Carlo
        Monte Carlo simulations rely on repeated random sampling to model the probability of possible
        outcomes in a process that cannot easily be predicted. Thus it is used to estimate model uncertainty.
        In machine learning, Monte Carlo dropout refers to the process of randomly removing nodes from a neural network
        during training to regularize learning and avoid overfitting.


    nonterminal atom
        An atom is considered nonterminal if it is connected to two or more
        nonhydrogen atoms, that is, the method ``GetHvyDegree()`` of
        :ref:`OEAtomBase <OEChem_OEAtomBase>` returns
        a value greater than or equal to 2.

    OEB
        This is a binary OpenEye format used as a compact way to represent molecules with
        multiple :term:`conformers`.

    Orion back end
        The Orion back end is the set of programs and services that make up the
        "server" part of the client/server Orion product.

    Orion Platform
        The Orion Platform is the set of OpenEye-supported interfaces
        to the Orion back end.  Some interfaces are meant to be called by Python
        programs and some are command-line programs.

    package
    packages
        In Python, *packages* are sets of Python scripts (programs) organized in a directories
        that also includes an __init__.py script. The __init__.py script runs when the directory
        is opened; it may import  objects used by scripts in the package and perform
        other useful initial tasks for the packages' scripts.  Floe packages for
        use in Orion are specific examples of Python packages.

    popcount
        Popcount refers to the procedure of counting the number of 1s set in
        a bit string.  It is available as a hardware instruction on many modern
        processors and can be used, as an alternative to software-based counting
        methods, to speed up fingerprint operations.

    preliminary API
        APIs that are still under development might be delivered and marked as
        preliminary. Providing early access means that the APIs can be improved
        based on user feedback before committing to a final API design.
        Preliminary APIs will sometimes be made available for a limited set of
        platforms and languages, usually Python and C++.

    project
        In **Orion**, a project is a *container for data* related to the pursuit of an objective.
        A project serves as a location to store data and allows for efficient sharing and collaboration.
        Each project has its own :ref:`Project Summary <project-summary>` page.

    raster image
        Raster graphics represent images as an array of pixels or
        points of color.

    receptor
    receptors
        Receptors are a class of proteins that selectively bind to specific ligand molecules to change the behavior of a cell.
        This binding may activate or inactivate a receptor. A receptor is an integral part of a Design Unit and contains
        information about the location and characteristics of the binding pocket.

    ROC curve
        The receiver operating characteristic (ROC) curve is a two-dimensional graph
        in which the false positive rate is plotted on
        the X-axis and the true positive rate is plotted on the Y-axis.
        The ROC curves are useful to visualize and compare the performance of
        classifier methods. See also
        `Receiver operating characteristic (ROC) <http://en.wikipedia.org/wiki/Receiver_operating_characteristic>`_ in Wikipedia,
        `An introduction to ROC analysis <http://dx.doi.org/10.1016/j.patrec.2005.10.010>`_ by Tom Fawcett, and
        the definition of :term:`AUC`.

    rotatable bond
        In OpenEye documentation, a bond is considered rotatable only if it is a single nonring bond
        between two :term:`nonterminal <nonterminal atom>`, non-triple-bonded atoms.
        For example, the following structures have no rotatable bonds: ``CCC``, ``CC#CC``, and ``C1CCCCC1``.
        Note: Since the  "rotatable" property  depends on the 'in ring' property.
        the :ref:`OEFindRingAtomsAndBonds <OEFindRingAtomsAndBonds>` function must be called
        before accessing the :term:`rotatable bond` property via the
        ``IsRotor`` method of :ref:`OEQBondBase <OEQBondBase>`.

    script
    scripts
        Python programs are often called *scripts* because they are
        usually interpreted and not precompiled.  For most purposes, *script* and *program*
        are the same in Python, and this documentation may use either term to refer to
        a file of Python source code.

    SDF
        A Structural Data File (SDF) encodes information about chemical compounds
        in plain text. It is based on the :term:`MOL` format developed originally by Molecular
        Design Limited (MDL).  An SDF file can encode multiple molecules in a single
        file. The internet has considerable practical information
        on the format, such as https://lifechemicals.com/order-and-supply/how-to-work-with-sd-files.

    shard
        Shards are thin wrappers around files (not related to Orion Files). Each shard can store up to
        5 GB of arbitrary binary data as well as
        256 kB of user defined metadata in the form of `JSON <https://en.wikipedia.org/wiki/JSON>`_.

    SMARTS
        SMILES Arbitrary Target Specification (SMARTS)

        SMARTS is a language that allows specifying substructures by providing
        a number of primitive symbols describing atomic and bond properties.
        Atom and bond primitive specifications may be combined to form
        expressions by using logical operators.
        An introduction to SMARTS syntax is provided in :ref:`chapter_SMARTS`.
        For more information go to `the documentation of SMARTS on the Daylight Chemical Information Systems site <http://www.daylight.com/dayhtml/doc/theory/theory.smarts.html>`_

    SMILES
        Simplified Molecular Input Line Entry System (SMILES)

        A SMILES string represents a molecule by describing only its
        molecular graph (*i.e.* atoms and bonds in the connection table, but no chiral or
        isotopic information).
        There are usually a large number of valid SMILES which represent a
        given structure.
        For example, CCO, OCC and C(O)C all specify the structure of ethanol.
        For generating an arbitrary SMILES string, use the
        :ref:`OECreateAbsSmiString <OECreateAbsSmiString>` function.
        An introduction to SMILES syntax is provided in chapter :ref:`chapter_SMILES`.
        For more information go to `the documentation of SMILES on the Daylight Chemical Information Systems site <http://www.daylight.com/dayhtml/doc/theory/theory.smiles.html>`_

    SMIRKS
        SMILES Reaction Kernel Specification (SMIRKS)

        SMIRKS is a reaction transform language.
        A reaction considered valid according to the strict SMIRKS semantics if 1) all mapped product atoms have
        corresponding mapped reactant atoms,
        and 2) all atom maps must be pairwise (*i.e.*, every map class has exactly
        one reactant and one product atom)
        The strict semantics also requires that unmapped reactant atoms are
        destroyed in the reaction.
        The *strict* semantics means full compliance with SMIRKS defined by its originator, Daylight Inc.
        An introduction to SMIRKS syntax is provided in :ref:`chapter_reactions`.
        For more information go to `the documentation of SMIRKS on the Daylight Chemical Information Systems site <http://www.daylight.com/dayhtml/doc/theory/theory.smirks.html>`_
        Additional information on the semantics of SMIRKS language can be found at
        `SMIRKS Tutorial on the Daylight Chemical Information Systems site <http://www.daylight.com/dayhtml_tutorials/languages/smirks/index.html>`_.

    stable API
        Toolkits that have been fully developed, documented, and tested are
        considered stable.  The API definitions for these toolkits will be
        consistent across languages and platforms and will not change between
        toolkit releases.
        Code written with earlier versions of the toolkit will compile and
        run with newer versions. This allows users to easily upgrade
        to newer versions without worrying about breaking legacy code.


    stereo atom
        In **OEChem TK** the atom stereo information is stored as relative
        positions of neighboring atoms around a tetrahedral center.
        If an atom has specified stereochemistry, then the
        :ref:`HasStereoSpecified <OEChem_OEAtomBase_HasStereoSpecified>` method of
        :ref:`OEAtomBase <OEChem_OEAtomBase>` returns True.
        In **OEChem TK**, atom stereochemistry is internally represented by the two properties
        :term:`stereo atom` and :term:`chiral atom`.
        These properties are completely independent and allow
        **OEChem TK** to retain configuration information about atoms that are not
        chiral atoms, or to identify chiral atoms whose configuration is not
        specified. In the current version of **OEChem TK**, the only class of
        stereochemistry supported for atoms is
        :ref:`Tetrahedral <OEChem_OEAtomStereo>`, which corresponds
        to :math:`sp3` tetrahedral chirality. Valid return values for
        the :ref:`OEAtomStereo <OEChem_OEAtomStereo>` Tetrahedral stereochemistry
        class are ``Left`` and
        ``Right``.  See also the :term:`chiral atom` definition, the
        :ref:`OEBondBase <OEBondBase>` ``SetStereo`` method, the
        :ref:`OEBondBase <OEBondBase>` ``GetStereo`` method, the
        :ref:`OEBondBase <OEBondBase>` ``HasStereoSpecified`` method, and the
        :ref:`Bond Stereochemistry <section_stereochemistry_bond>` section

    stereo bond
        In **OEChem TK** the bond stereo information is stored as relative
        positions of neighboring atoms around a bond.
        If a bond has specified stereochemistry, then the
        :ref:`HasStereoSpecified <OEChem_OEAtomBase_HasStereoSpecified>` method
        of :ref:`OEAtomBase <OEChem_OEAtomBase>` returns
        True.
        In **OEChem TK**, atom stereochemistry is internally represented by the two properties
        :term:`stereo atom` and :term:`chiral atom`.
        These properties are completely independent and allow
        **OEChem TK** to retain configuration information about atoms that are not
        chiral atoms, or to identify chiral atoms whose configuration is not
        specified. In the current version of **OEChem TK**, the only class of
        stereochemistry supported for atoms is
        :ref:`Tetrahedral <OEChem_OEAtomStereo>`, which corresponds
        to :math:`sp3` tetrahedral chirality. Valid return values for
        the :ref:`OEAtomStereo <OEChem_OEAtomStereo>` Tetrahedral stereochemistry
        class are ``Left`` and
        ``Right``.  See also the :term:`chiral atom` definition, the
        :ref:`OEBondBase <OEBondBase>` ``SetStereo`` method, the
        :ref:`OEBondBase <OEBondBase>` ``GetStereo`` method, the
        :ref:`OEBondBase <OEBondBase>` ``HasStereoSpecified`` method, and the
        :ref:`Bond Stereochemistry <section_stereochemistry_bond>` section


    structural key
        A structural key is a fixed-length bitstring in which each bit is
        associated with a specific molecular pattern.
        When a structural key is generated for a molecule, the bitstring
        encodes whether or not these specific molecular patterns are
        present or absent in the molecule.
        The performance of such keys depends on the choice of the
        fragments used for constructing the keys and the probability of
        their presence in the searched molecule databases.


    SVG
        Scalable Vector Graphics (SVG) is a family of specifications of
        an XML-based file format for describing two-dimensional vector
        graphics.


    Tanimoto
        The Tanimoto coefficient (T) is a similarity measure for comparing chemical structures
        by means of molecular fingerprints. It is the ratio of the number of features common to both
        compounds to the total number of features. Two structures are generally considered similar
        if T > 0.85.


    vector image
        Vector graphics represent images using geometrical primitives
        such as points, lines, curves, and shapes or polygon(s), which
        are all based on mathematical equations.

    zwitterion
    zwitterionic
        A zwitterion contains an equal number of positively and negatively charged
        functional groups.  For more information, see `the Wikipedia definition <https://en.wikipedia.org/wiki/Zwitterion>`_.



.. global bibliography for applications, based on toolkits

.. _application-bibliography:

.. |accente|        unicode:: U+00E9
.. |accenta|          unicode:: U+00E0

.. only:: oehtml

   *************
   Bibliography
   *************

.. |JCOMPCHEM| replace:: *Journal of Computational Chemistry*

.. |BIOP|      replace:: *Biopolymers*

.. |JCHEMPHYS| replace:: *Journal of Chemical Physics*

.. |NAT|       replace:: *Nature*

.. |SCI|       replace:: *Science*

.. |BCHM|      replace:: *Biochemistry*

.. |PROT|      replace:: *Proteins*

.. |MLIQ|      replace:: *Molecular Liquids*

.. |ARBC|      replace:: *Annual Review of Biophysics & Biophysical Chemistry*

.. |JCC| replace:: *Journal of Computational Chemistry*

.. |CHEMREV| replace:: *Chemical Reviews*

.. |DRUGDISC| replace:: *Drug Discovery Today*

.. |JPS|      replace:: *Journal of Pharmaceutical Sciences*

.. |ADDR|     replace:: *Advanced Drug Delivery Reviews*

.. |DDT|      replace:: *Drug Discovery Today*

.. |CCHTS|    replace:: *Combinatorial Chemistry & High Throughput Screening*

.. |JAC|      replace:: *Journal of Applied Crystallography*

.. |JACS|     replace:: *Journal of the American Chemical Society*

.. |JCAMD|    replace:: *Journal of Computer-Aided Molecular Design*

.. |JCD|      replace:: *Journal of Chemical Documentation*

.. |JCICS|    replace:: *Journal of Chemical Information and Computer Science*

.. |JCIM|     replace:: *Journal of Chemical Information and Modeling*

.. |JMB|      replace:: *Journal of Molecular Biology*

.. |JMGM|     replace:: *Journal of Molecular Graphics and Modeling*

.. |JMC|      replace:: *Journal of Medicinal Chemistry*

.. |JPC|      replace:: *Journal of Physical Chemistry*

.. |JPCB|      replace:: *Journal of Physical Chemistry B*

.. |NAR|     replace:: *Nucleic Acids Research*

.. |PAC|      replace:: *Pure and Applied Chemistry*

.. |SCIENCE|  replace:: *Science*

.. |PNAS|     replace:: *Proceedings of the National Academy of Science, USA*

.. |PROTEINS| replace:: *Proteins*

.. |PROTSCI|  replace:: *Protein Science*

.. |BIOPOL|   replace:: *Biopolymers*

.. |ACTACRYST| replace:: *Acta Crystallographica Section A: Foundations and Advances*

.. |ACTDCRYST| replace:: *Acta Crystallographica Section D: Structural Biology*

.. |BIOPHYS| replace:: *Biophysical Journal*

.. [Baell-2010]
   | Baell, J.; Holloway, G.A.
   | New Substructure Filters for Removal of Pan Assay Interference Compounds (PAINS) from Screening Libraries and for Their Exclusion in Bioassays.
   | *J. Med. Chem.* **2010**, *53* (7), 2719–2740.
   | DOI: 10.1021/jm901137j

.. [Bento-2014]
   | Bento, A.P.; Gaulton, A.; Hersey, A.; Bellis, L.J.; Chambers, J.; Davies, M.; Krüger, F.A.; Light, Y.; Mak, L.; McGlinchey, S.; et al.
   | The ChEMBL Bioactivity Database: an Update.
   | *Nucleic Acids Res.* **2014**, *42* (D1), D1083–D1090.
   | DOI: 10.1093/nar/gkt1031

.. [Bertz-1981]
   | Bertz, S.H.
   | The First General Index of Molecular Complexity.
   | *J. Am. Chem. Soc.* **1981**, *103* (12), 3599–3601.
   | DOI: 10.1021/ja00402a071

.. [Bertz-1982]
   | Bertz, S.H.
   | Convergence, Molecular Complexity, and Synthetic Analysis.
   | *J. Am. Chem. Soc.* **1982**, *104* (21), 5801–5803.
   | DOI: 10.1021/ja00385a049

.. [Boda-2007]
   | Boda, K.; Seidel, T.; Gasteiger, J.
   | Structure and Reaction Based Evaluation of Synthetic Accessibility.
   | *J. Comput.-Aided Mol. Des.* **2007**, *21* (6), 311–325.
   | DOI: 10.1007/s10822-006-9099-2

.. [Boström-2001]
   | Boström, J.
   | Reproducing the Conformations of Protein-Bound Ligands: A Critical Evaluation of Several Popular Conformational Searching Tools.
   | *J. Comput.-Aided Mol. Des.* **2001**, *15* (12), 1137–1152.
   | DOI: 10.1023/a:1015930826903

.. [Boström-2003]
   | Boström, J.; Greenwood, J.R.; Gottfries, J.
   | Assessing the Performance of OMEGA with Respect to Retrieving Bioactive Conformations.
   | *J. Mol. Graphics Modell.* **2003**, *21* (5), 449–462.
   | DOI: 10.1016/s1093-3263(02)00204-8

.. [Brown-Muchmore-2008]
   | Brown, S.; Muchmore, S.W., Pharmaceutical Discovery Division, Abbott Laboratories, Abbott Park, IL.
   | Belief Curves for Tanimoto Combo and Electrostatic Tanimoto Combo.
   | *Personal Communication*, 2008.

.. [Cascarano-1991]
   | Cascarano, G.; Giacovazzo, C.; Camalli, M.; Spagna, R; Watkin, D.
   | Automatic Solution and Refinement of Crystal Structures by Means of the Package UNIQUE.
   | *Acta Crystallogr., Sect. A: Found. Crystallogr.* **1991**, *A47* (4), 373–381.
   | DOI: 10.1107/s010876739100096x

.. [Chen-2003]
   | Chen, X.; Wang, W.
   | The Use of Bioisosteric Groups in Lead Optimization.
   | In *Annu. Rep. Med. Chem.*, Vol. 38; Elsevier, Inc., 2003; pp. 333–346.
   | DOI: 10.1016/S0065-7743(03)38033-9

.. [Clark-1999]
   | Clark, D.E.
   | Rapid Calculation of Polar Molecular Surface Area and its Application to the Prediction of Transport Phenomena. 1. Prediction of Intestinal Absorption.
   | *J. Pharm. Sci.* **1999**, *88* (8), 807–814.
   | DOI: 10.1021/js9804011

.. [Coutsias-2016]
   | Coutsias, E.A.; Lexa, K.W.; Wester, M.J.; Pollock, S.N.; Jacobson, M.P.
   | Exhaustive Conformational Sampling of Complex Fused Ring Macrocycles Using Inverse Kinematics.
   | *J. Chem. Theory Comput.*, **2016**, *12* (9), 4674–4687.
   | DOI: 10.1021/acs.jctc.6b00250

.. [Crippen-1988]
   | Crippen, G.M.; Havel, T.F.
   | *Distance Geometry and Molecular Conformation*; Research Studies Press, 1988.

.. [Dallal-2001]
   | Dallal, G.E.
   | *The Little Handbook of Statistical Practice*; Kindle, 2012.
   | Amazon ID (ASIN): B00847SM6A.
   | (Originally cited as http://www.StatisticalPractice.com, accessed May 2011.)

.. [Diller-1999]
   | Diller, D.J.; Verlinde, C.L.M.J.
   | A Critical Evaluation of Several Global Optimization Algorithms for the Purpose of Molecular Docking.
   | *J. Comput. Chem.* **1999**, *20* (16), 1740–1751.
   | DOI: 10.1002/(sici)1096-987x(199912)20:16<1740::aid-jcc6>3.0.co;2-a

.. [DOCK]
   | *The Official UCSF DOCK Website*. http://dock.compbio.ucsf.edu/

.. [Durant-2002]
   | Durant, J.L.; Leland, B.A.; Henry, D.R.; Nourse, J.G.
   | Reoptimization of MDL Keys for Use in Drug Discovery.
   | *J. Chem. Inf. Comput. Sci.* **2002**, *42* (6), 1273–1280.
   | DOI: 10.1021/ci010132r

.. [Egan-2000]
   | Egan, W.J.; Merz, K.M.; Baldwin, J.J.
   | Prediction of Drug Absorption Using Multivariate Statistics.
   | *J. Med. Chem.* **2000**, *43* (21), 3867–3877.
   | DOI: 10.1021/jm000292e

.. [Eisenberg-1986]
   | Eisenberg, D.; McLachlan, A.D.
   | Solvation Energy in Protein Folding and Binding.
   | *Nature* **1986**, *319* (6050), 199–203.
   | DOI: 10.1038/319199a0

.. [Eldridge-1997]
   | Eldridge, M.D.; Murray, C.W.; Auton, T.R.; Paolini, G.V.; Mee, R.P.
   | Empirical Scoring Functions: I. The Development of a Fast Empirical Scoring Function to Estimate the Binding Affinity of Ligands in Receptor Complexes.
   | *J. Comput.-Aided Mol. Des.* **1997**, *11* (5), 425–445.
   | DOI: 10.1023/a:1007996124545

.. [Erickson-2004]
   | Erickson, J.A.; Jalaie, M.; Robertson, D.H.; Lewis, R.A.; Vieth, M.
   | Lessons in Molecular Recognition: The Effects of Ligand and Protein Flexibility on Molecular Docking Accuracy.
   | *J. Med. Chem.* **2004**, *47* (1), 45–55.
   | DOI: 10.1021/jm030209y

.. [Ertl-2000]
   | Ertl, P.; Rohde, B.; Selzer, P.
   | Fast Calculation of Molecular Polar Surface Area as a Sum of Fragment-Based Contributions and its Application to the Prediction of Drug Transport Properties.
   | *J. Med Chem.* **2000**, *43* (20), 3714–3717.
   | DOI: 10.1021/jm000942e

.. [Fletterick-1982]
   | Fletterick, R.J.; Matela, R.
   | Color-Coded ⍺-Carbon Models of Proteins.
   | *Biopolymers* **1982**, *21* (5), 999–1003.
   | DOI: https://doi.org/10.1002/bip.360210512

.. [Friedrich-2017]
   | Friedrich, N.-O.; Meyder, A.; de Bruyn Kops, C.; Sommer, K.; Flachsenberg, F.; Rarey, M.; Kirchmair, J.
   | High-Quality Dataset of Protein-Bound Ligand Conformations and Its Application to Benchmarking Conformer Ensemble Generators.
   | *J. Chem. Inf. Model.* **2017** *57*, (3), 529–539.
   | DOI: 10.1021/acs.jcim.6b00613

.. [Gamo-2010]
   | Gamo, F.-J.; Sanz, L.M.; Vidal, J.; de Cozar, C.; Alvarez, E.; Lavandera, J.-L.; Vanderwall, D.E.;
   | Green, D.V.S.; Kumar, V.; Hasan, S.; et al.
   | Thousands of Chemical Starting Points for Antimalarial Lead Identification.
   | *Nature* **2010**, *465* (7296), 305–310.
   | DOI: 10.1038/nature09107

.. [Grant-1995]
   | Grant, J.A.; Pickup,B.T.
   | A Gaussian Description of Molecular Shape.
   | *J. Phys.Chem.* **1995**, *99* (11), 3503–3510.
   | DOI: 10.1021/j100011a016

.. [Grant-1996]
   | Grant, J.A.; Gallardo, M.A.; Pickup, B.T.
   | A Fast Method of Molecular Shape Comparison. A Simple Application of a Gaussian Description of Molecular Shape.
   | *J. Comput. Chem.* **1996**, *17* (14), 1653–1666.
   | DOI: 10.1002/(SICI)1096-987X(19961115)17:14<1653::AID-JCC7>3.0.CO;2-K

.. [Grant-1997]
   | Grant, J.A.; Pickup, B.T.
   | Gaussian Shape Methods. In: *Computer Simulations of Biomolecular Systems,* Vol 3;
   | van Gunsteren, W.F., Weiner, P.K., Wilkinson, A.J., Eds.; Springer, 1997; pp. 150–176.
   | DOI: 10.1007/978-94-017-1120-3_5

.. [Grant-2001]
   | Grant, J.A.; Pickup, B.T.; Nicholls, A.
   | A Smooth Permittivity Function for Poisson–Boltzmann Solvation Methods.
   | *J. Comput. Chem.* **2001**, *22* (6), 608–640.
   | DOI: 10.1002/jcc.1032

.. [Grant-2007]
   | Grant, J.A.; Pickup, B.T.; Sykes, M.J.; Kitchen, C.A.; Nicholls, A.
   | A Simple Formula for Dielectric Polarization Energies: The Sheffield Solvation Model.
   | *Chem. Phys. Lett.* **2007**, *441* (1–3), 163–166.
   | DOI: 10.1016/j.cplett.2007.05.008

.. [GraphSim]
   | :ref:`GraphSim TK <GraphSim>` OpenEye, Cadence Molecular Sciences

.. [GRID]
   | *Molecular Discovery*. http://www.moldiscovery.com/soft_grid.php

.. [Guba-2016]
   | Guba, W.; Meyder, A.; Rarey, M.; Hert, J.
   | Torsion Library Reloaded: A New Version of Expert-Derived SMARTS Rules for Assessing Conformations of Small Molecules.
   | *J. Chem. Inf. Model.* **2016**, *56* (1), 1–5.
   | DOI: 10.1021/acs.jcim.5b00522

.. [Guillot-2002]
   | Guillot, B.
   | A Reappraisal of What We Have Learnt During Three Decades of Computer Simulations on Water.
   | *J. Mol. Liq.* **2002**, *101* (1–3), 219–260.
   | DOI: 10.1016/s0167-7322(02)00094-6

.. [Hajduk-2007]
   | Hajduk, P.J.; Greer, J.
   | A Decade of Fragment-Based Drug Design: Strategic Advances and Lessons Learned.
   | *Nat. Rev. Drug Discovery* **2007**, *6* (3), 211–219.
   | DOI: 10.1038/nrd2220

.. [Halgren-I-1996]
   | Halgren, T.A.
   | Merck Molecular Force Field. I. Basis, Form, Scope, Parameterization, and Performance of MMFF94.
   | *J. Comput. Chem.* **1996**, *17* (5–6), 490–519.
   | DOI: 10.1002/(SICI)1096-987X(199604)17:5/6<490::AID-JCC1>3.0.CO;2-P

.. [Halgren-II-1996]
   | Halgren, T.A.
   | Merck Molecular Force Field. II. MMFF94 van der Waals and Electrostatic Parameters for Intermolecular Interactions.
   | *J. Comput. Chem.* **1996**, *17* (5–6), 520–552.
   | DOI: 10.1002/(SICI)1096-987X(199604)17:5/6<520::AID-JCC2>3.0.CO;2-W

.. [Halgren-III-1996]
   | Halgren, T.A.
   | Merck Molecular Force Field: III. Molecular Geometries and Vibrational Frequencies for MMFF94.
   | *J. Comput. Chem.* **1996**, *17* (5–6), 553–586.
   | DOI: 10.1002/(SICI)1096-987X(199604)17:5/6<553::AID-JCC3>3.0.CO;2-T

.. [Halgren-IV-1996]
   | Halgren, T.A.; Nachbar, R.B.
   | Merck Molecular Force Field. IV. Conformational Energies and Geometries for MMFF94.
   | *J. Comput. Chem.* **1996**, *17* (5–6), 587–615.
   | DOI: 10.1002/(SICI)1096-987X(199604)17:5/6<587::AID-JCC4>3.0.CO;2-Q

.. [Halgren-V-1996]
   | Halgren, T.A.
   | Merck Molecular Force Field. V. Extension of MMFF94 using Experimental Data, Additional Computational Data, and Empirical Rules.
   | *J. Comput. Chem.* **1996**, *17* (5–6), 616–641.
   | DOI: 10.1002/(SICI)1096-987X(199604)17:5/6<616::AID-JCC5>3.0.CO;2-X

.. [Halgren-VI-1999]
   | Halgren, T.A.
   | MMFF VI. MMFF94s Option for Energy Minimization Studies.
   | *J. Comput. Chem.* **1999**, *20* (7), 720–729.
   | DOI: 10.1002/(SICI)1096-987X(199905)20:7<720::AID-JCC7>3.0.CO;2-X

.. [Halgren-VII-1999]
   | Halgren, T.A.
   | MMFF VII. Characterization of MMFF94, MMFF94s, and Other Widely Available Force Fields for Conformational Energies and for Intermolecular-Interaction Energies and Geometries.
   | *J. Comput. Chem.* **1999**, *20* (7), 730–748.
   | DOI: 10.1002/(SICI)1096-987X(199905)20:7<730::AID-JCC8>3.0.CO;2-T

.. [Hanley-1982]
   | Hanley, J.A.; McNeil, B.J.
   | The Meaning and Use of the Area Under a Receiver Operating Characteristic (ROC) Curve.
   | *Radiology* **1982**, *143* (1), 29–36.
   | DOI: 10.1148/radiology.143.1.7063747

.. [Hare-2004]
   | Hare, B.J.; Walters, W.P.; Caron, P.R.; Bemis, G.W.
   | CORES: An Automated Method for Generating Three-Dimensional Models of Protein/Ligand Complexes.
   | *J. Med. Chem.* **2004**, *47* (19), 4731–4740.
   | DOI: 10.1021/jm0499054

.. [Hawkins-2010]
   | Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T.
   | Conformer Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the Protein Databank and Cambridge Structural Database.
   | *J. Chem. Inf. Model.* **2010**, *50* (4), 572–584.
   | DOI: 10.1021/ci100031x

.. [Hawkins-2012]
   | Hawkins, P.C.D; Nicholls, A.
   | Conformer Generation with OMEGA: Learning from the Data Set and the Analysis of Failures.
   | *J. Chem. Inf. Model.* **2012**, *52*, (11), 2919–2936.
   | DOI: 10.1021/ci300314k

.. [Hawkins-2020]
   | Hawkins, P.C.D.; Wlodek, S.J.
   | Decisions With Confidence: Application to the Conformation Sampling of Molecules in the Solid State.
   | *J. Chem. Inf. Model.* **2020**, *60* (7), 3518–3533.
   | DOI: 10.1021/acs.jcim.0c00358

.. [Hermann-1972]
   | Hermann, R.B.
   | Theory of Hydrophobic Bonding. II. Correlation of Hydrocarbon Solubility in Water With Solvent Cavity Surface Area.
   | *J. Phys. Chem.* **1972**, *76* (19), 2754–2759.
   | DOI: 10.1021/j100663a023

.. [Huang-2003]
   | Huang, X.; Margulis, C.J.; Berne, B.J.
   | Dewetting-Induced Collapse of Hydrophobic Particles.
   | *Proc. Natl. Acad. Sci. U. S. A.*  **2003**, *100* (21), 11953–11958.
   | DOI: 10.1073/pnas.1934837100

.. [Huang-2006]
   | Huang, N.; Shoichet, B.K.; Irwin, J.J.
   | Benchmarking Sets for Molecular Docking.
   | *J. Med. Chem.* **2006**, *49* (23), 6789–6801.
   | DOI: 10.1021/jm0608356

.. [Jain-2008]
   | Jain, A.N.; Nicholls, A.
   | Recommendations for Evaluation of Computational Methods.
   | *J. Comput-Aided Mol. Des.* **2008**, *22* (3–4), 133–139.
   | DOI: 10.1007/s10822-008-9196-5

.. [Jakalian-2000]
   | Jakalian, A.; Bush, B.L.; Jack, D.B.; Bayly, C.I.
   | Fast, Efficient Generation of High-Quality Atomic Charges. AM1-BCC Model: I: Method.
   | *J. Comput. Chem.* **2000**, *21* (2), 132–146.
   | DOI: 10.1002/(sici)1096-987x(20000130)21:2%3C132::aid-jcc5%3E3.0.co;2-p

.. [Jakalian-2002]
   | Jakalian, A.; Jack, D.B.; Bayly, C.I.
   | Fast, Efficient Generation of High-Quality Atomic Charges. AM1-BCC Model: II. Parameterization and Validation.
   | *J. Comput. Chem.* **2002**, *23* (16), 1623–1641.
   | DOI: 10.1002/jcc.10128

.. [Jeffrey-1997]
   | Jeffrey, G.A.
   | *An Introduction to Hydrogen Bonding*;
   | Oxford University Press, 1997.
   | ISBN: 0195095499, 9780195095494

.. [Jones-1991]
   | Jones, T.A.; Zou, J.-Y.; Cowan, S.W.; Kjeldgaard, M.
   | Improved Methods for Building Protein Models in Electron Density Maps and the Location of Errors in these Models.
   | *Acta Crystallogr., Sect. A: Found. Crystallogr.* **1991**, *A47* (2), 110–119.
   | DOI: 10.1107/s0108767390010224

.. [Kleywegt-2004]
   | Kleywegt, G.J.; Harris, M.R.; Zou, J.-Y.; Taylor, T.C.; Wählby, A.; Jones, T.A.
   | The Uppsala Electron-Density Server.
   | *Acta Crystallogr., Sect. D: Biol. Crystallogr.* **2004**, *D60* (12), 2240–2249.
   | DOI: 10.1107/s0907444904013253

.. [Koch-1974]
   | Koch, M.H.
   | On the Application of Phase Relationships to Complex Structures. VI. Automatic Interpretation of Electron-Density Maps for Organic Structures.
   | *Acta Crystallogr., Sect. A: Cryst. Phys., Diffr., Theor. Gen. Crystallogr.* **1974**, *A30* (1), 67–70.
   | DOI: 10.1107/s0567739474000118

.. [Labute-2010]
   | Labute, P.
   | LowModeMD—Implicit Low-Mode Velocity Filtering Applied to Conformational Search of Macrocycles and Protein Loops.
   | *J. Chem. Inf. Model.* **2010**, *50* (5), 792–800.
   | DOI: 10.1021/ci900508k

.. [Lauri-1994]
   | Lauri, G.; Bartlett, P.A.
   | CAVEAT: A Program to Facilitate the Design of Organic Molecules.
   | *J. Comput.-Aided Mol. Des.* **1994** *8* (1), 51–66.
   | DOI: 10.1007/bf00124349

.. [Lewell-1998]
   | Lewell, X.Q.; Judd, D.B.; Watson, S,P; Hann, M.M.
   | RECAP—Retrosynthetic Combinatorial Analysis Procedure: A Powerful New Technique for Identifying Privileged Molecular Fragments With Useful Applications in Combinatorial Chemistry.
   | *J. Chem. Inf. Comput. Sci.* **1998**, *38* (3), 511–522.
   | DOI: 10.1021/ci970429i

.. [Lipinski-1997]
   | Lipinski, C.A.; Lombardo, F.; Dominy, B.W; Feeney, P.J.
   | Experimental and Computational Approaches to Estimate Solubility and Permeability in Drug Discovery and Development Settings.
   | *Adv. Drug Delivery Rev.* **1997**, *23* (1–3), 3–25.
   | DOI: 10.1016/s0169-409x(96)00423-1

.. [Lovering-2009]
   | Lovering, F.; Bikker, J.; Humblet, C.
   | Escape from Flatland: Increasing Saturation as an Approach to Improving Clinical Success.
   | *J. Med. Chem.* **2009**, *52* (21), 6752–6756.
   | DOI: 10.1021/jm901241e

.. [Martin-2005]
   | Martin, Y.C.
   | A Bioavailability Score.
   | *J. Med. Chem.* **2005**, *48* (9), 3164–3170.
   | DOI: 10.1021/jm0492002

.. [Masek-1993]
   | Masek, B.B.; Merchant, A.; Matthew, J.B.
   | Molecular Shape Comparison of Angiotensin II Receptor Antagonists.
   | *J. Med. Chem.* **1993**, *36* (9), 1230–1238.
   | DOI: 10.1021/jm00061a014

.. [Mayne-1998]
   | Mayne, L.; Englander, S.W.; Qiu, R.; Yang, J.; Gong, Y.; Spek, E.J.; Kallenbach, N.R.
   | Stabilizing Effect of a Multiple Salt Bridge in a Prenucleated Peptide.
   | *J. Am. Chem. Soc.* **1998**, *120* (41), 10643–10645.
   | DOI: 10.1021/ja981592c

.. [McGann-2003]
   | McGann, M.; Almond, H.R.; Nicholls, A.; Grant, J.A.; Brown, F.K.
   | Gaussian Docking Functions.
   | *Biopolymers* **2003**, *68* (1), 76–90.
   | DOI: 10.1002/bip.10207

.. [McGovern-2003]
   | McGovern, S.L.; Helfand, B.T.; Feng, B.; Shoichet, B.K.
   | A Specific Mechanism of Nonspecific Inhibition.
   | *J. Med. Chem.* **2003**, *46* (20), 4265–4272.
   | DOI: 10.1021/jm030266r

.. [McQuarrie-1976]
   | McQuarrie, D.A.
   | *Statistical Mechanics*;
   | Harper & Row, 1976.

.. [Menéndez-Velázquez-2003]
   | Menéndez-Velázquez, A.; García-Granda, S.
   | A Procedure Towards the Automatic Solution of Crystal Structures by Means of Topological Analysis of Fourier Maps.
   | *J. Appl. Crystallogr.* **2003**, *36* (2), 193–205.
   | DOI: 10.1107/s0021889802022100

.. [Mills-Dean-1996]
   | Mills, J.E.J.; Dean, P.M.
   | Three-Dimensional Hydrogen-Bond Geometry and Probability Information from a Crystal Survey.
   | *J. Comput.-Aided Mol. Des.* **1996**, *10* (6), 607–622.
   | DOI: 10.1007/bf00134183

.. [Mobley-2018]
   | Mobley, D.L.; Bannan, C.C.; Rizzi, A.; Bayly, C.I.; Chodera, J.D.; Lim, V.T.; Lim, N.M.; Beauchamp, K.A.; Slochower, D.R.; Shirts, M.R.; et al.
   | Escaping Atom Types in Force Fields Using Direct Chemical Perception.
   | *J. Chem. Theory Comput.* **2018**, *14* (11), 6076–6092.
   | DOI: 10.1021/acs.jctc.8b00640

.. [Muchmore-2008]
   | Muchmore, S.W.; Debe, D.A.; Metz, J.T.; Brown, S.P.; Martin, Y.C.; Hajduk, P.J.
   | Application of Belief Theory to Similarity Data Fusion for Use in Analog Searching and Lead Hopping.
   | *J. Chem.Inf. Model.* **2008**, *48* (5), 941–948.
   | DOI: 10.1021/ci7004498

.. [Nicholls-1991]
   | Nicholls, A.; Sharp, K.A.; Honig, B.
   | Protein Folding and Association: Insights from the Interfacial and Thermodynamic Properties of Hydrocarbons.
   | *Proteins: Struct., Funct., Bioinf.* **1991**, *11*, (4), 281–96.
   | DOI: 10.1002/prot.340110407

.. [Nicholls-2008]
   | Nicholls,A.; Mobley, D.L.; Guthrie, J.P.; Chodera, J.D.; Bayly, C.I.; Cooper, M.D.; Pande, V.S.
   | Predicting Small-Molecule Solvation Free Energies: An Informal Blind Test for Computational Chemistry.
   | *J. Med. Chem.* **2008**, *51* (4), 769–779.
   | DOI: 10.1021/jm070549+

.. [Nicholls-2009]
   | Nicholls, A.; Wlodek, S.; Grant, J.A.
   | The SAMP1 Solvation Challenge: Further Lessons Regarding the Pitfalls of Parametrization.
   | *J. Phys. Chem. B* **2009**, *113* (14), 4521–4532.
   | DOI: 10.1021/jp806855q

.. [Nicholls-2010]
   | Nicholls, A.; Wlodek S.; Grant, J.A.
   | SAMPL2 and Continuum Modeling.
   | *J. Comput.-Aided Mol. Des.* **2010**, *24* (4), 293–306.
   | DOI: 10.1007/s10822-010-9334-8

.. [Oldfield-2001]
   | Oldfield, T.J.
   | Creating Structure Features by Data Mining the PDB to Use as Molecular-Replacement Models.
   | *Acta Crystallogr., Sect. D: Biol. Crystallogr.* **2001**, *D57* (10), 1421–1427.
   | DOI: 10.1107/s0907444901012483

.. [Oprea-2000]
   | Oprea, T.
   | Property Distribution of Drug-Related Chemical Databases.
   | *J. Comput.-Aided Mol. Des.* **2000**, *14* (3), 251–264.
   | DOI: 10.1023/a:1008130001697

.. [Otter-1989]
   | Otter, A.; Scott, P.G.; Liu, X.H.; Kotovych, G.
   | A :sup:`1`\ H and :sup:`13`\ C NMR Study on the Role of Salt-Bridges in the Formation of a Type I ß-Turn in N-Acetyl-L-Asp-L-Glu-L-Lys-L-Ser-NH\ :sub:`2`.
   | *J. Biomol. Struct. Dyn.* **1989**, *7* (3), 455–476.
   | DOI: 10.1080/07391102.1989.10508504

.. [Perola-2004]
   | Perola, E.; Charifson, P.S.
   | Conformational Analysis of Drug-Like Molecules Bound to Proteins: an Extensive Study of Ligand Reorganization upon Binding.
   | *J. Med. Chem.* **2004**, *47* (10), 2499–2510.
   | DOI: 10.1021/jm030563w

.. [PDB-IDs]
   | *RCSB Protein Databank*. https://www.rcsb.org/ (accessed May 2011)
   | *Trypsin inhibitors*:
   | **PDB ID: 1C2D** Citation: Katz, B.A., Luong, C. Recruiting Zinc to Mediate Potent, Specific Inhibition of Serine Proteases (1999) doi 10.2210/pdb1C2D/pdb
   | **PDB ID: 1C5T** Citation: Katz, B.A., Mackman, R., Luong, C., Radika, K., Martelli, A., Sprengeler, P.A., Wang, J., Chan, H., Wong, L. Structural Basis for Selectivity of a Small Molecule, S1-Binding, Sub-Micromolar Inhibitor of Urokinase Type Plasminogen Activator (1999) doi 10.2210/pdb1C5T/pdb
   | **PDB ID: 1F0T** Citation: Maignan, S., Guilloteau, J.P., Pouzieux, S., Choi-Sledeski, Y.M., Becker, M.R., Klein, S.I., Ewing, W.R., Pauls, H.W., Spada, A.P., Mikol, V. Bovine Trypsin Complexed with RPR131247 (2000) doi 10.2210/pdb1F0T/pdb
   | **PDB ID: 1G3D** Citation: Toyota, E., Ng, K.K.S., Sekizaki, H., Itoh, K., Tanizawa, K., James, M.N.G. Bovine Beta-Trypsin Bound to Meta-Amidino Schiff Base Copper (II) Chelate (2000) doi 10.2210/pdb1G3D/pdb
   | **PDB ID: 1G3E** Citation: Toyota, E., Ng, K.K.S., Sekizaki, H., Itoh, K., Tanizawa, K., James, M.N.G. Bovine Beta-Trypsin Bound to Para-Amidino Schiff Base Copper (II) Chelate (2000) doi 10.2210/pdb1G3E/pdb
   | **PDB ID: 1GHZ** Citation: Katz, B.A., Elrod, K., Luong, C., Rice, M., Mackman, R.L., Sprengeler, P.A., Spencer, J., Hatayte, J., Janc, J., Link, J., Litvak, J., Rai, R., Rice, K., Sideris, S., Verner, E., Young, W. A Novel Serine Protease Inhibition Motif Involving a Multi-Centered Short Hydrogen Bonding Network at the Active Site (2001) doi 10.2210/pdb1GHZ/pdb
   | **PDB ID: 1GJ6** Citation: Katz, B.A., Sprengeler, P.A., Luong, C., Verner, E., Spencer, J.R., Breitenbucher, J.G., Hui, H., McGee, D., Allen, D., Martelli, A., Mackman, R.L. Engineering Inhibitors Highly Selective for the S1 Sites of SER190 Trypsin-Like Serine Protease Drug Targets (2001) doi 10.2210/pdb1GJ6/pdb
   | **PDB ID: 1H4W** Citation: Katona, G., Berglund, G.I., Hajdu, J., Graf, L., Szilagyi, L. Structure of human trypsin IV (brain trypsin) (2001) doi 10.2210/pdb1H4W/pdb
   | **PDB ID: 1J17** Citation: Stubbs, M.T. Factor XA Specific Inhibitor in Complex with Rat Trypsin Mutant X99/175/190RT (2002) doi 10.2210/pdb1J17/pdb
   | **PDB ID: 1K1I** Citation: Stubbs, M.T. Bovine Trypsin-Inhibitor Complex (2001) doi 10.2210/pdb1K1I/pdb
   | **PDB ID: 1K1L** Citation: Stubbs, M.T. Bovine Trypsin-Inhibitor Complex (2001) doi 10.2210/pdb1K1L/pdb
   | **PDB ID: 1K1N** Citation: Stubbs, M.T. Bovine Trypsin-Inhibitor Complex (2001) doi 10.2210/pdb1K1N/pdb
   | **PDB ID: 1PPC** Citation: Bode, W., Turk, D. Geometry of Binding of the Benzamidine-and Arginine-Based Inhibitors N-alpha-(2-naphthyl-sulphonyl-glycyl)-DL-P-amidinophenylalanyl-oiperidine (NAPAP) and (2R,4R)-4-methy-1-[N-alpha-(3-methyl-1,2,3,4-tetrahydro-8-quinolinesulphonyl)-L-arginyl]-2-piperidine Carboxylic Acid (MQPA) to Human Alpha-Thrombin: X-Ray Crystallographic Determination of the NAPAP-Trypsin Complex and Modeling of NAPAP-Thrombin AND MQPA-Thrombin (1991) doi 10.2210/pdb1PPC/pdb
   | **PDB ID: 1QB1** Citation: Whitlow, M. Bovine Trypsin with 1-[2-[5-[amino(imino)methyl]-2-hydroxyphenoxy]-6-[3-(4,5-dihydro-1-methyl-1H-imidazol-2-yl)phenoxy]pyridin-4-yl]piperidine-3-carboxylic Acid (ZK-806974) (1999) doi 10.2210/pdb1QB1/pdb
   | **PDB ID: 1QB6** Citation: Whitlow, M. Bovine Trypsin 3,3'-[3,5-difluoro-4-methyl-2, 6-pyridinediylbis(oxy)]bis(benzenecarboximidamide) (ZK-805623) Complex (1999) doi 10.2210/pdb1QB6/pdb
   | **PDB ID: 1QB9** Citation: Whitlow, M. Bovine Trypsin 7-[[2-[[1-(1-iminoethyl)piperidin-4-YL]oxy]-9H-carbozol-9-YL] methyl]naphthalene-2-carboximidamid (ZK-806450) Complex (1999) doi 10.2210/pdb1QB9/pdb
   | **PDB ID: 1QBN** Citation: Whitlow, M. Bovine Trypsin 2-[amino(imino)methyl]-2-hydroxyphenoxy]-6-[3-(4,5-dihydro-1H-imidazol-2-yl)phenoxy]pyridine-4-carboxylic Acid (ZK-806688) Complex (1999) doi 10.2210/pdb1QBN/pdb
   | **PDB ID: 1QBO** Citation: Whitlow, M. Bovine Trypsin 7-[[6-[[1-(1-iminoethyl)piperidin-4-YL]oxy]-2-methyl-benzimidazol-1-YL]methyl]naphthalene-2-carboximidamid ZK-806711 Inhibitor Complex (1999) doi 10.2210/pdb1QBO/pdb
   | **PDB ID: 1TNI** Citation: Kurinov, I., Harrison, R.W. Prediction of Novel Serine Protease Inhibitors (1994) doi 10.2210/pdb1TNI/pdb
   | *Estrogen antagonist receptor*:
   | **PDB ID: 3ERT** Citation: Shiau, A.K., Barstad, D., Loria, P.M., Cheng, L., Kushner, P.J., Agard, D.A., Greene, G.L. Human Estrogen Receptor Alpha Ligand-Binding Domain in Complex with 4-Hydroxytamoxifen. (1999) doi 10.2210/pdb3ERT/pdb

.. [Pierotti-1976]
   | Pierotti, R.A.
   | A Scaled Particle Theory of Aqueous and Nonaqueous Solutions.
   | *Chem. Rev* **1976**, *76* (6), 717–726.
   | DOI: 10.1021/cr60304a002

.. [Reid-2014]
   | Reid, R.; Yau, M.; Singh, R.; Hamidon, J.; Lim, J.; Stoermer, M.; Fairlie, D.
   | Potent Heterocyclic Ligands for Human Complement C3a Receptor.
   | *J. Med. Chem.* **2014**, *57* (20), 8459–8470.
   | DOI: 10.1021/jm500956p

.. [Rizzo-2006]
   | Rizzo, R.C.; Aynechi, T.; Case, D.A.; Kuntz, I.D.
   | Estimation of Absolute Free Energies of Hydration Using Continuum Methods: Accuracy of Partial Charge Models and Optimization of Nonpolar Contributions.
   | *J. Chem. Theory Comput.* **2006**, *2* (1), 128–139.
   | DOI: 10.1021/ct050097l

.. [Rossi-2007]
   | Rossi, K.A.; Weigelt, C.A.; Nayeem, A.; Krystek, S.R., Jr.
   | Loopholes and Missing Links in Protein Modeling.
   | *Protein Sci.* **2007**, *16* (9), 1999–2012.
   | DOI: 10.1110/ps.072887807

.. [Seidler-2003]
   | Seidler, J.; McGovern, S.L.; Doman, T.N.; Shoichet, B.K.
   | Identification and Prediction of Promiscuous Aggregating Inhibitors among Known Drugs.
   | *J. Med. Chem.* **2003**, *46* (21), 4477–4486.
   | DOI: 10.1021/jm030191r

.. [Shannon-1949]
   | Shannon, C.E.; Weaver, W.
   | *The Mathematical Theory of Communication*; University of Illinois Press, 1949.
   | ISBN 0252725484

.. [Sharp-1991a]
   | Sharp, K.A.; Nicholls, A.; Friedman, R.; Honig, B.
   | Extracting Hydrophobic Free Energies from Experimental Data: Relationship to Protein Folding and Theoretical Models.
   | *Biochemistry* **1991**, *30* (40), 9686–9697.
   | DOI: 10.1021/bi00104a017

.. [Sharp-1991b]
   | Sharp, K.A.; Nicholls, A.; Fine, R.F.; Honig, B.
   | Reconciling the Magnitude of the Microscopic and Macroscopic Hydrophobic Effects.
   | *Science* **1991**, *252* (5002), 106–109.
   | DOI: 10.1126/science.2011744

.. [Sheridan-2002]
   | Sheridan, R.P.
   | The Most Common Chemical Replacements in Drug-Like Compounds.
   | *J. Chem. Inf. Comput. Sci.* **2002**, *42* (1), 103–108.
   | DOI: 10.1021/ci0100806

.. [Spellmeyer-1997]
   | Spellmeyer, D.C.; Wong, A.K.; Bower, M.J.; Blaney, J.M.
   | Conformational Analysis using Distance Geometry Methods.
   | *J. Mol. Graphics Modell.* **1997**, *15* (1), 18–36.
   | DOI: 10.1016/s1093-3263(97)00014-4

.. [Sykes-2008]
   | Sykes, M.J.; McKinnon, R.A.; Miners, J.O.
   | Prediction of Metabolism by Cytochrome P450 2C9: Alignment and Docking Studies of a Validated Database of Substrates.
   | *J. Med. Chem.* **2008**, *51* (4), 780–791.
   | DOI: 10.1021/jm7009793

.. [Tolman-1949]
   | Tolman, R.C.
   | The Effect of Droplet Size on Surface Tension.
   | *J. Chem. Phys.* **1949**, *17* (3), 333–337.
   | DOI: 10.1063/1.1747247

.. [Truchon-2009]
   | Truchon, J.-F.; Nicholls, A.; Grant, J.A.; Iftimie, R.I.; Roux B.; Bayly, C.I.
   | Using Electronic Polarization from the Internal Continuum (EPIC) for Intermolecular Interactions.
   | *J. Comput. Chem.* **2009**, *31* (4), 811–824.
   | DOI: 10.1002/jcc.21369

.. [Tu-2012]
   | Tu, M.; Rai, B.; Mathiowetz, A.; Didiuk, M.; Pfefferkorn, J.; Guzman-Perez, A.; Benbow, J.; Guimarães, C.; Mente, S.; Hayward, M.; Liras, S.
   | Exploring Aromatic Chemical Space with NEAT: Novel and Electronically Equivalent Aromatic Template.
   | *J. Chem. Inf. Model.* **2012**, *52* (5), 1114–1123.
   | DOI: 10.1021/ci300031s

.. [Tuccinardi-2010]
   | Tuccinardi, T.; Botta, M.; Giordano, A.; Martinelli, A.
   | Protein Kinases: Docking and Homology Modeling Reliability.
   | *J. Chem. Inf. Model.* **2010**, *50* (8), 1432–1441.
   | DOI: 10.1021/ci100161z

.. [Ujváry-2003]
   | Ujváry, I.; Györffy, W; Lopata, A.
   | Fragment-Based Drug Design using Stereoisomers. A Case Study of Analogues of the Phenol Group in the Bioster Database.
   | *Acta Pharm. Hung.* **2003**, *73* (3), 163–169.
   | PMID: 15112439

.. [Vagin-2004]
   | Vagin, A.A.; Steiner, R.A.; Lebedev, A.A.; Potterton, L.; McNicholas, S.; Long, F.; Murshudov, G.N.
   | REFMAC5 Dictionary: Organization of Prior Chemical Knowledge and Guidelines for its Use.
   | *Acta Crystallogr., Sect. D: Biol. Crystallogr.* **2004**, *D60* (12), 2184–2195.
   | DOI: 10.1107/s0907444904023510

.. [Veber-2002]
   | Veber, D.F.; Johnson, S.R.; Cheng, H.-Y.; Smith, B.R.; Ward, K.W.; Kopple, K.D.
   | Molecular Properties that Influence the Oral Bioavailability of Drug Candidates.
   | *J. Med. Chem.* **2002**, *45* (12), 2615–2623.
   | DOI: 10.1021/jm020017n

.. [Verkhivker-2000]
   | Verkhivker, G.M.; Bouzida, D.; Gehlhaar, D.K.; Rejto, P.A.; Arthurs, S.; Colson, A.B.; Freer, S.T.; Larson, V.; Luty, B.A.; Marrone, T.; et al.
   | Deciphering Common Failures in Molecular Docking of Ligand-Protein Complexes.
   | *J. Comput.-Aided Mol. Des.* **2000**, *14* (8), 731–751.
   | DOI: 10.1023/a:1008158231558

.. [Verloop-1987]
   | Verloop, A.
   | The STERIMOL Approach to Drug Design, Marcel Dekker, New York, 1987.

.. [Vidal-2005]
   | Vidal, D.; Thormann, M.; Pons, M.
   | LINGO, an Efficient Holographic Text Based Method To Calculate Biophysical Properties and Intermolecular Similarities.
   | *J. Chem. Inf. Model.* **2005**, *45* (2), 386–393.
   | DOI: 10.1021/ci0496797

.. [Virtanen-2010]
   | Virtanen, S.I; Pentikäinen, O.T.
   | Efficient Virtual Screening using Multiple Protein Conformations Described as Negative Images of the Ligand-Binding Site.
   | *J. Chem. Inf. Model.* **2010**, *50* (6), 1005–1011.
   | DOI: 10.1021/ci100121c

.. [Wang-J-2000]
   | Wang, J.; Cieplak, P.; Kollman, P.A.
   | How Well Does a Restrained Electrostatic Potential (RESP) Model Perform in Calculating Conformational Energies of Organic and Biological Molecules?
   | *J. Comput. Chem.* **2000**, *21* (12), 1049–1074.
   | DOI: 10.1002/1096-987x(200009)21:12<1049::aid-jcc3>3.0.co;2-f

.. [Wang-R-1997]
   | Wang, R.; Ying, F.; Lai, L.
   | A New Atom-Additive Method for Calculating Partition Coefficients.
   | *J. Chem. Inf. Comput. Sci.* **1997**, *37* (3), 615–621.
   | DOI: 10.1021/ci960169p

.. wang 1997 not referenced in this book 12/14/23

.. .. [Wang-T-1997]
   | Wang, T.; Zhou, J.
   | EMCSS: A New Method for Maximal Common Substructure Search.
   | *J. Chem. Inf. Comput. Sci.* **1997**, *37* (5), 828–834.
   | DOI: 10.1021/ci9601675

.. [Ward-2012]
   | Ward, R.A.; Brassington, C.; Breeze, A.L.; Caputo, A.; Critchlow, S.; Davies, G.; Goodwin, L.; Hassall, G.; Greenwood, R.; Holdgate, G.A.; et al.
   | Design and Synthesis of Novel Lactate Dehydrogenase A Inhibitors by Fragment-Based Lead Generation.
   | *J. Med. Chem.* **2012**, *55* (7), 3285–3306.
   | DOI: 10.1021/jm201734r

.. [Warren-2006]
   | Warren, G.L.; Andrews, C.W.; Capelli, A.-M.; Clarke, B.; LaLonde, J.; Lambert, M.H.; Lindvall, M.; Nevins, N.; Semus, S.F.; Senger, S.; et al.
   | A Critical Assessment of Docking Programs and Scoring Functions.
   | *J. Med. Chem.* **2006**, *49* (12), 5912–5931.
   | DOI: 10.1021/jm050362n

.. [Warren-2012]
   | Warren, G.L.; Do, T.D.; Kelley, B.P.; Nicholls, A.; Warren, S.D.
   | Essential Considerations for Using Protein–Ligand Structures in Drug Discovery.
   | *Drug Discov. Today* **2012**, *17* (23–24), 1270–1281.
   | DOI: 10.1016/j.drudis.2012.06.011

.. [Watson-2001]
   | Watson, P.; Willett, P.; Gillet, V.J.; Verdonk, M.L.
   | Calculating the Knowledge-Based Similarity of Functional Groups Using Crystallographic Data.
   | *J. Comput.-Aided Mol. Des.* **2001**, *15*, 835–857.
   | DOI: 10.1023/a:1013115500749

.. [Watts-2014]
   | Watts, K.S.; Dalal, P.; Tebben, A.J.; Cheney, D.L.; Shelley, J.C.
   | Macrocycle Conformational Sampling with MacroModel.
   | *J. Chem. Inf. Model.* **2014**, *54* (10), 2680–2696.
   | DOI: 10.1021/ci5001696

.. [Wikipedia-pValue]
   | P-value. *Wikipedia*.
   | https://en.wikipedia.org/w/index.php?title=P-value&oldid=1142130724 (accessed May 2011).

.. [Wlodek-2006]
   | Wlodek, S.; Skillman, A.G.; Nicholls, A.
   | Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential.
   | *Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *62* (7), 741–749.
   | DOI: 10.1107/s0907444906016076

.. [Wlodek-2010]
   | Wlodek, S.; Skillman, A.G.; Nicholls, A.
   | Ligand Entropy in Gas-Phase, Upon Solvation and Protein Complexation. Fast Estimation with Quasi-Newton Hessian.
   | *J. Chem. Theory Comput.* **2010**, *6* (7), 2140–2152.
   | DOI: 10.1021/ct100095p

.. [Yalkowsky-1980]
   | Yalkowsky, S.H.; Valvani, S.C.
   | Solubility and Partitioning I: Solubility of Nonelectrolytes in Water.
   | *J. Pharm. Sci.* **1980**, *69* (8), 912–922.
   | DOI: 10.1002/jps.2600690814

.. [Zhang-2012]
   | Tianhong Zhang; Hongli Li; Hualin Xi; Robert V. Stanton; Sergio H. Rotstein
   | HELM: A Hierarchical Notation Language for Complex Biomolecule Structure Representation
   | *J. Chem. Inf. Model.* **2012**, *52* (10), 2796−2806.
   | DOI: https://pubs.acs.org/doi/10.1021/ci3001925

:orphan:

..  _citation-info:

.. Version information file generated by CMake

.. |appspkgversion|  replace:: 2026.1.0

.. |afitt_version|  replace:: 3.0.4.0

.. |brood_version|  replace:: 5.0.0.0

.. |eon_version|  replace:: 3.1.3.0

.. |oedocking_version|  replace:: 4.3.5.0

.. |omega_version|  replace:: 7.0.0.0

.. |picto_version|  replace:: 5.1.5.0

.. |pka-prospector_version|  replace:: 1.2.7.0

.. |quacpac_version|  replace:: 2.3.0.0

.. |rocs_version|  replace:: 3.10.0.0

.. |sitehopper_version|  replace:: 2.1.4.0

.. |spruce_version|  replace:: 1.9.0.0

.. |szmap_version|  replace:: 1.7.4.0

.. |szybki_version|  replace:: 2.9.2.0

.. |vida_version|  replace:: 5.0.7.1



Citation Information for OpenEye Applications
=====================================================

To cite AFITT or FLYNN, please use the following:

    | AFITT |afitt_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com/.

    | Wlodek, S.; Skillman A.G.; Nicholls A. Automated Ligand Placement and Refinement with a Combined Force Field and Shape Potential. *Acta Crystallogr., Sect. D: Struct. Biol.* **2006**, *D62* (7), 741-749. DOI: 10.1107/s0907444906016076

To cite BROOD, please use the following:

    | BROOD |brood_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com/.

To cite EON, please use the following:

    | EON |eon_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com/.

To cite OEDocking, please use the following:

    | OEDocking |oedocking_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com/.

    | Kelley, B.P.; Brown, S.P.; Warren, G.L.; Muchmore, S.W. POSIT: Flexible Shape-Guided Docking For Pose Prediction. *J. Chem. Inf. Model.* **2015**, *55* (8), 1771-1780. DOI: 10.1021/acs.jcim.5b00142

    | McGann, M. FRED Pose Prediction and Virtual Screening Accuracy. *J. Chem. Inf. Model.* **2011**, *51* (3), 578-596. DOI: 10.1021/ci100436p

    | McGann, M. FRED and HYBRID Docking Performance on Standardized Datasets. *J. Comput.-Aided Mol. Des.* **2012**, *26* (8), 897-906. DOI: 10.1007/s10822-012-9584-8

To cite OMEGA, please use the following:

    | OMEGA |omega_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    | Hawkins, P.C.D.; Skillman, A.G.; Warren, G.L.; Ellingson, B.A.; Stahl, M.T. Conformer Generation with OMEGA: Algorithm and Validation Using High Quality Structures from the Protein Databank and the Cambridge Structural Database. *J. Chem. Inf. Model.* **2010**, *50* (4), 572-584. DOI: 10.1021/ci100031x

To cite PICTO, please use the following:

    | PICTO |picto_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

To cite pKa-Prospector, please use the following:

    | pKa-Prospector |pka-prospector_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

To cite QUACPAC, please use the following:

    | QUACPAC |quacpac_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

To cite ROCS, please use the following:

    | ROCS |rocs_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

    | Hawkins, P.C.D.; Skillman, A.G.; and Nicholls, A. Comparison of Shape-Matching and Docking as Virtual Screening Tools. *J. Med. Chem.* **2007**, *50* (1), 74-82. DOI: 10.1021/jm0603365

To cite SiteHopper, please use the following:

    SiteHopper |sitehopper_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

To cite Spruce, please use the following:

    Spruce |spruce_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com.

To cite SZMAP, please use the following:

    SZMAP |szmap_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com. (2013)

To cite SZYBKI, please use the following:

    SZYBKI |szybki_version|. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com

To cite VIDA, please use the following:

    VIDA <vida_version>. OpenEye, Cadence Molecular Sciences, Santa Fe, NM. http://www.eyesopen.com

    `The version number is available on the front page of the VIDA section <https://beta-docs.nm.eyesopen.us/applications/vida/index.html>`_.

.. _section_macrocycle:

Macrocycle Conformations
------------------------

Torsion driving conformational sampling methods such as described in the
:ref:`chapter_omegatheory` section often perform poorly
for macrocyclic molecules due to the problem of ring closure after the torsion driving step. 
Conformational sampling of macrocycles therefore requires a different approach;
we address this issue with **OMEGA** using distance geometry (DG) [Hawkins-2020]_. Other methods have been applied to this
problem, such as distance geometry (DG) [Crippen-1988]_, molecular dynamics (MD/LLMOD) [Watts-2014]_,
MD with perturbation along low energy eigenvectors [Labute-2010]_, and inverse kinematics
[Coutsias-2016]_. It is important to note that **OMEGA** DG also works well for very flexible linear molecules which have
such a large conformational space that torsion driving may not be able to adequately sample it.

**OMEGA**'s method of conformational sampling of macrocycles is an adaptation of the distance geometry method 
of Spellmeyer et al. [Spellmeyer-1997]_. In this method, a traditional embedding DG algorithm is replaced
with a direct error function minimization of the random atomic coordinates, followed by force field 
refinement. Each initial Cartesian atomic coordinate *x* is assigned by choosing a random number *r* 
between *-1* and *1*, multiplied by a factor :math:`f\sqrt{N}` which determines the box of maximum extent 
for a molecule with *N* atoms:

.. math:: x = f\sqrt{N}r
   :label: eqtnext

Alternatively, instead of randomly placing atoms in Cartesian space, the method allows for random
placement of rigid fragments such as aromatic rings, nitro groups, and so on. After randomly
placing molecules, atoms, or rigid fragments, an error function of the form:

.. math:: F = \sum_{i,j} (d_{ij}-c_{i,j})^2 + \sum_k V_k
   :label: eqtnerror

is optimized. In the above equation, the first sum runs over all pairs of atoms in the molecule,
where :math:`d_{ij}` are the interatomic distances and :math:`c_{ij}` are elements of the constraint matrix;
they are obtained from the MMFF94 force field parameters. When atoms *(i,j)* are
bonded or are the first and last atoms in a bond angle, the upper and lower bounds
are the same and are taken as the corresponding equilibrium force field distances. When
atoms *(i,j)* are the first and last atoms of a torsion angle, the lower bound corresponds to the cis configuration and
the upper bound to the trans configuration of those atoms. Finally, when atoms *(i,j)* are separated
by more than three bonds, the lower bound is taken as the sum of the vdW radii and the upper
bound as the sum of bond lengths which separate the pair. The second summation in
equation :eq:`eqtnerror` is over the tetrahedral constraints which result from:

1. planarity

2. chirality

3. cis-trans isomerism

Optimization of the error function :eq:`eqtnerror` leads to a rough conformation. No hydrogen atoms
except those which are bonded to chiral atoms are included in the error function minimization.
Each rough conformation is checked for chirality correctness before refinement. 
If the rough conformation passes the chirality checks, it is refined against a forcefield, MMFF94
([Halgren-I-1996]_, [Halgren-II-1996]_, [Halgren-III-1996]_, [Halgren-IV-1996]_, [Halgren-V-1996]_).
Solvent forces can be included in the refinement step using a simple continuum
solvation model (the Sheffield model [Grant-2007]_). When the sequence of random
placement followed by error function minimization and force field refinement is repeated for a large enough
number of times for a given macrocycle, its conformational space is reasonably well covered.

Special measures are taken for zwitterionic molecules (containing both positively and negatively
charged groups, such as :math:`CO_2^-` and :math:`NH_3^+`). In order to prevent possible Coulombic collapse
in the absence of a stabilizing receptor, zwitterionic molecules are neutralized before performing 
the distance geometry calculation and the refined structures are recharged before writing them out. 
This approach meaningfully improves **OMEGA**’s ability to reproduce solid-state conformations of
zwitterionic ligands.

This method of conformation sampling is completely general and can be used to generate conformations
for any molecule, whether or not it contains a large ring. However the ``macrocycle`` mode in **OMEGA** has
been specifically developed and parameterized to perform well on macrocycles, therefore its performance
on linear and small ring molecules is worse than with ``classic`` **OMEGA**.



.. _chapter_omegatheory:

Torsion Driving (TD) in OMEGA
-----------------------------

The torsion driving (TD) algorithm of **OMEGA** is composed of two main
components; building the molecular scaffold (model) from non-rotor fragments and
sampling the torsional degrees of freedom.
Model generation may be bypassed by importing fragment structures from
external sources ([Hawkins-2010]_; [Hawkins-2012]_).

**OMEGA** builds initial structures for the molecule by assembling fragment
templates along sigma bonds.  Input molecules' graphs are fragmented at
exocyclic sigma, and carbon to heteroatom acyclic (but not exocyclic)
sigma bonds.  Conformations for the fragments are either retrieved
from pregenerated libraries built with :ref:`MakeFraglib <chapter_makefraglib>` or
constructed on-the-fly using the same approach
that :ref:`MakeFraglib <chapter_makefraglib>` uses.  Molecule
assembly is accomplished by simple vector alignment since all
interfragment joints are along sigma bonds.

Once an initial structure is constructed or given as
input, **OMEGA** generates additional ones enumerating ring
conformations and invertible nitrogen atoms.  Ring conformations are
taken from the same fragment library used to build the initial model.
**OMEGA** detaches all exocyclic substituents from a ring system, then aligns
and attaches them relative to the new ring conformation.  **OMEGA**
attempts to generate every possible combination of ring conformations
possible for a given structure.  

The next step in model generation is to detect and enumerate
invertible nitrogens.  Nitrogens that have pyramidal geometry, no specified
stereochemistry, no more than one hydrogen, are three
valent, and have no more than three ring bonds are considered by **OMEGA**
to be invertible.  Invertible in this context simply means that at
room temperature a pyramidal nitrogen is likely to be able to rapidly
(on an NMR timescale) interconvert between two puckered forms.  All
multiconformer ring models are further expanded by enumerating all
possible nitrogen puckers.  The resulting model set is the starting
point for conformer search by torsion driving.

**OMEGA** begins the torsion search process by examining the molecular
graph and determining the bonds that may freely rotate.  By default, **OMEGA**
selects acyclic sigma bonds that have at least one non-hydrogen atom
attached to each end of the bond.  By default, hydrogen rotors (e.g., hydroxyl
groups) are not altered during the torsion search; however, this can be enabled.
The final ensemble selection is based on
RMS distance of heavy atoms and sampled hydrogen atoms; unsampled hydrogen atoms
do not affect this RMS distance. A list of
possible dihedral angles are then assigned to each rotatable bond.
The current mechanism for assignment is based on SMARTS matching,
although alternate strategies for assigning angles based on
experimental (i.e., X-ray) or theoretical (i.e., fragment optimization
studies) are possible.  The molecular graph is then subjected to
pattern and geometric symmetry detection.  Common patterns such as
para-disubstituted benzene are used to reduce the number of symmetry
equivalent dihedral angles that need to be searched.  All torsions are
altered by 120 and 180 degrees, and an RMS calculation is performed,
taking into account symmetry-equivalent atoms in order to detect two-
and three-fold symmetries. Once a set of nonredundant dihedral angles is
assigned to each rotatable bond, **OMEGA** samples the torsion space through
a systematic enumeration of combinations of these angles. Depending on the
flexibility of the molecule, the maximum number of conformers to be
generated, and the mode in which **OMEGA** is run, the algorithm to sample
the torsion space is decided. By default, Thompson sampling, a Bayesian reinforcement
learning algorithm, is used.
The best conformers identified in the torsion search
are rank-ordered by energy. A
final ensemble is selected by sequentially testing the conformers
using the RMS distance cutoff. To be accepted into the final
ensemble, a conformer must have an RMS distance to every other member
of the ensemble that exceeds the user-defined cutoff value.  The final
ensemble is populated up to the user-defined maximum ensemble size
limit, or until the list of low energy conformers is exhausted.

.. figure:: /_images/steps_in_tordrive.png
   :align: center
   :alt: Three-step TD workflow: generate initial models, sample conformer space using rotatable bond torsions, then prune and keep low-energy diverse conformers.

   **Figure 1.** Illustration of steps in torsion driving **OMEGA**.

Thompson Sampling in OMEGA
--------------------------
The torsion library provides a set of likely dihedral angles for each rotatable bond.
In Thompson sampling for torsion driving, we use these angles from the torsion rules as
priors for a Bayesian process. Instead of enumerating every possible
combination of angles and searching the combinatorially expanding space of conformers,
conformers are instead generated based on these priors.
For every angle for a given rotatable bond, a distribution of beliefs is maintained
for modeling the likelihood of that angle to be part of a new low strain conformer. We sample these
distributions to pick an angle for a given rotor. This process is repeated for every
rotatable bond to pick a combination of angles that defines a conformer.
After a conformer is generated, its energy is evaluated and the beliefs are updated
based on the result. As we generate more conformers while continuously updating the beliefs,
the sampling process is steered toward the low-strain structures of interest.

.. figure:: /_images/TSinOMEGA_cartoon.png
   :align: center
   :alt: Conceptual loop diagram of iterative torsion sampling, conformer scoring, and probability updates that favor unique, low-strain structures.

   **Figure 2.** Illustration of Thompson sampling algorithm in torsion driving **OMEGA**.

.. note::

   Conformers generated from **OMEGA** with default options do not maintain
   input relative stereochemistry, that is, cis/trans configurations for cyclohexane or other
   cyclic molecules.



.. _section_omega_modes:

OMEGA Sampling Modes
--------------------

**OMEGA** provides a set of predefined sampling modes, each tuned for a specific downstream
application. Selecting the right mode ensures that the output ensemble is appropriately sized and
shaped for the intended use case: not too sparse to miss binding-relevant geometries, but
not so dense as to be computationally unaffordable in the downstream step.
All modes except ``macrocycle`` (see the :ref:`Macrocycle Conformations section <section_macrocycle>`)
share the same underlying torsion driving (TD)
algorithm described in :ref:`Torsion Driving in Omega <chapter_omegatheory>`, but they differ in the default values of key
parameters such as the maximum number of conformers, energy window, and RMS pruning threshold.

.. figure:: /_images/modes_in_omega.png
   :align: center
   :alt: OMEGA sampling modes and relative sampling depth for downstream applications; see text for details.

   **Figure 1.** The torsion driving sampling modes in **OMEGA**.

The ``classic`` mode is the default mode. This allows a maximum of 200 conformations for a molecule.
These conformers represent a gas-phase ensemble. The  ``fastrocs``  and ``rocs`` modes are tailored toward
effective use in shape-based virtual screening applications: **FastROCS** and **ROCS**, with a
maximum of 10 and 50 conformations, respectively. The ``pose`` mode is designed for docking
with **OEDocking** (FRED/HYBRID) and allows up to 800 conformations for molecules with eight or more rotors.
The ``dense`` mode is designed for free-energy or solvation calculations with **Freeform** and generates
large ensembles (up to 20,000 conformations) with a tight RMS pruning threshold and a wide energy window
to provide thorough coverage of accessible conformational space.

Each of these modes not only has its own set of default parameters for ensemble slicing that are 
optimized for the intended downstream application, but the Thompson sampling strategy is also tailored 
for each mode, based on the typical flexibility of the molecule and the maximum number of conformers generated in that mode.

Choosing a Mode
^^^^^^^^^^^^^^^

The table below summarizes the recommended mode for common downstream applications:

.. list-table::
   :header-rows: 1
   :widths: 25 35 80

   * - Mode
     - Downstream Application
     - Key Characteristic
   * - ``classic``
     - General purpose
     - Gas-phase ensemble with balanced defaults
   * - ``fastrocs``
     - FastROCS GPU screening
     - Compact ensemble (up to 10 confs)
   * - ``rocs``
     - ROCS shape screening
     - Moderately sized, representative ensemble (up to 50 confs)
   * - ``pose``
     - OEDocking (FRED/HYBRID)
     - Wide energy window for bioactive conformers, up to 800 confs for flexible molecules
   * - ``dense``
     - Freeform free energy
     - Very dense ensemble with solvation scoring

