Linux & OS X
************************************************************************
Installing OpenEye Python Toolkits
========================================================================
The two **recommended** ways to install the **OpenEye Python Toolkits**
are:
* *Anaconda* and pip (see section :ref:`section_python_conda`)
* *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.
If you do not want to use *Anaconda* or *virtualenv* you can directly
download **OpenEye Python Toolkits** packages and use the 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.
.. note::
In order to follow the
`PEP 440 <http://www.python.org/dev/peps/pep-0440>`_ guidelines on
versions, the version label for the python toolkit
is |pypkgversion| instead of |pkgversion|.
.. _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 instructions 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 Anaconda packages.
This version will default to Python 3 when creating new
environments and building packages.
After downloading and installing *Anaconda*, the **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-linux-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: 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.
.. 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.
.. hint::
When installing different versions of the toolkit (platform specific vs.
single build) in different conda environments, ``pip`` might try to
install the Python packages from the cache. In order to avoid this
problem, use the ``--no-cache-dir`` option.
.. 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/>`_,
the **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 virtual 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**
.. hint::
When installing different versions of the toolkit (platform specific vs.
single build) in different conda environments, ``pip`` might try to
install the Python packages from the cache. In order to avoid this
problem, use the ``--no-cache-dir`` option.
.. _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.
#. 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.
The ``PYTHONPATH`` environment variable can be set in
your shell startup script ``~/.bashrc`` For example, if the package was
untarred into the ``/usr/local`` directory:
.. 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|")
Substitute the path to the actual toolkit location.
All the toolkit examples can 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_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 supported by
OpenEye. This means that the libraries will only depend on older Linux system
functions (eg. glibc). Since Linux guarantees forwards compatibility,
the distribution will work across many modern Linux systems.
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 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 on linux, the default behavior is to install the
single-build Python package. In order to override this behavior and use the
older autodetect mechanism to install the platform-specific package one can
set the ``OE_PIP_ARCH`` environment variable to the value ``old`` before
executing the ``pip install`` command. Alternately, one can set
the ``OE_PIP_ARCH`` environment variable to a specific version string to
install exactly that version. The ``single-build`` distributions
include the string ``linux-x64`` in the name, so a ``pip list`` can be used
to identify whether the single-build or platform-specific distribution has
been installed.
.. note::
In previous toolkits, ``OE_ARCH`` was used by the installer for both
Python packages and applications. This caused confusion since the
platform names could be different for the applications and the
Python packages on a platform. Now ``OE_ARCH`` is used exclusively
by the applications and ``OE_PIP_ARCH`` is used exclusively by Python.
Example of installing the single-build distribution with *Anaconda*:
.. parsed-literal::
$ export OE_PIP_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 C++
runtime libraries. It will arise only if one is using the OpenEye toolkits
with other C++ based Python modules in the same Python environment. If the
other C++ based module is linked to a different libstdc++ library, it is
important that the *newest* libstdc++ library loads first. Adjust the import
order of C++ modules so that the python module which references the latest
libstdc++ runtime is loaded first. The OpenEye python libraries ship with
ABI version 3.4.22(dual), which is the latest runtime for g++ compilers
available as of January, 2017. Generally one should import openeye
first. Only if the other module is built against a later g++ version (some
time in the future) should one import the other module first.
If there is a runtime libstdc++ issue, it will typically result in a runtime
error message 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:
Unusual Installation Environments
------------------------------------------------------------------------
For assistance with unusual installation environments such as systems
without network access or heterogeneous clusters, please contact
support at [email protected].
Integration Testing
========================================================================
The **OpenEye Python Toolkits** ship with a simple set of integration
tests to make sure all the libraries function 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 tests are skipped on OS X, Windows, and Linux systems
without appropriate GPU hardware since FastROCS functionality is not available.
