Installation notes

Support and Help

If you have any problems or suggestions please do get in touch with us at support@ccdc.cam.ac.uk.

An open community github repository focused on scripts using the CSD Python API is available at github.com/ccdc-opensource/csd-python-api-scripts and you are encouraged to visit this site in the first instance if you require inspiration with what is possible with the CSD Python API. We are also grateful for any feedback from your experiences with the CSD Python API.

Supported platforms

The CSD Python API is known compatible with, and fully supported on, the following platforms:

  • Windows - Intel compatible, 64-bit:

    • Windows 10 and 11

  • Linux - Intel compatible, 64-bit:

    • RedHat Enterprise 7.6 or higher, and 8

    • CentOS 7.6 or higher

    • CentOS Stream 8

    • Ubuntu LTS 20 and 22

    • We do not support Wayland as a display server protocol (see known issues). Note: As we add support for newer versions of Linux, support for older versions may have to be withdrawn. If you are using a linux version near the minimum that we support, we would recommend updating in the near future to ensure you are able to use future CSD software updates without interruption.

  • macOS - Intel compatible or Apple ARM (via Rosetta 2 emulation)*, 64-bit:

    • macOS 11, 12 and 13

    • Note: Apple ARM-based (M1) systems are supported with this release via emulation with Rosetta 2

The CSD Python API may work on additional, unsupported, platforms.

Python versions

Python 3.7 and 3.9 are supported, and Python 3.9 is provided by default with the CSD Software Portfolio. Separate pip and conda packages are available for supported versions of Windows, Linux and macOS.

Python installation

Windows

  1. If you do not already have a supported Python 3 installation (for example, Python 3.9) then please download and run the latest Windows installer from www.python.org/downloads. By default this will create:

    C:\Python37

    Make sure that your path variable includes your Python directory and your Python Scripts directory. For example by updating the PATH:

    set PATH=%PATH%;C:\Python39;C:\Python39\Scripts

Linux

  1. If your distribution has a package available for a supported version of Python 3 (for example Python 3.9), simply install this using the system package manager; otherwise follow steps 2 and 3 to install Python 3 from source.

  2. If you need to install Python from source, first install the libraries required to compile a working Python 3. On CentOS 7 and 8, you can install these as follows:

    $ sudo yum install -y gcc make openssl-devel bzip2-devel libffi libffi-devel sqlite-devel xz-devel

  3. Next, download the latest Python 3 Linux source code package from https://www.python.org/downloads/. To build and install this locally to your user directory:

    $ tar zxvf Python-3.9.*.tgz
$ cd Python-3.9.*
$ ./configure --prefix=$HOME/python3.7 --enable-optimizations --enable-shared
$ make
$ make install

    If you install Python 3 to your home directory, make sure to edit your .bashrc file to add the new Python installation to your PATH:

    $ echo export PATH=$PATH:$HOME/python3.7/bin >> ~/.bashrc
$ echo export LD_LIBRARY_PATH=$HOME/python3.9/lib:$LD_LIBRARY_PATH >> ~/.bashrc

    To instead install system-wide to /usr/local - which won’t require changes to your system paths afterwards, but requires root permissions:

    $ tar zxvf Python-3.9.*.tgz
$ cd Python-3.9.*
$ ./configure --enable-optimizations --enable-shared
$ sudo make altinstall

MacOS

For macOS the Python version should be from python.org for our pip package. The pre-installed system Python on macOS is not supported. We recommend the use of our conda packages with Anaconda Python for macOS for macOS.

Installation

Installation options

More than one mechanism exists for installing the CSD Python API.

The CSDS 2024 release includes a self-contained Python environment with the CSD Python API preinstalled with all of its prerequisites. In this case, no additional installation steps are required. We recommend this for most users.

For more advanced users, the CSD Python API can also be installed via pip and conda. These are for the standard Python package managers that are available on most platforms, and may be used for installing the CSD Python API into pre-existing Python environments. The following instructions are specifically for these more complicated options.

The CSD Python API may be installed using either pip or conda. Conda is a part of the Anaconda Python Distribution.

Note

In all cases, if you have not yet installed the CSD Portfolio 2024 release, then you will need to do this first. However, the toolkit will continue to work in the absence of the CSD if non-data dependent features are used.

Note

It is important to correctly match versions of the ccdc package with the version of Python in use.

Using conda

The CSD Python API can be installed on all supported platforms via conda from the CCDC conda channel.

In a valid conda environment, install the package specifying the channel:

conda install --channel=https://conda.ccdc.cam.ac.uk csd-python-api

Alternatively, you may wish to configure the channel in your conda environment to make installation easy in the future:

conda config --add channels https://conda.ccdc.cam.ac.uk
conda install csd-python-api

Note

The CSD Python API depends on a number of packages in conda-forge. Please ensure that conda-forge channel is configured in your conda environment.

Using pip

The CSD Python API can be installed on all supported platforms via pip from the CCDC pip package repository.

In a valid Python environment, install the package specifying the index URL:

python -m pip install --extra-index-url https://pip.ccdc.cam.ac.uk/ csd-python-api

Offline packages

