Skip to content

GitLab

Unverified Commit 62002c50 authored by Peter Eastman's avatar Peter Eastman Committed by GitHub
Browse files

Update instructions on compiling from source (#3186) 

* Update instructions on compiling from source

* Minor changes based on feedback
parent 245f18cf
Show whitespace changes
Inline Side-by-side
Showing with 251 additions and 262 deletions
docs-source/usersguide/library/02_compiling.rst
View file @ 62002c50
...@@ -3,315 +3,319 @@ ...@@ -3,315 +3,319 @@
Compiling OpenMM from Source Code Compiling OpenMM from Source Code
################################# #################################
This chapter describes the procedure for building and installing OpenMM This chapter describes the procedure for building and installing OpenMM from
libraries from source code. It is recommended that you use binary OpenMM source code. In most cases, it is best to use the pre-built versions installed
libraries, if possible. If there are not suitable binary libraries for your with conda. Sometimes you might need to build from source, though, such as if
system, consider building OpenMM from source code by following these you want to modify OpenMM, or if conda does not provide packages compatible with
instructions. your environment.
Prerequisites We first describe how to build on Linux or Mac. We then describe how to build
************* on Windows, where the process is slightly different.
Before building OpenMM from source, you will need the following:
* A C++ compiler
* CMake Compiling on Linux and Mac
**************************
* OpenMM source code
Prerequisites
=============
See the sections below for specific instructions for the different platforms. Before building OpenMM from source, you will need certain tools.
Get a C++ compiler C++ compiler
================== ------------
You must have a C++ compiler installed before attempting to build OpenMM from You must have a C++ compiler installed before attempting to build OpenMM from
source. 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
Mac and Linux: clang or gcc 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.
Use clang or gcc on Mac/Linux. OpenMM should compile correctly with all recent
versions of these compilers. We recommend clang since it produces faster code,
especially when using the CPU platform. If you do not already have a compiler
installed, you will need to download and install it. On Mac OS X, this means
downloading the Xcode Tools from the App Store.
Windows: Visual Studio
----------------------
On Windows systems, use the C++ compiler in Visual Studio 2015 or later. You Python
can download a free version of the Visual Studio C++ build tools from ------
https://visualstudio.microsoft.com. If you plan to use OpenMM from
Python, it is critical that both OpenMM and Python be compiled with the same
version of Visual Studio.
Install CMake 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.
CMake is the build system used for OpenMM. You must install CMake version 3.1
or higher before attempting to build OpenMM from source. You can get CMake from
http://www.cmake.org/. If you choose to build CMake from source on Linux, make
sure you have the curses library installed beforehand, so that you will be able
to build the CCMake visual CMake tool.
Get the OpenMM source code OpenMM Source Code
========================== ------------------
You will also need the OpenMM source code before building OpenMM from source. You will also need the OpenMM source code. To download it:
To download and unpack OpenMM source code:
#. Browse to https://simtk.org/home/openmm. #. Browse to https://github.com/openmm/openmm/releases.
#. Click the "Downloads" link in the navigation bar on the left side. #. Find the latest release and click the link to download the source as either
#. Download OpenMM<Version>-Source.zip, choosing the latest version. a .zip or .tar.gz file.
#. Unpack the zip file. Note the location where you unpacked the OpenMM source #. Unpack the file. Note the location where you unpacked the OpenMM source code.
code.
Alternatively, if you want the most recent development version of the code rather 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 than the version corresponding to a particular release, you can get it from
https://github.com/pandegroup/openmm. Be aware that the development code is constantly 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 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 you want a stable, well tested version of OpenMM, you should download the source
code for the latest release as described above. code for the latest release as described above.
Other Required Software CUDA or OpenCL Support
======================= ----------------------
There are several other pieces of software you must install to compile certain
parts of OpenMM. Which of these you need depends on the options you select in
CMake.
* For compiling the CUDA Platform, you need: 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.
* CUDA (See Chapter :numref:`installing-openmm` for installation instructions.) 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.
* For compiling the OpenCL Platform, you need: Other Required Software
-----------------------
* OpenCL (See Chapter :numref:`installing-openmm` for installation instructions.) 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.
::
* For compiling C and Fortran API wrappers, you need: conda install -c conda-forge cmake make cython swig fftw doxygen numpy
* Python 2.7 or later (http://www.python.org) Step 1: Configure with CMake
* Doxygen (http://www.doxygen.org) ============================
* A Fortran compiler
* For compiling the Python API wrappers, you need: 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:
* Python 2.7 or later (http://www.python.org) .. code-block:: none
* SWIG (http://www.swig.org)
* Doxygen (http://www.doxygen.org)
* Cython (https://cython.org)
* For compiling the CPU platform, you need: mkdir build
cd build
ccmake ..
* FFTW, single precision multithreaded version (http://www.fftw.org) 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.
* To generate API documentation, you need: There are several variables that can be adjusted in the CMake interface:
* Doxygen (http://www.doxygen.org) * 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 /usr/local/cuda/include on Linux)
and OPENCL_LIBRARY to point to the library (usually /usr/local/cuda/lib64/libOpenCL.so
on Linux).
Configure (press “c”) again. Adjust any variables that cause an error.
Continue to configure (press “c”) until no starred CMake variables are
displayed, then press “g” to generate the makefiles for building the project.
Step 1: Configure with CMake Step 2: Build and Install
**************************** =========================
Build and install OpenMM with the command::
Build and source directories make install
============================
First, create a directory in which to build OpenMM. A good name for this If you are installing to a system area, such as /usr/local/openmm/, you will
directory is build_openmm. We will refer to this as the “build_openmm need to type::
directory” in the instructions below. This directory will contain the temporary
files used by the OpenMM CMake build system. Do not create this build directory
within the OpenMM source code directory. This is what is called an “out of
source” build, because the build files will not be mixed with the source files.
Also note the location of the OpenMM source directory (i.e., where you unpacked sudo make install
the source code zip file). It should contain a file called CMakeLists.txt.
This directory is what we will call the “OpenMM source directory” in the
following instructions.
Starting CMake Step 3: Install the Python API
============== ==============================
Configuration is the first step of the CMake build process. In the Build and install the Python API with the command::
configuration step, the values of important build variables will be established.
Mac and Linux make PythonInstall
-------------
On Mac and Linux machines, type the following two lines: If you are installing into the system Python, such as /usr/bin/python, you will
need to type:
:: ::
cd build_openmm sudo make PythonInstall
ccmake -i <path to OpenMM src directory>
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
configure CMake. Follow the instructions in the “All Platforms” section below.
Windows
-------
On Windows, perform the following steps:
#. Click Start->All Programs->CMake 3.1->CMake
#. In the box labeled "Where is the source code:" browse to OpenMM src directory
(containing top CMakeLists.txt)
#. In the box labeled "Where to build the binaries" browse to your build_openmm
directory.
#. Click the "Configure" button at the bottom of the CMake screen.
#. Select "Visual Studio 10 2010" from the list of Generators (or whichever
version you have installed)
#. Follow the instructions in the “All Platforms” section below.
All platforms
-------------
There are several variables that can be adjusted in the CMake interface:
* If you intend to use CUDA (NVIDIA) or OpenCL acceleration, set the variable .. _test-your-build:
OPENMM_BUILD_CUDA_LIB or OPENMM_BUILD_OPENCL_LIB, respectively, to ON. Before
doing so, be certain that you have installed and tested the drivers for the
platform you have selected (see Chapter :numref:`installing-openmm` for information on
installing GPU software).
* There are lots of other options starting with OPENMM_BUILD that control
whether to build particular features of OpenMM, such as plugins, API wrappers,
and documentation.
* 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.
Step 4: Test your build
=======================
Configure (press “c”) again. Adjust any variables that cause an After OpenMM has been built, you should run the unit tests to make sure it
error. works. Enter the command::
Continue to configure (press “c”) until no starred/red CMake make test
variables are displayed. Congratulations, you have completed the configuration
step.
Step 2: Generate Build Files with CMake You should see a series of test results like this:
***************************************
Once the configuration is done, the next step is generation. The generate .. code-block:: none
“g” or “OK” or “Generate” option will not be available until
configuration has completely converged.
Windows 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> ...
* Press the "OK" or “Generate” button to generate Visual Studio project files. :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,
::
* If CMake does not exit automatically, press the close button in the upper- ./TestReferenceLangevinIntegrator
right corner of the CMake title bar to exit.
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:
Mac and Linux .. code-block:: none
=============
* Press “g” to generate the Makefile. exception: Assertion failure at TestReferenceLangevinIntegrator.cpp:129. Expected 9.97741,
* If CMake does not exit automatically, press “q” to exit. found 10.7884 (This test is stochastic and may occasionally fail)
Congratulations! You have successfully built and installed OpenMM from source.
That’s it! Generation is the easy part. Now it’s time to build.
Step 3: Build OpenMM Compiling on Windows
******************** ********************
Prerequisites
=============
Windows Before building OpenMM from source, you will need certain tools.
=======
#. Open the file OpenMM.sln in your openmm_build directory in Visual Studio. C++ compiler
#. Set the configuration type to "Release" (not "Debug") in the toolbar. ------------
#. From the Build menu, click Build->Build Solution
#. The OpenMM libraries and test programs will be created. This takes some
time.
#. The test program TestCudaRandom might not build on Windows. This is OK.
On Windows systems, use the C++ compiler in Visual Studio 2015 or later. You
can download a free version of Visual Studio from https://visualstudio.microsoft.com.
Mac and Linux Python
============= ------
* Type :code:`make` in the openmm_build directory. 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.
The OpenMM libraries and test programs will be created. This takes some time. CMake
-----
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/.
Step 4: Install OpenMM OpenMM Source Code
********************** ------------------
You will also need the OpenMM source code. To download it:
Windows #. 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.
In the Solution Explorer Panel, far-click/right-click INSTALL->build. 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.
Mac and Linux CUDA or OpenCL Support
============= ----------------------
Type: 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.
make install Other Required Software
-----------------------
If you are installing to a system area, such as /usr/local/openmm/, you will Several other tools are required to build OpenMM. The easiest way to install
need to type: 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.
:: ::
sudo make install conda install -c conda-forge cython swig fftw doxygen numpy
Step 5: Install the Python API Step 1: Configure with CMake
****************************** ============================
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:
Windows .. code-block:: none
=======
In the Solution Explorer Panel, right-click PythonInstall->build. mkdir build
cd build
"C:\Program Files\CMake\bin\cmake-gui.exe"
Mac and Linux 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.
Type: #. 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
make PythonInstall 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".
If you are installing into the system Python, such as /usr/bin/python, you will There are several variables that can be adjusted in the CMake interface:
need to type:
::
sudo make PythonInstall
.. _test-your-build: * 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
OPENCL_LIBRARY to point to the library (usually "C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v11.4/lib/x64/OpenCL.lib").
Step 6: Test your build Press "Configure" again. Adjust any variables that cause an error.
***********************
After OpenMM has been built, you should run the unit tests to make sure it Continue to press "Configure" until no red CMake variables are displayed, then
works. press "Generate" to create the Visual Studio project files for building OpenMM.
Windows Step 2: Build and Install
======= =========================
In Visual Studio, far-click/right-click RUN_TESTS in the Solution Explorer #. Open the file :file:`OpenMM.sln` in your build directory in Visual Studio.
Panel. Select RUN_TESTS->build to begin testing. Ignore any failures for Note that this file will appear as just :file:`OpenMM` if you have configured
TestCudaRandom. 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".
Mac and Linux Step 3: Install the Python API
============= ==============================
Type: In the Solution Explorer, right-click on "PythonInstall" and select "Build".
::
make test Step 4: Test your build
=======================
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".
You should see a series of test results like this: You should see a series of test results like this:
::
.. code-block:: none
Start 1: TestReferenceAndersenThermostat Start 1: TestReferenceAndersenThermostat
1/317 Test #1: TestReferenceAndersenThermostat .............. Passed 0.26 sec 1/317 Test #1: TestReferenceAndersenThermostat .............. Passed 0.26 sec
...@@ -322,72 +326,57 @@ You should see a series of test results like this: ...@@ -322,72 +326,57 @@ You should see a series of test results like this:
... <many other tests> ... ... <many other tests> ...
:code:`Passed` is good. :code:`FAILED` is bad. If any tests fail, you :code:`Passed` is good. :code:`FAILED` is bad. If any tests fail, you
can run them individually to get more detailed error information. Note that can run them individually to get more detailed error information. Right-click
some tests are stochastic, and therefore are expected to fail a small fraction on a test in the Solution Explorer and select "Debug > Start New Instance".
of the time. These tests will say so in the error message:
::
./TestReferenceLangevinIntegrator 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
exception: Assertion failure at TestReferenceLangevinIntegrator.cpp:129. Expected 9.97741, exception: Assertion failure at TestReferenceLangevinIntegrator.cpp:129. Expected 9.97741,
found 10.7884 (This test is stochastic and may occasionally fail) found 10.7884 (This test is stochastic and may occasionally fail)
Congratulations! You successfully have built and installed OpenMM from source. Congratulations! You have successfully built and installed OpenMM from source.
Building the Documentation (Optional) Building the Documentation (Optional)
************************************* *************************************
The documentation that you're currently reading, as well as the developer guide and API The documentation that you're currently reading, as well as the Developer Guide and API
documentation can be built through CMake by setting the OpenMM option :code:`OPENMM_GENERATE_API_DOCS=ON`. documentation, can be built through CMake. To do that, you need to install a few
additional tools. The easiest way is to use :code:`pip` to install them into
User Guide and Developer Guide your Python environment. The following command installs everything needed to
============================== build documentation in HTML format.
::
Generating the user guide and developer guide requires the following dependencies
* Sphinx (http://sphinx-doc.org/)
* sphinxcontrib-bibtex (https://pypi.python.org/pypi/sphinxcontrib-bibtex)
These dependencies may not be available in your system package manager, but should
be installable through Python's ``pip`` package manager. ::
pip install sphinx sphinxcontrib-bibtex
The developer and user guides can be built either as HTML or a PDFs. Building the
PDF version will also require a functional LaTeX installation.
To build the HTML version of the documentation, type: ::
make sphinxhtml
To build the PDF version of the documentation, type: ::
make sphinxpdf
Python and C++ API Documentation
================================
The following dependencies are required to build the Python and C++ API documentation. pip install sphinx sphinxcontrib-bibtex sphinxcontrib-lunrsearch sphinxcontrib-autodoc_doxygen jinja2
* Sphinx (http://sphinx-doc.org/) 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.
* sphinxcontrib-lunrsearch (https://pypi.python.org/pypi/sphinxcontrib-lunrsearch) If you want to build documentation, make sure that OPENMM_GENERATE_API_DOCS is
set to ON when configuring the build in CMake.
* sphinxcontrib-autodoc_doxygen (https://pypi.python.org/pypi/sphinxcontrib-autodoc_doxygen) To build the documentation, use the following build targets.
* :code:`sphinxhtml`: Build the User Guide and Developer Guide in HTML format.
These dependencies may not be available in your system package manager, but should * :code:`sphinxpdf`: Build the User Guide and Developer Guide in PDF format.
be installable through Python's ``pip`` package manager. ::
pip install sphinx sphinxcontrib-lunrsearch sphinxcontrib-autodoc_doxygen * :code:`C++ApiDocs`: Build the C++ API documentation.
To build the C++ API documentation, type: :: * :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`.
make C++ApiDocs On Linux or Mac, build a target using the :code:`make` command. For example,
::
To build the Python API documentation, type: :: make sphinxhtml
make PythonApiDocs On Windows, right-click on the target in the Solution Explorer and select "Build".
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).
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment