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 @@
Compiling OpenMM from Source Code
#################################
This chapter describes the procedure for building and installing OpenMM
libraries from source code. It is recommended that you use binary OpenMM
libraries, if possible. If there are not suitable binary libraries for your
system, consider building OpenMM from source code by following these
instructions.
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.
Prerequisites
*************
Before building OpenMM from source, you will need the following:
* A C++ compiler
We first describe how to build on Linux or Mac. We then describe how to build
on Windows, where the process is slightly different.
* CMake
* OpenMM source code
Compiling on Linux and Mac
**************************
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
source.
Mac and Linux: 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
----------------------
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.
On Windows systems, use the C++ compiler in Visual Studio 2015 or later. You
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.
Python
------
Install CMake
=============
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.
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.
Get the OpenMM source code
==========================
OpenMM Source Code
------------------
You will also need the OpenMM source code before building OpenMM from source.
To download and unpack OpenMM source code:
You will also need the OpenMM source code. To download it:
#. Browse to https://simtk.org/home/openmm.
#. Click the "Downloads" link in the navigation bar on the left side.
#. Download OpenMM<Version>-Source.zip, choosing the latest version.
#. Unpack the zip file. Note the location where you unpacked the OpenMM source
code.
#. 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.
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/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
you want a stable, well tested version of OpenMM, you should download the source
code for the latest release as described above.
Other Required Software
=======================
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.
CUDA or OpenCL Support
----------------------
* 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)
* Doxygen (http://www.doxygen.org)
* A Fortran compiler
Step 1: Configure with CMake
============================
* 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)
* SWIG (http://www.swig.org)
* Doxygen (http://www.doxygen.org)
* Cython (https://cython.org)
.. code-block:: none
* 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
directory is build_openmm. We will refer to this as the “build_openmm
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.
If you are installing to a system area, such as /usr/local/openmm/, you will
need to type::
Also note the location of the OpenMM source directory (i.e., where you unpacked
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.
sudo make install
Starting CMake
==============
Step 3: Install the Python API
==============================
Configuration is the first step of the CMake build process. In the
configuration step, the values of important build variables will be established.
Build and install the Python API with the command::
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
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:
sudo make PythonInstall
* If you intend to use CUDA (NVIDIA) or OpenCL acceleration, set the variable
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.
.. _test-your-build:
Step 4: Test your build
=======================
Configure (press “c”) again. Adjust any variables that cause an
error.
After OpenMM has been built, you should run the unit tests to make sure it
works. Enter the command::
Continue to configure (press “c”) until no starred/red CMake
variables are displayed. Congratulations, you have completed the configuration
step.
make test
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
“g” or “OK” or “Generate” option will not be available until
configuration has completely converged.
.. code-block:: none
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-
right corner of the CMake title bar to exit.
./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:
Mac and Linux
=============
.. code-block:: none
* Press “g” to generate the Makefile.
* If CMake does not exit automatically, press “q” to exit.
exception: Assertion failure at TestReferenceLangevinIntegrator.cpp:129. Expected 9.97741,
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.
#. 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.
C++ compiler
------------
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
need to type:
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.
::
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:
::
make PythonInstall
#. 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".
If you are installing into the system Python, such as /usr/bin/python, you will
need to type:
::
sudo make PythonInstall
There are several variables that can be adjusted in the CMake interface:
.. _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
works.
Continue to press "Configure" until no red CMake variables are displayed, then
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
Panel. Select RUN_TESTS->build to begin testing. Ignore any failures for
TestCudaRandom.
#. 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".
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:
::
.. code-block:: none
Start 1: TestReferenceAndersenThermostat
1/317 Test #1: TestReferenceAndersenThermostat .............. Passed 0.26 sec
......@@ -322,72 +326,57 @@ You should see a series of test results like this:
... <many other tests> ...
: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
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:
::
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".
./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,
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)
*************************************
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`.
User Guide and Developer Guide
==============================
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 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
additional tools. The easiest way is to use :code:`pip` to install them into
your Python environment. The following command installs everything needed to
build documentation in HTML format.
::
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
be installable through Python's ``pip`` package manager. ::
* :code:`sphinxpdf`: Build the User Guide and Developer Guide in PDF format.
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