02_compiling.rst 16.4 KB
Newer Older
1
2
3
4
5
.. _compiling-openmm-from-source-code:

Compiling OpenMM from Source Code
#################################

6
7
8
9
10
This chapter describes the procedure for building and installing OpenMM from
source code.  In most cases, it is best to use the pre-built versions installed
with conda.  Sometimes you might need to build from source, though, such as if
you want to modify OpenMM, or if conda does not provide packages compatible with
your environment.
11

12
13
We first describe how to build on Linux or Mac.  We then describe how to build
on Windows, where the process is slightly different.
14

15
16
.. _compiling-openmm-from-source-linux:

17
18
Compiling on Linux and Mac
**************************
19

20
21
Prerequisites
=============
22

23
Before building OpenMM from source, you will need certain tools.
24

25
26
C++ compiler
------------
27
28

You must have a C++ compiler installed before attempting to build OpenMM from
29
30
31
32
33
source.  All recent versions of clang or gcc should work correctly.  On Linux,
you can install the compiler with your system's standard package manager (such
as apt or yum).  On MacOS, you can get a C++ compiler by installing the Xcode
developer tools from the App Store.  Alternatively you can use a package manager
such as Homebrew to install clang or gcc.
34

35
36
Python
------
37

38
39
40
You will need a 64-bit Python 3.x environment.  We recommend using Miniconda
(https://docs.conda.io/en/latest/miniconda.html), which includes the conda
package manager.
41

42
43
OpenMM Source Code
------------------
44

45
You will also need the OpenMM source code.  To download it:
46

47
48
49
50
#. Browse to https://github.com/openmm/openmm/releases.
#. Find the latest release and click the link to download the source as either
   a .zip or .tar.gz file.
#. Unpack the file.  Note the location where you unpacked the OpenMM source code.
51
52
53

Alternatively, if you want the most recent development version of the code rather
than the version corresponding to a particular release, you can get it from
54
https://github.com/openmm/openmm.  Be aware that the development code is constantly
55
56
57
58
changing, may contain bugs, and should never be used for production work.  If
you want a stable, well tested version of OpenMM, you should download the source
code for the latest release as described above.

59
60
CUDA or OpenCL Support
----------------------
61

62
63
64
If you want to compile OpenMM with support for running on GPUs, you will need
CUDA and/or OpenCL.  MacOS comes with OpenCL built in, so nothing else needs to
be installed.  For Linux, you need an appropriate SDK.
65

66
67
68
69
70
71
The easiest way is to install the most recent CUDA Toolkit from https://developer.nvidia.com/cuda-downloads.
It includes the headers and libraries needed to compile both CUDA and OpenCL
applications.  In addition, it has runtime libraries that are needed for running
CUDA applications.  The runtime components for OpenCL applications are included
with the GPU drivers from NVIDIA, AMD, and Intel, so make sure you have an
up-to-date driver.
72

73
74
Other Required Software
-----------------------
75

76
77
78
79
Several other tools are required to build OpenMM.  The easiest way to install
them is with conda.  The following command will install everything needed to
build OpenMM.
::
80

Peter Eastman's avatar
Peter Eastman committed
81
    conda install -c conda-forge cmake make cython swig doxygen numpy
82

83
84
Step 1: Configure with CMake
============================
85

86
87
88
First, create a directory in which to build OpenMM.  Starting from the root
level of the OpenMM source tree (the directory containing the top CMakeLists.txt
file), execute the following commands:
89

90
.. code-block:: none
91

92
93
94
    mkdir build
    cd build
    ccmake ..
95

96
97
98
That is not a typo.  :code:`ccmake` has two c’s.  CCMake is the visual CMake
configuration tool.  Press :code:`c` within the CCMake interface to load the
OpenMM build scripts and begin configuring CMake.
99

100
There are several variables that can be adjusted in the CMake interface:
101

102
* Set the variable CMAKE_INSTALL_PREFIX to the location where you want to
103
104
  install OpenMM. If you are using conda environments this variable should point to
  the full path of the root directory of your environment.
105
106
107
108
109
110
111
112
113
* Set the variable PYTHON_EXECUTABLE to the Python interpreter you plan to use
  OpenMM with.  Usually this will be detected automatically.
* There are lots of options starting with OPENMM_BUILD that control
  whether to build particular features of OpenMM, such as plugins, API wrappers,
  and documentation.
* Usually the OpenCL library and headers will be detected automatically.  If for
  any reason CMake is unable to find them, set OPENCL_INCLUDE_DIR to point to
  the directory containing the headers (usually /usr/local/cuda/include on Linux)
  and OPENCL_LIBRARY to point to the library (usually /usr/local/cuda/lib64/libOpenCL.so
114
  on Linux).
115

116
Configure (press “c”) again.  Adjust any variables that cause an error.
117

118
119
Continue to configure (press “c”) until no starred CMake variables are
displayed, then press “g” to generate the makefiles for building the project.
120

121
122
Step 2: Build
=============
123

124
Build OpenMM with the command::
125

126
    make
127

128
.. _test-your-build:
129

130
Step 3: Test your build
131
=======================
132

133
134
135
136
137
138
This step is optional but recommended. Tests can take up to several minutes depending on your
hardware configuration.

It is recommended that you make sure your local build of OpenMM works before trying
to install.

139
140
After OpenMM has been built, you should run the unit tests to make sure it
works.  Enter the command::
141

142
    make test
143

144
You should see a series of test results like this:
145

146
.. code-block:: none
147

148
149
150
151
152
153
154
            Start   1: TestReferenceAndersenThermostat
      1/317 Test   #1: TestReferenceAndersenThermostat .............. Passed  0.26 sec
            Start   2: TestReferenceBrownianIntegrator
      2/317 Test   #2: TestReferenceBrownianIntegrator .............. Passed  0.13 sec
            Start   3: TestReferenceCheckpoints
      3/317 Test   #3: TestReferenceCheckpoints ..................... Passed  0.02 sec
      ... <many other tests> ...
155

156
157
158
:code:`Passed` is good.  :code:`FAILED` is bad.  If any tests fail, you
can run them individually to get more detailed error information.  For example,
::
159

160
    ./TestReferenceLangevinIntegrator
161

162
163
Note that some tests are stochastic, and therefore are expected to fail a small
fraction of the time.  These tests will say so in the error message:
164

165
.. code-block:: none
166

167
168
    exception: Assertion failure at TestReferenceLangevinIntegrator.cpp:129.  Expected 9.97741,
        found 10.7884 (This test is stochastic and may occasionally fail)
169

170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
Step 3: Install
===============
Install your local build of OpenMM using the following command::

    make install

If you are installing to a system directory, such as /usr/local/openmm/, you will
need admin capabilities to install, in this case use::

    sudo make install

Step 3: Install the Python API
==============================

Build and install the Python API with the command::

    make PythonInstall

If you are installing into the system Python, such as /usr/bin/python, you will
need to type::

    sudo make PythonInstall

You can test the Python API installation using::

    python -m openmm.testInstallation

Congratulations! You have successfully built and installed OpenMM from source.
198

199
Compiling on Windows
200
201
********************

202
203
Prerequisites
=============
204

205
Before building OpenMM from source, you will need certain tools.
206

207
208
C++ compiler
------------
209

Peter Eastman's avatar
Peter Eastman committed
210
On Windows systems, use the C++ compiler in Visual Studio 2017 or later.  You
211
can download a free version of Visual Studio from https://visualstudio.microsoft.com.
212

213
214
Python
------
215

216
217
218
You will need a 64-bit Python 3.x environment.  We recommend using Miniconda
(https://docs.conda.io/en/latest/miniconda.html), which includes the conda
package manager.
219

220
221
CMake
-----
222

223
224
225
CMake is the build system used for OpenMM.  You must install CMake version 3.17
or higher before attempting to build OpenMM from source.  You can get CMake from
http://www.cmake.org/.
226

227
228
OpenMM Source Code
------------------
229

230
You will also need the OpenMM source code.  To download it:
231

232
233
234
235
#. Browse to https://github.com/openmm/openmm/releases.
#. Find the latest release and click the link to download the source as either
   a .zip or .tar.gz file.
#. Unpack the file.  Note the location where you unpacked the OpenMM source code.
236

237
238
239
240
241
242
Alternatively, if you want the most recent development version of the code rather
than the version corresponding to a particular release, you can get it from
https://github.com/openmm/openmm.  Be aware that the development code is constantly
changing, may contain bugs, and should never be used for production work.  If
you want a stable, well tested version of OpenMM, you should download the source
code for the latest release as described above.
243

244
245
CUDA or OpenCL Support
----------------------
246

247
248
249
250
251
252
253
If you want to compile OpenMM with support for running on GPUs, you will need
CUDA and/or OpenCL.  Install the most recent CUDA Toolkit from https://developer.nvidia.com/cuda-downloads.
It includes the headers and libraries needed to compile both CUDA and OpenCL
applications.  In addition, it has runtime libraries that are needed for running
CUDA applications.  The runtime components for OpenCL applications are included
with the GPU drivers from NVIDIA, AMD, and Intel, so make sure you have an
up-to-date driver.
254

255
256
Other Required Software
-----------------------
257

258
259
260
261
Several other tools are required to build OpenMM.  The easiest way to install
them is with conda.  From the Windows Start menu, select "Anaconda Prompt (Miniconda3)".
It will open a command window that is preconfigured for conda.  Enter the
following command to install everything needed to build OpenMM.
262
263
::

Peter Eastman's avatar
Peter Eastman committed
264
    conda install -c conda-forge cython swig doxygen numpy
265

266
267
Step 1: Configure with CMake
============================
268

269
270
271
First, create a directory in which to build OpenMM.  In the "Anaconda Prompt"
window opened above, cd to the root level of the OpenMM source tree (the
directory containing the top CMakeLists.txt file).  Execute the following commands:
272

273
.. code-block:: none
274

275
276
277
    mkdir build
    cd build
    "C:\Program Files\CMake\bin\cmake-gui.exe"
278

279
280
281
282
This will launch the CMake GUI configuration tool.  It is critical that you
launch it from the "Anaconda Prompt" window as shown above.  Do *not* launch
it from the Start menu.  If you do, it will not be able to find the tools you
installed with conda.
283

284
285
286
287
288
289
290
#. In the box labeled "Where is the source code" browse to the OpenMM source directory
   (containing the top CMakeLists.txt file).
#. In the box labeled "Where to build the binaries" browse to the build
   directory you just created.
#. Click the "Configure" button at the bottom of the CMake window.
#. Select "Visual Studio 16 2019" from the  list of Generators (or whichever
   version you have installed) and click "Finish".
291

292
There are several variables that can be adjusted in the CMake interface:
293

294
295
296
297
298
299
300
301
302
303
304
305
* Set the variable CMAKE_INSTALL_PREFIX to the location where you want to
  install OpenMM.
* Set the variable PYTHON_EXECUTABLE to the Python interpreter you plan to use
  OpenMM with.  Usually this will be detected automatically.
* There are lots of options starting with OPENMM_BUILD that control
  whether to build particular features of OpenMM, such as plugins, API wrappers,
  and documentation.
* Usually the OpenCL library and headers will be detected automatically.  If for
  any reason CMake is unable to find them, set OPENCL_INCLUDE_DIR to point to
  the directory containing the headers (usually
  "C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v11.4/include", except
  with the correct version number for the toolkit you installed) and
306
  OPENCL_LIBRARY to point to the library (usually "C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v11.4/lib/x64/OpenCL.lib").
307

308
Press "Configure" again.  Adjust any variables that cause an error.
309

310
311
Continue to press "Configure" until no red CMake variables are displayed, then
press "Generate" to create the Visual Studio project files for building OpenMM.
312

313
314
Step 2: Build and Install
=========================
315

316
317
318
319
320
321
#. Open the file :file:`OpenMM.sln` in your build directory in Visual Studio.
   Note that this file will appear as just :file:`OpenMM` if you have configured
   Explorer to hide file name extensions.
#. Set the configuration type to "Release" (not "Debug") in the toolbar.
#. From the Build menu, select "Build Solution".  This takes some time.
#. In the Solution Explorer, right-click on "INSTALL" and select "Build".
322

323
324
Step 3: Install the Python API
==============================
325

326
In the Solution Explorer, right-click on "PythonInstall" and select "Build".
327

328
329
Step 4: Test your build
=======================
330

331
332
After OpenMM has been built, you should run the unit tests to make sure it
works.  In the Solution Explorer, right-click on "RUN_TESTS" and select "Build".
333
You should see a series of test results like this:
334
335

.. code-block:: none
336
337
338
339
340
341
342
343
344
345

            Start   1: TestReferenceAndersenThermostat
      1/317 Test   #1: TestReferenceAndersenThermostat .............. Passed  0.26 sec
            Start   2: TestReferenceBrownianIntegrator
      2/317 Test   #2: TestReferenceBrownianIntegrator .............. Passed  0.13 sec
            Start   3: TestReferenceCheckpoints
      3/317 Test   #3: TestReferenceCheckpoints ..................... Passed  0.02 sec
      ... <many other tests> ...

:code:`Passed` is good.  :code:`FAILED` is bad.  If any tests fail, you
346
347
can run them individually to get more detailed error information.  Right-click
on a test in the Solution Explorer and select "Debug > Start New Instance".
348

349
350
351
352
Note that some tests are stochastic, and therefore are expected to fail a small
fraction of the time.  These tests will say so in the error message:

.. code-block:: none
353
354
355
356

    exception: Assertion failure at TestReferenceLangevinIntegrator.cpp:129.  Expected 9.97741,
        found 10.7884 (This test is stochastic and may occasionally fail)

357
358
Congratulations! You have successfully built and installed OpenMM from source.

359
360
361
362

Building the Documentation (Optional)
*************************************

363
364
The documentation that you're currently reading, as well as the Developer Guide and API
documentation, can be built through CMake.  To do that, you need to install a few
365
additional tools.  The easiest way is to use :code:`conda` to install them into
366
367
368
your Python environment.  The following command installs everything needed to
build documentation in HTML format.
::
369

370
    conda install -c conda-forge sphinx sphinxcontrib-bibtex breathe jinja2
371

372
373
To build documentation in PDF format, you also must have a functional LaTeX
installation.  It can be obtained from https://www.latex-project.org/get.
374

375
376
If you want to build documentation, make sure that OPENMM_GENERATE_API_DOCS is
set to ON when configuring the build in CMake.
377

378
To build the documentation, use the following build targets.
379

380
* :code:`sphinxhtml`: Build the User Guide and Developer Guide in HTML format.
381

382
* :code:`sphinxpdf`: Build the User Guide and Developer Guide in PDF format.
383

384
* :code:`C++ApiDocs`: Build the C++ API documentation.
385

386
387
388
* :code:`PythonApiDocs`: Build the Python API documentation.  This target
  requires that you have already built the :code:`install` target, such as with
  :code:`make install`.
389

390
391
On Linux or Mac, build a target using the :code:`make` command.  For example,
::
392

393
    make sphinxhtml
394

395
On Windows, right-click on the target in the Solution Explorer and select "Build".
396

397
398
399
After building the documentation, build the :code:`install` target to install
the documentation into the installation directory (the one you specified with
CMAKE_INSTALL_PREFIX).
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433

Using local build of OpenMM alongside conda tools that depend on it
*******************************************************************

A common case is to have a local build of OpenMM in the same environment as other tools
that depend on it. This can be achieved by forcing a remove of OpenMM when you install
your tools using conda.

We will use :code:`openmmtools` as an example here, but it can be replaced with any
other software package that requires OpenMM.

Step 1: Install your tools as usual
===================================

Install your tools using conda as you commonly do, for example using::

    conda install -c conda-forge  openmmtools

This will pull the conda-forge package of :code:`openmm` which we don't want since we want
to use our local build.

Step 2: Remove conda openmm package
===================================

To remove the openmm package that was installed in the previous step, we can use::

    conda remove --force openmm

This will remove the :code:`openmm` package without changing or removing dependencies.

Step 3: Install local build of openmm
=====================================

Now we just install our local build of :code:`openmm` as instructed in
434
:ref:`compiling-openmm-from-source-linux`