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