1 Installation {#installation}
6 # Binary installation {#installation_binary}
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.
12 We recommend you use a stable release. These are available
for
13 Windows, Mac and Linux from our [download page](https:
15 Binaries are [also available
for our latest nightly builds](https:
16 please check out the [nightly builds results page](https:
17 to see
if the code is currently stable enough
for your purposes.
19 # Google Colab {#installation_colab}
21 To experiment with IMP on [Google Colaboratory](https:
24 !add-apt-repository -y ppa:salilab/ppa
27 sys.path.append(os.path.dirname(glob.glob(
'/usr/lib/python*/dist-packages/IMP')[0]))
31 # Source code installation {#installation_source}
33 ## Prerequisites {#installation_prereqs}
35 In order to build %IMP from source, you will need:
37 - A C++ compiler that supports the C++11 standard, such as gcc, clang,
38 or Microsoft Visual Studio 2017 or later.
41 with its [zlib filter enabled](https:
48 The following prerequisites are _optional_; without them some parts of %IMP
49 will not build, and some will not
function optimally.
52 is built with NumPy, many operations that transfer data between C++ and Python
53 become more efficient.
57 - [Modeller](\ref modeller): needed to use the IMP.modeller module.
58 - [CGAL](\ref CGAL): enables faster geometric operations, such as
60 - [Google perf tools](\ref perf): needed only
for profiling %IMP code.
61 - [ANN](\ref ANN): certain data structures will be faster
if it is available.
62 - [GSL](\ref GSL) (1.13 or later): needed to use the IMP.gsl module.
63 - [OpenCV](\ref OpenCV) (2.1 or later): needed to use the IMP.em2d module or the
64 [idock](@ref idock_pcsk9) and [emagefit](@ref emagefit_3sfd) command
67 modules or the [multifit](@ref multifit_3sfd) command line tool.
69 IMP.cnmultifit module or the [cnmultifit](@ref cnmultifit_groel) command
72 IMP.npctransport module.
73 - An [MPI](@ref IMP::mpi) library is needed to use the IMP.mpi module.
76 and [matplotlib](https:
77 Python libraries are also recommended.
80 for visualization of results.
82 The following prerequisites are _bundled_, i.e. they are included with %IMP
83 itself and will be built at the same time as %IMP, unless explicitly
84 requested otherwise (see [CMake](@ref cmake_config)
for more information):
87 RMF files, and the IMP.rmf module.
91 (Note that
if you build a stable release of %IMP from source code,
using
92 versions of dependencies that were released _after_ that %IMP release
93 (e.g. a brand
new version of Python), you may run into build issues.
94 Either use older versions of the dependencies, or look at the
95 [patches we
've applied to the conda package](https://github.com/conda-forge/imp-feedstock/blob/main/recipe/meta.yaml)
96 and apply them to your source code checkout.)
98 ### Getting prerequisites on Linux {#installation_prereqs_linux}
99 All of the prerequisites should be available as pre-built packages for
100 your Linux distribution of choice. For example, on a Fedora system the
101 following should install most of the prerequisites:
103 sudo dnf install boost-devel gperftools-devel CGAL-devel graphviz gsl-devel cmake hdf5-devel swig fftw-devel opencv-devel python3-numpy
105 ### Getting prerequisites on a Mac {#installation_prereqs_mac}
107 Mac users must first install the developer Command Line Tools, which can be
108 done from the command line by running
110 sudo xcode-select --install
112 These can also be obtained by installing Xcode from the App store, then trying
113 to run a command line tool (such as `clang`) which will prompt to install the
116 Then Mac users should use one of the available collections of Unix tools,
118 - [Homebrew](https://brew.sh) (_recommended_) Once you installed `homebrew`
121 brew tap salilab/salilab
122 brew install boost gmp google-perftools cgal graphviz gsl cmake hdf5 swig fftw mpfr opencv libtau eigen
124 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).
125 - [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
127 sudo port install boost cgal cmake fftw gmp gperftools graphviz gsl eigen hdf5 mpfr ninja opencv protobuf-cpp swig swig-python
128 (as in brew, some of these packages may be optional)
132 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
133 conda activate IMP_BUILD
134 conda install -c anaconda protobuf libprotobuf
136 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).
141 ### Getting prerequisites on Windows {#installation_prereqs_windows}
143 We recommend Linux or Mac
for developing with %IMP, as obtaining the
144 prerequisites on Windows is much more involved. However,
if you really want
145 to build on Windows, see the
146 [building from source code on Windows](@ref install_windows) page
for the
150 ## Download {#installation_download}
152 - Download the source code tarball from [our download page](https:
154 tar -xvzf ../imp-<version>.tar.gz
156 - Alternatively you can use [git](https:
157 directly from our [GitHub repository](https:
160 git clone -b
main https:
161 (cd imp && git submodule update --init && ./setup_git.py)
163 (the `main` branch tracks the most recent stable
164 release; alternatively you can use `develop` to
get the most recent code,
165 but please check out the [nightly builds results page](https:
166 to see
if the code is currently stable enough
for your purposes).
168 ## Compilation {#installation_compilation}
170 Make a separate directory to keep the compiled version of %IMP in (it
's tidier
171 to keep this separate from the source code, and if you need to later you can
172 just delete this directory without affecting the source). Set up the build
173 with [CMake](@ref cmake_config), then finally compile it, with something
178 cmake <path to IMP source>
181 There are a number of ways in which %IMP can be configured.
182 See [the configuration options page](@ref cmake_config) for more details
183 and for help with CMake problems.
185 ## Testing {#installation_testing}
186 Once the compilation is complete, you can optionally run the test suite.
187 Test are run using `ctest`. A good start is to run `ctest --output-on-failure`.
189 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"`.
191 Benchmarks are simply tests labeled as `benchmark`; examples are tests labeled as `example`.
193 Note that some test failures are to be expected; compare the failures with
194 those at our own [nightly builds page](https://integrativemodeling.org/nightly/results/)
195 if you are concerned.
197 ## Installation {#installation_install}
199 Once everything is compiled (and optionally tested) you can install %IMP
200 by simply running `make install`. If you opted to install in a non-standard
201 location, it is up to you to set up your environment variables so that %IMP
202 can be found (you may need to set `PATH`, `PYTHONPATH`, and `LD_LIBRARY_PATH`).
204 Alternatively, you can run %IMP directly from the build directory by using
205 the `setup_environment.sh` script. This sets the necessary environment
206 variables and then runs the rest of the command line with this modified
207 environment. For example, to run the `ligand_score` command line tool you
210 ./setup_environment.sh ligand_score <arguments>
212 or create a new shell with
214 ./setup_environment.sh $SHELL
218 ligand_score <arguments>