1 stable release
|7.4.1||Aug 20, 2020|
#12 in Simulation
This crate provides
bindgen-generated declarations for the C API wrapper of OpenMM, optionally building static / dynamic libraries from its source code. The build step is highly configurable, exposing the most important OpenMM CMake options to the library consumer through Cargo features and / or environment variables.
OpenMM is a toolkit for molecular simulation. It can be used either as a stand-alone application for running simulations, or as a library you call from your own code. It provides a combination of extreme flexibility (through custom forces and integrators), openness, and high performance (especially on recent GPUs) that make it truly unique among simulation codes.
This crate needs the following programs installed and available on your system:
- C / C++ compiler (the platform defaults work best: MSVC on Windows, GCC on Linux and Clang on macOS)
The simplest installation can be achieved by simply adding the following to
[dependencies] openmm-sys = "7.4"
That's it! The installation is fully self-contained. However, building the OpenMM libraries can be a bit time-consuming - on the author's machine (mid 2012 MacBook Pro) it takes 3-5 minutes. To see the CMake build steps as it runs, use the
-vv (very verbose) when building using Cargo:
cargo build -vv
The good news is you can copy / move the installation folder (printed during compilation) somewhere else and set the
OPENMM_HOME environment variable to point to its location. Take this terminal output as an example:
$> cargo build -vv <Elided CMake output> warning: [OpenMM-sys] Dynamically linking against the OpenMM library. warning: [OpenMM-sys] The OpenMM library was built and installed in `/Users/andreinicusan/openmm-rust/openmm-sys/target/debug/build/openmm-sys-0e32f8f9e5febd89/out`. You can copy / move that directory somewhere else and set the `OPENMM_HOME` environment variable to point to its path. This way, the OpenMM library will no longer require building.
Copy the file from the path shown and set
$> mkdir ~/openmm $> cp -r /Users/andreinicusan/openmm-rust/openmm-sys/target/debug/build/openmm-sys-0e32f8f9e5febd89/out ~/openmm $> export OPENMM_HOME=/Users/andreinicusan/openmm-rust/openmm-sys/target/debug/build/openmm-sys-0e32f8f9e5febd89/out
Future Rust crates will use the OpenMM installation from
OPENMM_HOME instead of compiling its source code - improving compilation times tremendously!
The directory tree pointed at by
OPENMM_HOME should look something like this:
$OPENMM_HOME ├── bin ├── build ├── docs ├── examples ├── include ├── lib │ ├── libOpenMM.dylib │ ├── libOpenMMAmoeba.dylib │ ├── libOpenMMAmoeba_static.a │ ├── libOpenMMDrude.dylib │ ├── libOpenMMDrude_static.a │ ├── libOpenMMRPMD.dylib │ ├── libOpenMMRPMD_static.a │ ├── libOpenMM_static.a │ └── plugins └── licenses
The actual OpenMM libraries reside in
$> conda install -c omnia -c conda-forge openmm
The downside of this approach is that you now need to locate where the OpenMM libraries were installed, so you can set
OPENMM_HOME. For example, on the author's machine, running
which python produces:
$> which python /usr/local/anaconda3/envs/openmm_env/bin/python
Popping the last two components from that path should yield a location which contains
lib and the required OpenMM libraries:
By default, OpenMM's CMake installer will check which platforms are available and build all plugins for those. For example, if CUDA is available on your system and the AMOEBA plugin is going to be built (
OPENMM_BUILD_AMOEBA_PLUGIN = "ON" in CMake), the CUDA implementation is also included by default (
OPENMM_BUILD_AMOEBA_CUDA_LIB = "ON"). The most important features available can be cherry-picked from this crate, as shown below.
Besides setting the
OPENMM_HOME environment variable, there are a few other settings that are easy to configure in
[dependencies.openmm-sys] features = ["static-lib", "cuda"]
In this case, OpenMM is built and used as a static library, including the CUDA platform. Here is the complete list of available features:
shared-lib- build shared (dynamic) OpenMM libraries.
static-lib- build static OpenMM libraries and link against them. If both
static_libare checked, they are built together, but your crate will link against the static library.
no-default- turn off all OpenMM CMake options. You can use this for cherry-picking individual features that you want compiled.
minimal- does not build any plugins, examples, API docs or Python wrappers.
cpu- build optimized CPU platform.
opencl- build the OpenMMOpenCL library.
cuda- build OpenMMCuda library for Nvidia GPUs.
amoeba- build Amoeba plugin.
drude- build Drude plugin.
pme- build PME plugin.
rpmd- build RPMD plugin.
examples- build included OpenMM examples.
generate-api-docs- generate Doxygen-based documentation.
c-and-fortran-wrappers- build C and Fortran wrappers. Essential if you want to use this crate, as it uses the C API.
Note: we cannot build the Python wrapper in this crate as packaging the required OpenMM source code exceeds crates.io's limit of 10 MB per crate. If you need the Python wrapper, please use another installation path (
conda, compiling from source, etc.).
The build step can be further configured using some environment variables:
OPENMM_CMAKE_OPTIONS- this can contain space-separated
key=valuepairs that will be passed down to
OPENMM_BUILD_CUDA_LIB=ON PYTHON_EXECUTABLE=usr/bin/python). You can run
cmake -LA <openmm_source_dir>to see the full list of available options.
CXXSTDLIB- sometimes the location of the C++ standard library shared-lib needs to be explicitly given to the linker. For reasons beyond me, the name varies between compilers (e.g. "libc++" for Clang and "libstdc++" for GCC). Set this environment variable to override the default platform-dependent option.
Finally, you can compile OpenMM yourself using CMake. Even more information (and perhaps better explained than me) is provided by OpenMM's authors on their website - see the "Compiling OpenMM from Source Code" section.
Take a look in the
examples/ folder for some low-level use of OpenMM from Rust. Note that it uses OpenMM's C Wrapper, so all functions calls must be
unsafe - see the
openmm-rust crate for a safe, higher-level API.
The first two digits of this crate's version correspond to the latest minor version of
OpenMM, while the last digit corresponds to patches to this crate. For example,
openmm-sys version 7.4.0 corresponds to
OpenMM 7.4.2 (the latest at the time of writing).
If you are interested in having Rust wrappers for a different
OpenMM version, by all means contact me at a.l.nicusan <at> bham.ac.uk.
The shell script used to generate the Rust bindings to OpenMM's C Wrapper is included in
src/bindings, along with the wrapper itself.
This crate is MIT-licensed. See the
openmm/docs-source/licenses directory for OpenMM's licenses.
All credit goes to Dr. Peter Eastman, OpenMM's authors, the Stanford Pande lab and Stanford University for this amazing piece of software. If you used OpenMM in any of your work please cite the following publication:
P. Eastman, J. Swails, J. D. Chodera, R. T. McGibbon, Y. Zhao, K. A. Beauchamp, L.-P. Wang, A. C. Simmonett, M. P. Harrigan, C. D. Stern, R. P. Wiewiora, B. R. Brooks, and V. S. Pande. “OpenMM 7: Rapid development of high performance algorithms for molecular dynamics.” PLOS Comp. Biol. 13(7): e1005659. (2017)