Instead of using the online conda channel or pip package repository, users may choose to download the conda channel zip files or the pip wheel files for offline installation. They are available from the CSD Software Portfolio download page:

  • CSD Python API - Python package

    • pip package or zipped conda channel

Warning

If you previously installed a version of the CSD Python API, you must uninstall this before installing this release. If you used pip, versions later than 1.0 can be uninstalled using:

pip uninstall csd-python-api

Using conda

  1. Unzip the downloaded conda channel to a location of your choice.

  2. Ensure you have installed the CSD Portfolio 2024 release in order to use the CSD and any data dependent feature.

  3. Install the packages:

conda install -c <ccdc_conda_channel location> Pillow six lxml numpy matplotlib
conda install -c <ccdc_conda_channel location> csd-python-api

where <ccdc_conda_channel location> is the full absolute path to the unzipped content of the downloaded conda channel.

Using pip on Windows

  1. If it is not already installed, install pip. pip is included as standard with recent Python versions.

  2. Install the CSD Python API by running (for example for Python 3.9):

pip install csd_python_api-3.1.0-py39-none-win_amd64.whl

Warning

If the installation fails to load the required modules with an error similar to Unable to load _UtilitiesLib then it is likely that your computer does not contain the required Microsoft runtime libraries. These may be installed from: the Visual C++ Redistributable Package for Visual Studio 2017

Warning

pip automatically downloads additional packages such as lxml. Some company firewalls block this, so you may need to configure an HTTPS proxy. Ask your systems administrator for more information.

Using pip on Linux

Warning

Using the pip package on macOS is not supported. We recommend the use of our conda packages with Anaconda Python for macOS for macOS.

  1. To install the CSD Python API into your own Python 3 environment (for example Python 3.9) run:

    $ python3 -m pip install csd-python-api-3.1.0-py39-none-linux_x86_64.whl

    Warning

    pip automatically downloads additional packages such as lxml. Some company firewalls block this, so you may need to configure an HTTPS proxy. Ask your systems administrator for more information.

Post-installation

CSD.ini

A configuration file can now be used to specify the CSD data location (from release 2023.1 onwards). You might need to set this up if your CSD data is not located in the usual location. The configuration file can be found at the following path on different platforms:

  • Windows

    • %HOMEPATH%\AppData\Roaming\CCDC\CSD.ini

  • Linux and MacOS

    • $HOME/.config/CCDC/CSD.ini

This CSD.ini file will usually be created automatically in a standard installation. It can also be created by running the csd_location tool. If you need to examine it or create it manually, the content of the file should, for example, be:

[General]
root=/home/user/CCDC/ccdc-data/

where the value of root is the directory which contains the csd directory containing the actual CSD sqlite file(s).

Environment on Linux and MacOS

If you have installed any of the CSD components in non-standard locations it is possible to specify these locations using the environment variables listed below. You may want to add these to your .bashrc, or similar, file to ensure they’re set on every session. e.g.:

$ # Set the variables required to locate the CSD data and files
$ export CCDC_TOOLKIT_ASER_DATABASE=/home/user/CCDC/ccdc-data/csd/as545be
$ export CCDC_TOOLKIT_SQLITE_DATABASE=/home/user/CCDC/ccdc-data/csd/as545be_ASER.sqlite
$ export CCDC_ISOSTAR_DATA_DIRECTORY=/home/user/CCDC/ccdc-data/isostar
$ export CCDC_MOGUL_DATA=/home/user/CCDC/ccdc-data/mogul
$ export CCDC_MOGUL_INITIALISATION_FILE=$PYTHONHOME/lib/python3.7/site-packages/ccdc/parameter_files/mogul.ini
$ export CCDC_CROSSMINER_DATABASE=/home/user/CCDC/ccdc-data/crossminer/csd_pdb_crossminer.feat
$ export CCDC_CROSSMINER_FEATURE_DEFINITIONS=/home/user/CCDC/ccdc-data/crossminer/feature_definitions
$ export GOLD_DIR=/home/user/CCDC/ccdc-software/gold/GOLD

On Red Hat 7 derivatives such as CentOS 7 only, you might need to set LD_LIBRARY_PATH to include both your Python installation and the CSD Python API _lib directory. On the assumption that PY39 points at the root of your Python 3.9 installation (e.g., /usr/local/ when installing system-wide or the directory in your home directory if you’ve installed locally):

$ export LD_LIBRARY_PATH=$PY39/lib:$PY39/lib/python3.9/site-packages/ccdc/_lib:$LD_LIBRARY_PATH

It is important that older versions of the CSD Python API are not additionally referenced within the LD_LIBRARY_PATH value (DYLD_LIBRARY_PATH on macOS).

Optional Third-party Packages

Several of the example scripts rely on external packages such as matplotlib and jinja2, as do some scripts distributed with the Mercury and Hermes software. These are not needed for use of the CSD Python API itself. To use these example scripts your Python environment will need to include these packages.

To install matplotlib, jinja2, numpy, and biopython, use, e.g.:

pip install matplotlib jinja2 numpy biopython

Testing The CSD Python API

The CSD Python API test package is available from the CSD Software Portfolio download page. This package contains a README file with instructions.