.. _compiling-openmm-from-source-code: 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. Prerequisites ************* Before building OpenMM from source, you will need the following: * A C++ compiler * CMake * OpenMM source code See the sections below for specific instructions for the different platforms. Get a 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 ---------------------- 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. 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. Get the OpenMM source code ========================== You will also need the OpenMM source code before building OpenMM from source. To download and unpack OpenMM source code: #. Browse to https://simtk.org/home/openmm. #. Click the "Downloads" link in the navigation bar on the left side. #. Download OpenMM-Source.zip, choosing the latest version. #. Unpack the zip 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 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. * For compiling the CUDA Platform, you need: * CUDA (See Chapter :numref:`installing-openmm` for installation instructions.) * For compiling the OpenCL Platform, you need: * OpenCL (See Chapter :numref:`installing-openmm` for installation instructions.) * For compiling C and Fortran API wrappers, you need: * Python 2.7 or later (http://www.python.org) * Doxygen (http://www.doxygen.org) * A Fortran compiler * For compiling the Python API wrappers, you need: * Python 2.7 or later (http://www.python.org) * SWIG (http://www.swig.org) * Doxygen (http://www.doxygen.org) * Cython (https://cython.org) * For compiling the CPU platform, you need: * FFTW, single precision multithreaded version (http://www.fftw.org) * To generate API documentation, you need: * Doxygen (http://www.doxygen.org) Step 1: Configure with CMake **************************** Build and source directories ============================ 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. 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. Starting CMake ============== Configuration is the first step of the CMake build process. In the configuration step, the values of important build variables will be established. Mac and Linux ------------- On Mac and Linux machines, type the following two lines: :: cd build_openmm ccmake -i 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 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. Configure (press “c”) again. Adjust any variables that cause an error. Continue to configure (press “c”) until no starred/red CMake variables are displayed. Congratulations, you have completed the configuration step. Step 2: Generate Build Files with CMake *************************************** 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. Windows ======= * Press the "OK" or “Generate” button to generate Visual Studio project files. * If CMake does not exit automatically, press the close button in the upper- right corner of the CMake title bar to exit. Mac and Linux ============= * Press “g” to generate the Makefile. * If CMake does not exit automatically, press “q” to exit. That’s it! Generation is the easy part. Now it’s time to build. Step 3: Build OpenMM ******************** Windows ======= #. 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. Mac and Linux ============= * Type :code:`make` in the openmm_build directory. The OpenMM libraries and test programs will be created. This takes some time. Step 4: Install OpenMM ********************** Windows ======= In the Solution Explorer Panel, far-click/right-click INSTALL->build. Mac and Linux ============= Type: :: make install If you are installing to a system area, such as /usr/local/openmm/, you will need to type: :: sudo make install Step 5: Install the Python API ****************************** Windows ======= In the Solution Explorer Panel, right-click PythonInstall->build. Mac and Linux ============= Type: :: make PythonInstall If you are installing into the system Python, such as /usr/bin/python, you will need to type: :: sudo make PythonInstall .. _test-your-build: Step 6: Test your build *********************** After OpenMM has been built, you should run the unit tests to make sure it works. Windows ======= 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. Mac and Linux ============= Type: :: make test You should see a series of test results like this: :: 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 ... ... :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: :: ./TestReferenceLangevinIntegrator 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. 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 following dependencies are required to build the Python and C++ API documentation. * Sphinx (http://sphinx-doc.org/) * sphinxcontrib-lunrsearch (https://pypi.python.org/pypi/sphinxcontrib-lunrsearch) * sphinxcontrib-autodoc_doxygen (https://pypi.python.org/pypi/sphinxcontrib-autodoc_doxygen) 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-lunrsearch sphinxcontrib-autodoc_doxygen To build the C++ API documentation, type: :: make C++ApiDocs To build the Python API documentation, type: :: make PythonApiDocs