IMP logo
IMP Manual  for IMP version 2.20.0
installation.md
1 Installation {#installation}
2 ============
3 
4 [TOC]
5 
6 # Binary installation {#installation_binary}
7 
8 Binary installation is strongly recommended for new users of %IMP. It is
9 much faster than building from source code, requires a smaller download,
10 and all the necessary prerequisites are handled for you automatically.
11 
12 We recommend you use a stable release. These are available for
13 Windows, Mac and Linux from our [download page](https://integrativemodeling.org/download.html#stable).
14 
15 Binaries are [also available for our latest nightly builds](https://integrativemodeling.org/download.html#develop). If you do decide to use a nightly build,
16 please check out the [nightly builds results page](https://integrativemodeling.org/nightly/results/)
17 to see if the code is currently stable enough for your purposes.
18 
19 # Google Colab {#installation_colab}
20 
21 To experiment with IMP on [Google Colaboratory](https://colab.research.google.com), use the following code snippet:
22 
23 \code{.unparsed}
24 !echo "deb https://integrativemodeling.org/latest/download $(lsb_release -cs)/" > /etc/apt/sources.list.d/salilab.list
25 !wget -O /etc/apt/trusted.gpg.d/salilab.asc https://salilab.org/~ben/pubkey256.asc
26 !apt update
27 !apt install imp
28 import sys, os, glob
29 sys.path.append(os.path.dirname(glob.glob('/usr/lib/python*/dist-packages/IMP')[0]))
30 
31 \endcode
32 
33 # Source code installation {#installation_source}
34 
35 ## Prerequisites {#installation_prereqs}
36 
37 In order to build %IMP from source, you will need:
38 
39 - A C++ compiler that supports the C++11 standard, such as gcc, clang,
40  or Microsoft Visual Studio 2017 or later.
41 - [CMake](https://cmake.org) (2.8.12 or later; 3.14 or later is recommended)
42 - [Boost](https://www.boost.org) (1.53 or later; Boost.Iostreams must be built
43  with its [zlib filter enabled](https://www.boost.org/doc/libs/1_67_0/libs/iostreams/doc/installation.html))
44 - [Eigen](https://eigen.tuxfamily.org/) (3.0 or later)
45 - [HDF5](https://support.hdfgroup.org/HDF5/) (1.8 or later)
46 - [cereal](https://uscilab.github.io/cereal/)
47 - [Python](https://www.python.org) (3.6 or later, or 2.7)
48 - [SWIG](https://www.swig.org/) (3 or later)
49 
50 The following prerequisites are _optional_; without them some parts of %IMP
51 will not build, and some will not function optimally.
52 
53 - The [NumPy](https://numpy.org/) library is strongly recommended; if %IMP
54  is built with NumPy, many operations that transfer data between C++ and Python
55  become more efficient.
56 - [Doxygen](https://www.doxygen.nl/) (only exactly version 1.8.6 is supported)
57  and [Graphviz](https://www.graphviz.org/): required for building
58  documentation.
59 - [Modeller](\ref modeller): needed to use the IMP.modeller module.
60 - [CGAL](\ref CGAL): enables faster geometric operations, such as
61  nonbonded lists.
62 - [Google perf tools](\ref perf): needed only for profiling %IMP code.
63 - [ANN](\ref ANN): certain data structures will be faster if it is available.
64 - [GSL](\ref GSL) (1.13 or later): needed to use the IMP.gsl module.
65 - [OpenCV](\ref OpenCV) (2.1 or later): needed to use the IMP.em2d module or the
66  [idock](@ref idock_pcsk9) and [emagefit](@ref emagefit_3sfd) command
67  line tools.
68 - [FFTW](http://www.fftw.org): needed to use the IMP.em2d or IMP.multifit
69  modules or the [multifit](@ref multifit_3sfd) command line tool.
70 - [libTAU](https://integrativemodeling.org/libTAU.html): needed to use the
71  IMP.cnmultifit module or the [cnmultifit](@ref cnmultifit_groel) command
72  line tool.
73 - [Protobuf](https://github.com/google/protobuf): needed to use the
74  IMP.npctransport module.
75 - An [MPI](@ref IMP::mpi) library is needed to use the IMP.mpi module.
76 - The [scipy](https://scipy.org/install/),
77  [scikit-learn](https://scikit-learn.org/stable/install.html),
78  and [matplotlib](https://matplotlib.org/stable/users/installing/index.html)
79  Python libraries are also recommended.
80 - [Chimera](https://www.cgl.ucsf.edu/chimera/download.html) or
81  [ChimeraX](https://www.rbvi.ucsf.edu/chimerax/) are recommended
82  for visualization of results.
83 
84 The following prerequisites are _bundled_, i.e. they are included with %IMP
85 itself and will be built at the same time as %IMP, unless explicitly
86 requested otherwise (see [CMake](@ref cmake_config) for more information):
87 
88 - [RMF](https://integrativemodeling.org/rmf/) (1.3 or later) for handling
89  RMF files, and the IMP.rmf module.
90 - [python-ihm](https://github.com/ihmwg/python-ihm) for handling mmCIF and
91  BinaryCIF files.
92 
93 (Note that if you build a stable release of %IMP from source code, using
94 versions of dependencies that were released _after_ that %IMP release
95 (e.g. a brand new version of Python), you may run into build issues.
96 Either use older versions of the dependencies, or look at the
97 [patches we've applied to the conda package](https://github.com/conda-forge/imp-feedstock/blob/main/recipe/meta.yaml)
98 and apply them to your source code checkout.)
99 
100 ### Getting prerequisites on Linux {#installation_prereqs_linux}
101 All of the prerequisites should be available as pre-built packages for
102 your Linux distribution of choice. For example, on a Fedora system the
103 following should install most of the prerequisites:
104 
105  sudo dnf install boost-devel gperftools-devel CGAL-devel graphviz gsl-devel cmake hdf5-devel swig fftw-devel opencv-devel python3-numpy
106 
107 ### Getting prerequisites on a Mac {#installation_prereqs_mac}
108 
109 Mac users must first install the developer Command Line Tools, which can be
110 done from the command line by running
111 
112  sudo xcode-select --install
113 
114 These can also be obtained by installing Xcode from the App store, then trying
115 to run a command line tool (such as `clang`) which will prompt to install the
116 tools.
117 
118 Then Mac users should use one of the available collections of Unix tools,
119 such as
120 - [Homebrew](https://brew.sh) (_recommended_) Once you installed `homebrew`
121  do
122 
123  brew tap salilab/salilab
124  brew install boost gmp google-perftools cgal graphviz gsl cmake hdf5 swig fftw mpfr opencv libtau eigen
125 
126  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).
127 - [Macports](https://www.macports.org/) 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
128 
129  sudo port install boost cgal cmake fftw gmp gperftools graphviz gsl eigen hdf5 mpfr ninja opencv protobuf-cpp swig swig-python
130  (as in brew, some of these packages may be optional)
131 
132 - [Conda](https://docs.conda.io/en/latest/) Once you installed conda (typically via the Miniconda or Anaconda distributions), do
133 
134  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
135  conda activate IMP_BUILD
136  conda install -c anaconda protobuf libprotobuf
137 
138  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).
139 
140 
141 - or [Fink](http://www.finkproject.org/) (not supported)
142 
143 ### Getting prerequisites on Windows {#installation_prereqs_windows}
144 
145 We recommend Linux or Mac for developing with %IMP, as obtaining the
146 prerequisites on Windows is much more involved. However, if you really want
147 to build on Windows, see the
148 [building from source code on Windows](@ref install_windows) page for the
149 procedure we use.
150 
151 
152 ## Download {#installation_download}
153 
154 - Download the source code tarball from [our download page](https://integrativemodeling.org/download.html#source), then extract it with something like:
155 
156  tar -xvzf ../imp-<version>.tar.gz
157 
158 - Alternatively you can use [git](https://git-scm.com/) to get the code
159  directly from our [GitHub repository](https://github.com/salilab/imp)
160  with something like:
161 
162  git clone -b main https://github.com/salilab/imp.git
163  (cd imp && git submodule update --init && ./setup_git.py)
164 
165  (the `main` branch tracks the most recent stable
166  release; alternatively you can use `develop` to get the most recent code,
167  but please check out the [nightly builds results page](https://integrativemodeling.org/nightly/results/)
168  to see if the code is currently stable enough for your purposes).
169 
170 ## Compilation {#installation_compilation}
171 
172 Make a separate directory to keep the compiled version of %IMP in (it's tidier
173 to keep this separate from the source code, and if you need to later you can
174 just delete this directory without affecting the source). Set up the build
175 with [CMake](@ref cmake_config), then finally compile it, with something
176 like:
177 
178  mkdir imp_release
179  cd imp_release
180  cmake <path to IMP source>
181  make -j8
182 
183 There are a number of ways in which %IMP can be configured.
184 See [the configuration options page](@ref cmake_config) for more details
185 and for help with CMake problems.
186 
187 ## Testing {#installation_testing}
188 Once the compilation is complete, you can optionally run the test suite.
189 Test are run using `ctest`. A good start is to run `ctest --output-on-failure`.
190 
191 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"`.
192 
193 Benchmarks are simply tests labeled as `benchmark`; examples are tests labeled as `example`.
194 
195 Note that some test failures are to be expected; compare the failures with
196 those at our own [nightly builds page](https://integrativemodeling.org/nightly/results/)
197 if you are concerned.
198 
199 ## Installation {#installation_install}
200 
201 Once everything is compiled (and optionally tested) you can install %IMP
202 by simply running `make install`. If you opted to install in a non-standard
203 location, it is up to you to set up your environment variables so that %IMP
204 can be found (you may need to set `PATH`, `PYTHONPATH`, and `LD_LIBRARY_PATH`).
205 
206 Alternatively, you can run %IMP directly from the build directory by using
207 the `setup_environment.sh` script. This sets the necessary environment
208 variables and then runs the rest of the command line with this modified
209 environment. For example, to run the `ligand_score` command line tool you
210 can either run
211 
212  ./setup_environment.sh ligand_score <arguments>
213 
214 or create a new shell with
215 
216  ./setup_environment.sh $SHELL
217 
218 and then run
219 
220  ligand_score <arguments>
221 
222 in that shell.