---

    Linux & OS X
    ************************************************************************

    Installing OpenEye Python Toolkit
    ========================================================================

    There are multiple ways to install the **OpenEye Python Toolkits**. 

    The two **recommended** ways to install the **OpenEye Python Toolkits**
    are:

    * using *Anaconda* and pip (see section :ref:`section_python_conda`)
    * using *virtualenv* and pip (see section :ref:`section_python_pip`)

    .. warning::

       The above two ways are highly recommended since it is considered
       harmful to install packages into your global Python installation,
       known as ``site-packages``.

    If you do not want to use *Anaconda* or *virtualenv* you
    can directly download **OpenEye Python Toolkits** packages
    and use PYTHONPATH environment variable, however this method
    is only recommended for advanced users.
    (see section :ref:`section_python_pythonpath`).

    .. seealso::

       * :ref:`section_python_single_build` section to install **OpenEye Python Toolkits**
         across multiple Linux versions.

       * :ref:`section_python_cluster` section for advanced users who want to 
         install the **OpenEye Python Toolkits** for multiple Python versions and/or
         multiple platforms, in the same directory.

    .. note::

       In order to follow the `PEP 440
       <http://www.python.org/dev/peps/pep-0440>`_ guidelines on version
       numbers you will notice the version number of the toolkit is
       altered from |pkgversion| to |pypkgversion|.


    .. _section_python_conda:

    Anaconda Installation
    ------------------------------------------------------------------------

    The *Anaconda* package can be downloaded from
    https://www.continuum.io/downloads for Windows, OSX and Linux
    platforms. Follow the very simple instruction given there for
    installation. For first time users we also recommend reading
    http://conda.pydata.org/docs/test-drive.html and print out
    http://conda.pydata.org/docs/_downloads/conda-cheatsheet.pdf for
    reference.

    .. note::

       We recommend the installation of PYTHON 3.5 Anaconda packages.
       This version will default to Python 3 when creating new
       environments and building packages.

    After downloading and installing *Anaconda*, **OpenEye Python
    Toolkit** package can be installed by the following steps:

    #. First create a new conda environment, we recommend using Python 3:

       .. parsed-literal::

          $ conda create -n oepython3 python=3

       .. parsed-literal::

          Using Anaconda Cloud api site https://api.anaconda.org
          Fetching package metadata: ....
          Solving package specifications: .........

          Package plan for installation in environment  /home/username/anaconda/envs/oepython3:

          The following NEW packages will be INSTALLED:

           openssl:    1.0.2h-1
           pip:        8.1.2-py35_0
           python:     3.5.2-0
           readline:   6.2-2
           setuptools: 25.1.6-py35_0
           sqlite:     3.13.0-0
           tk:         8.5.18-0
           wheel:      0.29.0-py35_0
           xz:         5.2.2-0
           zlib:       1.2.8-3

          Proceed ([y]/n)? y

       After entering "y" to proceed, a new 'oepython3' environment
       will be created with Python 3.5.

    #. Activate the newly created 'oepython3' environment:

       .. parsed-literal::

          $ source activate oepython3
          (oepython3) $

       .. warning::

          It is very important to activate a work environment before pip installing,
          otherwise packages will be installed into the global Python environment.

    #. Pip install the **OpenEye Python Toolkits** into the new environment:

       .. parsed-literal::

          (oepython3) $ pip install -i https://pypi.anaconda.org/OpenEye/simple OpenEye-toolkits
          Collecting OpenEye-toolkits
          ...
          Successfully installed OpenEye-toolkits-|pypkgversion|  OpenEye-toolkits-python3-ubuntu-14.04-x64-|pypkgversion|


    #. Run the **OpenEye** example `oecheminfo.py` to verify the installation has completed successfully:

       .. parsed-literal::

          (oepython3) $ oecheminfo.py
          Installed OEChem version: |oechemversion| platform: Ubuntu-14.04-g++4.8-x64 built: |builddate|
          ...

    .. warning::

       Setting the environment variable ``PYTHONPATH`` will override the path to the Python  
       modules installed in a conda environment. 
       Make sure ``PYTHONPATH`` is **not** set when using a virtual environment.

    .. hint::

       We recommend using the *Anaconda* package, which is a complete suite
       containing hundreds of open source Python packages. 
       If disk-space is limited, we recommend the mini version of *Anaconda*,
       namely, *Miniconda*. *Miniconda* includes conda, its dependencies and Python.

       The *Miniconda* package can be downloaded from
       http://conda.pydata.org/miniconda.html for Windows, OSX and Linux
       platforms. The instructions for installation can be found here:
       http://conda.pydata.org/docs/install/quick.html

       All the above instructions for installing the **OpenEye Python Toolkits**
       are identical whether using the  *Anaconda* or *Miniconda* packages.

    .. seealso::

      :ref:`section_python_test` section for post-installation testing of the 
      **OpenEye Python Toolkits**


    .. _section_python_pip:

    Virtual Environment Installation
    ------------------------------------------------------------------------

    Assuming you have `virtualenv <http://www.virtualenv.org/en/latest/>`_
    and `virtualenvwrapper <http://virtualenvwrapper.readthedocs.org/en/latest/>`_,
    **OpenEye Python Toolkits** can be installed by the following steps:

    #. First create a new virtual environment:

       .. parsed-literal::

          $ mkvirtualenv oepython27

    #. Pip install **OpenEye Python Toolkits** into the new environment:

       .. parsed-literal::

          (oepython27) $ pip install -i https://pypi.anaconda.org/OpenEye/simple OpenEye-toolkits

       Or you can also pip install from a tarball downloaded from
       http://www.eyesopen.com/downloads.

       .. parsed-literal::

          (oepython27) $ pip install OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|.tar.gz

    #. Run the **OpenEye** example `oecheminfo.py` to verify the **OpenEye Python Toolkits** have been successfully installed:

       .. parsed-literal::

          (oepython27) $ oecheminfo.py
          Installed OEChem version: |oechemversion| platform: linux-g++4.x-x64 built: |builddate|
          ...


    .. warning::

       Setting the environment variable ``PYTHONPATH`` will override the path to the Python  
       modules installed in a conda environment. 
       Make sure ``PYTHONPATH`` is **not** set when using a virtual environment.

    .. seealso::

      :ref:`section_python_test` section for post-installation testing of the 
      **OpenEye Python Toolkits**


    .. _section_python_pythonpath:

    PYTHONPATH Installation
    ------------------------------------------------------------------------

    If you do not have root access or do not want to use *pip*  you
    can use the PYTHONPATH installation method.

    #. First you have to download the tarball that matches the python
       version, operating system, and architecture of your target
       machine's configuration. The **OpenEye Python Toolkits** packages
       can be download from http://www.eyesopen.com/downloads.

    #. Untar the downloaded distribution tarball:

       .. parsed-literal::

          $ tar xvf OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|.tar.gz

       This will yield a directory structure like the following:

       .. parsed-literal::

          OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|/
             openeye/
                libs/
                  python2.7-ubuntu-14.04-x64/
                docexamples/
                examples/

    #. Set the ``PYTHONPATH`` environment variable in order to enable the Python interpreter
       to find the `openeye`` directory.
       For example, if you untarred the package into the ``/usr/local``
       directory, the ``PYTHONPATH`` environment variable has to be set in
       your shell startup script ``~/.bashrc``

       .. parsed-literal::

          PYTHONPATH=/usr/local/OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|
          export PYTHONPATH

       The syntax and location may vary if you use a shell
       other than ``bash``.

       The equivalent can be done in Python code as follows:

       .. parsed-literal::

          $ python
          ...
          >>> import sys
          >>> sys.path.append("/usr/local/OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|")


       If you un-tarred in a different parent directory, you
       would use that actual location rather than ``/usr/local``.

       All the toolkit's examples can then be found in the ``examples``
       directory.  From the ``examples`` directory on the command line,
       the examples can be run using a command such as:

       .. parsed-literal::

          $ python oechem/oecheminfo.py
          Installed OEChem version: |oechemversion| platform: linux-g++4.x-x64 built: |builddate|
          ..

    .. _section_python_cluster:

    Heterogeneous Linux Cluster Installation
    ------------------------------------------------------------------------

    On Linux you can untar multiple versions of the toolkit into the same
    directory, for example Ubuntu 14 Python 3 and RHEL7 Python 2.7. When the
    module is imported the correct version will be selected automatically
    by the openeye runtime. ``PYTHONPATH`` need only be set to point at
    the top-level ``openeye`` directory. For example, installing both the
    Ubuntu14 and RHEL7 versions into the same NFS directory named
    ``/nfsdir/oepython`` could be accomplished by doing the following:

    .. parsed-literal::

       $ mkdir /nfsdir/oepython-|pkgversion|
       $ cd /nfsdir/oepython-|pkgversion|
       $ tar --strip-components 1 -vzxf /path/to/OpenEye-toolkits-python3-ubuntu-14.04-x64-|pypkgversion|.tar.gz OpenEye-toolkits-python3-ubuntu-14.04-x64-|pypkgversion|/openeye/
       $ tar --strip-components 1 -vzxf /path/to/OpenEye-toolkits-python2.7-redhat-7-x64-|pypkgversion|.tar.gz OpenEye-toolkits-python2.7-redhat-7-x64-|pypkgversion|/openeye/
       $ export PYTHONPATH=/nfsdir/oepython-|pkgversion|

    Using the above tar commands also strips out the extraneous files like
    ``setup.py`` and ``MANIFEST.in``. These files are only required by
    python packaging systems and are not needed when explicitly setting
    ``PYTHONPATH``.

    .. _section_python_single_build:

    Common Linux Single-Build Installation
    -------------------------------------------

    The ``single-build`` Linux package contains libraries built to be
    maximally-compatible with Linux-based systems.  It is built specifically to
    take advantage of the Linux cross-version compatibility guarantees in such
    a way that the Python package will run on many common Linux platforms.

    This distribution is built on the *oldest* version of Linux we support.
    This means that the libraries will only depend on older Linux system
    functions (eg. glibc).  Since Linux guarantees forwards compatibility, this
    means that the distribution will work across most modern Linux distributions.

    The distribution is built using a later g++ compiler toolchain.
    This allows us to take advantage of optimizations and language features
    only available in later g++ compiler versions (we're not tied to the
    old g++ from the older Linux OS).  This does create a new dependency on
    later versions of C++ runtime libraries (libstdc++.so, libgcc_s.so,
    libgomp.so).  These three files are included and installed with the OpenEye
    libraries in the Python ``site-packages`` directory, hence no additional
    configuration is required to use the ``single-build`` package.

    For a PIP installation, the current default behavior is to install the
    regular Python package based on the architecture detected by the
    OpenEye-toolkits installation process.  In order to override this behavior
    and use the ``single-build`` package, one must set the ``OE_ARCH`` environment
    variable to the value ``linux-x64`` before executing the ``pip install``
    command.  The ``single-build`` distributions include the string ``linux-x64``
    in the name, so a ``pip list`` can be used to verify that the correct
    distribution has been installed.

    Example of installing the single-build distribution with *Anaconda*:

    .. parsed-literal::

       $ export OE_ARCH=linux-x64
       $ conda create -n oepython3-sb python=3
       $ source activate oepython3-sb
       (oepython3-sb) $ pip install -i https://pypi.anaconda.org/OpenEye/simple OpenEye-toolkits
       ...
       Successfully installed OpenEye-toolkits-|pypkgversion| OpenEye-toolkits-python3-linux-x64-|pypkgversion|
       $ oecheminfo.py
       Installed OEChem version: |oechemversion| platform: linux-g++4.x-x64 built: |builddate|
       ...

    Because the ``single-build`` has an extra dependency on later g++ runtime
    libraries, there is a potential issue relating to the load order of
    the C++ runtime libraries.  It will arise only if one is using
    the OpenEye toolkits with other C++ based Python modules in the same
    Python executable.  If the other C++ based module is linked to a different
    libstdc++ library, it's important that the *newest* libstdc++ library
    loads first.  Avoiding this issue is straightforward; one can
    adjust the import order of C++ modules so that the latest (newest) libstdc++
    runtime is loaded first.  The OpenEye python libraries ship with version
    3.4.20, corresponding with g++ 4.9.  If other C++ modules were build with
    g++ 4.9 or lower, then one should ``import openeye`` first, otherwise one
    should ``import othermodule`` first.

    Note finally that if there is a runtime libstdc++ issue, it will typically
    result in a runtime error containing either  ``GLIBCXX`` or ``CXXABI``,
    as in the following example:

    .. parsed-literal::

       /usr/lib/x86_64-linux-gnu/libstdc++.so.6: version 'GLIBCXX_3.4.21'
       not found (required by python)

    .. _section_python_test:

    Integration Testing
    ========================================================================

    The **OpenEye Python Toolkits** ship with a simple set of integration
    tests to make sure all the libraries are functioning as intended. The
    test suite is not as exhaustive as the test suite used internally, it
    is just meant to ensure the **OpenEye Python Toolkits** infrastructure is
    working as intended.

    .. warning::

       Running the integration test requires *scripttest* and *nose*
       Python packages. These packages will be installed on-the-fly, if
       necessary. Again using *conda* or *virtualenv* environments
       will insure that these packages will not be installed into the global
       Python environment.

    To run the integration test suite (after activating the environment
    into which **OpenEye Python Toolkits** has been installed), execute the
    following command:

    .. parsed-literal::

       $ python -m openeye.examples.openeye_tests

    A message like the following will be shown if all the tests were run
    successfully::

       Collecting nose
         Using cached nose-1.3.7-py2-none-any.whl
       Installing collected packages: nose
       Successfully installed nose-1.3.7
       Collecting scripttest
       Installing collected packages: scripttest
       Successfully installed scripttest-1.3
       .........................................
       ----------------------------------------------------------------------
       Ran 41 tests in 95.877s

       OK


    Tests are skipped when the license is invalid/expired/doesn't exist or
    if functionally is not supported on the OS/platform.
    For example, when using an license file that contains only license 
    for the **OEChem TK**, a large number of tests will be skipped::

       SSSSSSSSSSSSSSS.......SSSSSSSSSSSSSSSSSSS
       ----------------------------------------------------------------------
       Ran 41 tests in 0.956s

       OK (SKIP=34)

    Similarly, FastROCS is skipped on OS X and Windows since the FastROCS
    functionality is not available on those platforms.