IMP logo
IMP Manual  develop.5651aa123e,2024/07/21
Installation

Binary installation

Binary installation is strongly recommended for new users of IMP. It is much faster than building from source code, requires a smaller download, and all the necessary prerequisites are handled for you automatically.

We recommend you use a stable release. These are available for Windows, Mac and Linux from our download page.

Binaries are also available for our latest nightly builds. If you do decide to use a nightly build, please check out the nightly builds results page to see if the code is currently stable enough for your purposes.

Google Colab

To experiment with IMP on Google Colaboratory, use the following code snippet:

!add-apt-repository -y ppa:salilab/ppa
!apt install imp
import sys, os, glob
sys.path.append(os.path.dirname(glob.glob('/usr/lib/python*/dist-packages/IMP')[0]))

Source code installation

Prerequisites

In order to build IMP from source, you will need:

  • A C++ compiler that supports the C++11 standard, such as gcc, clang, or Microsoft Visual Studio 2017 or later.
  • CMake (2.8.12 or later; 3.14 or later is recommended)
  • Boost (1.53 or later; Boost.Iostreams must be built with its zlib filter enabled)
  • Eigen (3.0 or later)
  • HDF5 (1.8 or later)
  • cereal
  • Python (3.6 or later)
  • SWIG (3 or later)

The following prerequisites are optional; without them some parts of IMP will not build, and some will not function optimally.

The following prerequisites are bundled, i.e. they are included with IMP itself and will be built at the same time as IMP, unless explicitly requested otherwise (see CMake for more information):

  • RMF (1.3 or later) for handling RMF files, and the IMP.rmf module.
  • python-ihm for handling mmCIF and BinaryCIF files.

(Note that if you build a stable release of IMP from source code, using versions of dependencies that were released after that IMP release (e.g. a brand new version of Python), you may run into build issues. Either use older versions of the dependencies, or look at the patches we've applied to the conda package and apply them to your source code checkout.)

Getting prerequisites on Linux

All of the prerequisites should be available as pre-built packages for your Linux distribution of choice. For example, on a Fedora system the following should install most of the prerequisites:

    sudo dnf install boost-devel gperftools-devel CGAL-devel graphviz gsl-devel cmake hdf5-devel swig fftw-devel opencv-devel python3-numpy

Getting prerequisites on a Mac

Mac users must first install the developer Command Line Tools, which can be done from the command line by running

    sudo xcode-select --install

These can also be obtained by installing Xcode from the App store, then trying to run a command line tool (such as clang) which will prompt to install the tools.

Then Mac users should use one of the available collections of Unix tools, such as

  • Homebrew (recommended) Once you installed homebrew do

      brew tap salilab/salilab
      brew install boost gmp google-perftools cgal graphviz gsl cmake hdf5 swig fftw mpfr opencv libtau eigen
    

    to install everything IMP finds useful (or that you will want for installing various useful Python libs that IMP finds useful). On older Macs, you may also need to brew install git if you want to use git (newer Macs include git).

  • Macports If you use MacPorts, you must verify /opt/local/bin is in your path (this may be taken care of by MacPorts automatically, and can be done manually either by modifying your shell's config file or by making an environment.plist file), and then do
      sudo port install boost cgal cmake fftw gmp gperftools graphviz gsl eigen hdf5 mpfr ninja opencv protobuf-cpp swig swig-python  
    
    (as in brew, some of these packages may be optional)
  • Conda Once you installed conda (typically via the Miniconda or Anaconda distributions), do

      conda create -n IMP_BUILD -c conda-forge python cxx-compiler c-compiler llvm-openmp swig cmake ninja numpy rmf ihm boost-cpp hdf5 libopencv eigen fftw gsl libcblas  cgal-cpp gmp mpfr mpich numpy cereal
      conda activate IMP_BUILD
      conda install -c anaconda protobuf libprotobuf
    

    Conda tips: as with brew and Macports, some of these packages may be optional. It is up to you whether to use "-c anaconda" or "-c conda-forge" for either of the packages, e.g. libprotobuf and protobuf worked better with anaconda in the past. In addition, cgal may not be identified by cmake. IMP will still run just fine. Either way, a solution could be setting the CGAL_DIR environment variable to $CONDA_PREFIX/lib/cmake/CGAL/ before running cmake, or adding a -DCGAL_DIR=$CONDA_PREFIX/lib/cmake/CGAL flag to the cmake command line ($CONDA_PREFIX is an environment variable that points to the folder of the active conda environment).

  • or Fink (not supported)

Getting prerequisites on Windows

We recommend Linux or Mac for developing with IMP, as obtaining the prerequisites on Windows is much more involved. However, if you really want to build on Windows, see the building from source code on Windows page for the procedure we use.

Download

  • Download the source code tarball from our download page, then extract it with something like:
      tar -xvzf ../imp-<version>.tar.gz
    
  • Alternatively you can use git to get the code directly from our GitHub repository with something like:

      git clone -b main https://github.com/salilab/imp.git
      (cd imp && git submodule update --init && ./setup_git.py)
    

    (the main branch tracks the most recent stable release; alternatively you can use develop to get the most recent code, but please check out the nightly builds results page to see if the code is currently stable enough for your purposes).

Compilation

Make a separate directory to keep the compiled version of IMP in (it's tidier to keep this separate from the source code, and if you need to later you can just delete this directory without affecting the source). Set up the build with CMake, then finally compile it, with something like:

mkdir imp_release
cd imp_release
cmake <path to IMP source>
make -j8

There are a number of ways in which IMP can be configured. See the configuration options page for more details and for help with CMake problems.

Testing

Once the compilation is complete, you can optionally run the test suite. Test are run using ctest. A good start is to run ctest --output-on-failure.

Tests are labeled with the module name and the type and cost of the test, so to run just the expensive tests in the atom module, use ctest -L "^IMP\.atom\-test\-.*EXPENSIVE".

Benchmarks are simply tests labeled as benchmark; examples are tests labeled as example.

Note that some test failures are to be expected; compare the failures with those at our own nightly builds page if you are concerned.

Installation

Once everything is compiled (and optionally tested) you can install IMP by simply running make install. If you opted to install in a non-standard location, it is up to you to set up your environment variables so that IMP can be found (you may need to set PATH, PYTHONPATH, and LD_LIBRARY_PATH).

Alternatively, you can run IMP directly from the build directory by using the setup_environment.sh script. This sets the necessary environment variables and then runs the rest of the command line with this modified environment. For example, to run the ligand_score command line tool you can either run

./setup_environment.sh ligand_score <arguments>

or create a new shell with

./setup_environment.sh $SHELL

and then run

ligand_score <arguments>

in that shell.