Linux & OS X

Installing OpenEye Python Toolkits

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

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 PYTHONPATH Installation).

See also

Note

In order to follow the PEP 440 guidelines on versions, the version label for the python toolkit is 2017.6.1 instead of 2017.Jun.1.

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:

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

    $ conda create -n oepython3 python=3
    
    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.

  2. Activate the newly created ‘oepython3’ environment:

    $ 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.

  3. Pip install the OpenEye Python Toolkits into the new environment:

    (oepython3) $ pip install -i https://pypi.anaconda.org/OpenEye/simple OpenEye-toolkits
    Collecting OpenEye-toolkits
    ...
    Successfully installed OpenEye-toolkits-2017.6.1  OpenEye-toolkits-python3-linux-x64-2017.6.1
    
  4. Run the OpenEye example oecheminfo.py to verify the installation has completed successfully:

    (oepython3) $ oecheminfo.py
    Installed OEChem version: 2.1.2 platform: linux-g++4.x-x64 built: 20170617
    ...
    

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.

See also

Unusual Installation Environments section for post-installation testing of the OpenEye Python Toolkits

Virtual Environment Installation

Assuming you have virtualenv and virtualenvwrapper, the OpenEye Python Toolkits can be installed by the following steps:

  1. First create a new virtual environment:

    $ mkvirtualenv oepython27
    
  2. Pip install OpenEye Python Toolkits into the new environment:

    (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.

    (oepython27) $ pip install OpenEye-toolkits-python2.7-ubuntu-14.04-x64-2017.6.1.tar.gz
    
  3. Run the OpenEye example oecheminfo.py to verify the OpenEye Python Toolkits have been successfully installed:

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

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.

See also

Unusual Installation Environments 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.

PYTHONPATH Installation

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

  1. 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.

  2. Untar the downloaded distribution tarball:

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

    This will yield a directory structure like the following:

    OpenEye-toolkits-python2.7-ubuntu-14.04-x64-2017.6.1/
       openeye/
          libs/
            python2.7-ubuntu-14.04-x64/
          docexamples/
          examples/
    
  3. 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:

    PYTHONPATH=/usr/local/OpenEye-toolkits-python2.7-ubuntu-14.04-x64-2017.6.1
    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:

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

    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:

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

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:

$ 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-2017.6.1 OpenEye-toolkits-python3-linux-x64-2017.6.1
$ oecheminfo.py
Installed OEChem version: 2.1.2 platform: linux-g++4.x-x64 built: 20170617
...

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:

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

Unusual Installation Environments

For assistance with unusual installation environments such as systems without network access or heterogeneous clusters, please contact support at support@eyesopen.com.

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:

$ 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.