Commit 3e33b09e authored by Evan Pretti's avatar Evan Pretti
Browse files

Move example files and update README files

parent 346d3ce3
......@@ -4,13 +4,33 @@
## OpenMM: A High Performance Molecular Dynamics Library
Introduction
------------
### Introduction
[OpenMM](http://openmm.org) 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.
Getting Help
------------
### Getting Help
Need Help? Check out the [documentation](http://docs.openmm.org/) and [discussion forums](https://simtk.org/forums/viewforum.php?f=161).
Need help using OpenMM? There are several places that you can find it:
- [Documentation](http://docs.openmm.org/):
- [User Manual](https://docs.openmm.org/latest/userguide/)
- [Python API Reference](https://docs.openmm.org/latest/api-python/)
- [C++ API Reference](https://docs.openmm.org/latest/api-c++/)
- [Getting Support](SUPPORT.md):
- [Frequently Asked Questions](https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions)
- [Discussion Forum](https://github.com/openmm/openmm/discussions)
- [Issue Tracker](https://github.com/openmm/openmm/issues)
- [Learning Resources](https://openmm.github.io/openmm-cookbook/latest):
- [OpenMM Tutorials](https://openmm.github.io/openmm-cookbook/latest/tutorials)
- [OpenMM Cookbook](https://openmm.github.io/openmm-cookbook/latest/cookbook)
- [OpenMM Examples](examples/README.md)
- [Contributing to OpenMM](CONTRIBUTING.md):
- [Developer Guide](https://docs.openmm.org/latest/developerguide/)
### License Information
OpenMM is free and open-source software. There are several licenses which cover
different parts of OpenMM, but most of the source code is covered by the MIT
license or the GNU Lesser General Public License (LGPL). Portions copyright
© 2008-2025 Stanford University and the Authors. For more details, see
[Licenses.txt](docs-source/licenses/Licenses.txt).
## How to Get Support for OpenMM
There are two main venues for getting support for OpenMM: the [discussion forum](https://simtk.org/forums/viewforum.php?f=161)
and the [Github repository](https://github.com/openmm/openmm). There is some overlap
There are two main venues for getting support for OpenMM: the GitHub
[discussion forum](https://github.com/openmm/openmm/discussions) and the
[issue tracker](https://github.com/openmm/openmm/issues). There is some overlap
between the two, but generally speaking the forum is for user oriented issues while the
repository is for developer oriented issues. If you have a question about how to use OpenMM
issue tracker is for developer oriented issues. If you have a question about how to use OpenMM
(including writing programs that access it through its public API), post on the forum. If
you want to suggest a change to the code, or if you think you have found a bug,
open an issue on Github. The core developers monitor both, so don't worry if you aren't
open an issue. The core developers monitor both, so don't worry if you aren't
sure which one is most appropriate for your question. We will see it either way.
You also may want to consult the [documentation](http://docs.openmm.org/). It is quite
......
OpenMM was developed by Simbios, the NIH National Center for Physics-Based
Simulation of Biological Structures at Stanford, funded under the NIH Roadmap
for Medical Research, grant U54 GM072970. See https://simtk.org.
OpenMM was originally developed by Simbios, the NIH National Center for
Physics-Based Simulation of Biological Structures at Stanford, funded under the
NIH Roadmap for Medical Research, grant U54 GM072970. Currently, OpenMM is
developed and maintained by various researchers and developers: for more
information, see <https://openmm.org/development>.
Portions copyright 2008-2019 Stanford University and the Authors.
Portions copyright © 2008-2025 Stanford University and the Authors.
There are several licenses which cover different parts of OpenMM as described
below.
......
.. _openmm-tutorials:
OpenMM C++ API Tutorial Examples
################################
OpenMM C++ API Examples
#######################
This chapter describes examples provided with OpenMM demonstrating how to use
the OpenMM C++ API (as well as the C and Fortran API wrappers).
Example Files Overview
**********************
......
# Generate and install examples.
#
# This is boilerplate code for generating a set of executables, one per
# .cpp file in an "examples" subdirectory.
#
# For IDEs that can deal with PROJECT_LABEL properties (at least
# Visual Studio) the projects for building each of these adhoc
# executables will be labeled "Example - TheExampleName" if a file
# TheExampleName.cpp is found in this directory.
#
# We check the BUILD_TESTING_{SHARED,STATIC} variables to determine
# whether to build dynamically linked, statically linked, or both
# versions of the executable.
SET(OpenMM_CWRAPPER "OpenMMCWrapper")
SET(OpenMM_FWRAPPER "OpenMMFortranWrapper")
SET(OpenMM_FMODULE "OpenMMFortranModule")
SET(CPP_EXAMPLES HelloArgon HelloSodiumChloride HelloEthane HelloWaterBox )
SET(C_EXAMPLES HelloArgonInC HelloSodiumChlorideInC)
SET(F_EXAMPLES HelloArgonInFortran HelloSodiumChlorideInFortran)
FOREACH(EX_ROOT ${CPP_EXAMPLES})
IF (OPENMM_BUILD_SHARED_LIB)
# Link with shared library
ADD_EXECUTABLE(${EX_ROOT} ${EX_ROOT}.cpp)
SET_TARGET_PROPERTIES(${EX_ROOT}
PROPERTIES
PROJECT_LABEL "Example - ${EX_ROOT}"
LINK_FLAGS "${EXTRA_LINK_FLAGS}"
COMPILE_FLAGS "${EXTRA_COMPILE_FLAGS}")
TARGET_LINK_LIBRARIES(${EX_ROOT} ${SHARED_TARGET})
ENDIF (OPENMM_BUILD_SHARED_LIB)
IF (OPENMM_BUILD_STATIC_LIB)
# Link with static library
SET(EX_STATIC ${EX_ROOT}Static)
ADD_EXECUTABLE(${EX_STATIC} ${EX_ROOT}.cpp)
SET_TARGET_PROPERTIES(${EX_STATIC}
PROPERTIES
PROJECT_LABEL "Example - ${EX_STATIC}"
LINK_FLAGS "${EXTRA_LINK_FLAGS}"
COMPILE_FLAGS "${EXTRA_COMPILE_FLAGS} -DOPENMM_USE_STATIC_LIBRARIES")
TARGET_LINK_LIBRARIES(${EX_STATIC} ${STATIC_TARGET})
ENDIF (OPENMM_BUILD_STATIC_LIB)
INSTALL(FILES ${EX_ROOT}.cpp DESTINATION examples)
ENDFOREACH(EX_ROOT ${CPP_EXAMPLES})
# Only build wrapper examples if wrappers have been built
IF(OPENMM_BUILD_C_AND_FORTRAN_WRAPPERS)
INCLUDE_DIRECTORIES(BEFORE ${PROJECT_BINARY_DIR}/wrappers)
FOREACH(EX_ROOT ${C_EXAMPLES})
IF (OPENMM_BUILD_SHARED_LIB)
# Link with shared library
# We need at least one .cpp here to get CMake to include
# C++ libraries on the link line.
ADD_EXECUTABLE(${EX_ROOT} ${EX_ROOT}.c Empty.cpp)
SET_TARGET_PROPERTIES(${EX_ROOT}
PROPERTIES
PROJECT_LABEL "Example C - ${EX_ROOT}"
LINK_FLAGS "${EXTRA_LINK_FLAGS}"
COMPILE_FLAGS "${EXTRA_COMPILE_FLAGS}")
TARGET_LINK_LIBRARIES(${EX_ROOT} ${SHARED_TARGET})
ADD_DEPENDENCIES(${EX_ROOT} ApiWrappers)
ENDIF (OPENMM_BUILD_SHARED_LIB)
IF (OPENMM_BUILD_STATIC_LIB)
# Link with static library
SET(EX_STATIC ${EX_ROOT}Static)
# We need at least one .cpp here to get CMake to include
# C++ libraries on the static link line.
ADD_EXECUTABLE(${EX_STATIC} ${EX_ROOT}.c Empty.cpp)
SET_TARGET_PROPERTIES(${EX_STATIC}
PROPERTIES
PROJECT_LABEL "Example C - ${EX_STATIC}"
LINK_FLAGS "${EXTRA_LINK_FLAGS}"
COMPILE_FLAGS "${EXTRA_COMPILE_FLAGS} -DOPENMM_USE_STATIC_LIBRARIES")
TARGET_LINK_LIBRARIES(${EX_STATIC} ${STATIC_TARGET})
ADD_DEPENDENCIES(${EX_STATIC} ApiWrappers)
ENDIF (OPENMM_BUILD_STATIC_LIB)
ENDFOREACH(EX_ROOT ${C_EXAMPLES})
ENDIF(OPENMM_BUILD_C_AND_FORTRAN_WRAPPERS)
FOREACH(EX_ROOT ${C_EXAMPLES})
INSTALL(FILES ${EX_ROOT}.c DESTINATION examples)
ENDFOREACH(EX_ROOT ${C_EXAMPLES})
FOREACH(EX_ROOT ${F_EXAMPLES})
INSTALL(FILES ${EX_ROOT}.f90 DESTINATION examples)
ENDFOREACH(EX_ROOT ${F_EXAMPLES})
INSTALL(FILES simulateAmber.py simulatePdb.py simulateGromacs.py benchmark.py argon-chemical-potential.py input.inpcrd input.prmtop input.pdb input.gro input.top 5dfr_minimized.pdb 5dfr_solv-cube_equil.pdb apoa1.pdb
DESTINATION examples)
INSTALL(FILES VisualStudio/HelloArgon.vcproj
VisualStudio/HelloArgon.sln
VisualStudio/HelloArgonInC.sln
VisualStudio/HelloArgonInC.vcproj
VisualStudio/HelloArgonInFortran.sln
VisualStudio/HelloArgonInFortran.vfproj
DESTINATION examples/VisualStudio)
INSTALL(FILES README.txt DESTINATION examples)
INSTALL(FILES Makefile NMakefile DESTINATION examples)
INSTALL(FILES MakefileNotes.txt Empty.cpp DESTINATION examples)
ADD_SUBDIRECTORY(cpp-examples)
ADD_SUBDIRECTORY(python-examples)
## OpenMM Examples
This directory contains various simple examples demonstrating the use of the
OpenMM Python and C++ APIs.
### Python API examples
The examples in `python-examples` demonstrate how to get a simple simulation up
and running using the OpenMM Python API application layer. The way of using
OpenMM illustrated here is primarily geared towards running biomolecular
simulations, but can be used for any kind of simulation that is to be set up by
reading from:
- Amber format files (see `python-examples/simulateAmber.py`)
- CHARMM format files (see `python-examples/simulateCharmm.py`)
- GROMACS format files (see `python-examples/simulateGromacs.py`)
- PDB (Protein Data Bank) files (to be used with OpenMM-compatible force fields; see `python-examples/simulatePdb.py`)
### C++ API examples
The examples in `cpp-examples` demonstrate the use of OpenMM's C++ API, and also
show how to use its C and Fortran bindings. For more information, see
[the README file](cpp-examples/README.md) in this subdirectory.
### Extras
You can also find:
- [Extra utility scripts](extras/README.md) in `extras`
- A suite of benchmarks for OpenMM in `Benchmarks`
----------------------------------------------------------------
OpenMM(tm) Example programs for OpenMM 4.0, November 2011.
See https://simtk.org/home/openmm.
For help go to the Advanced/Public Forums tab and post to the
"help" forum there.
OpenMM is part of SimTK, the Simbios simulation Toolkit, from
the Simbios National Center for Physics-based Simulation of
Biological Structures funded by the National Institutes of Health
through the NIH Roadmap for Medical Research, Grant U54 GM072970.
Information on the National Centers for Biomedical Computing can
be obtained here: https://commonfund.nih.gov/bioinformatics.
OpenMM is developed under the supervision of Simbios P.I. Vijay
Pande at Stanford. Any work that uses OpenMM should cite the
following paper: M. S. Friedrichs, P. Eastman, V. Vaidyanathan,
M. Houston, S. LeGrand, A. L. Beberg, D. L. Ensign, C. M. Bruns,
V. S. Pande. �Accelerating Molecular Dynamic Simulation on
Graphics Processing Units.� J. Comp. Chem., (2009), 30(6):864-872.
These simple "hello world" examples were developed by
Christopher Bruns and Michael Sherman.
----------------------------------------------------------------
OpenMM's native API is in C++, however it also comes with
automatically-generated C and Fortran 95 bindings for that API.
However, even if your calling code is in C or Fortran,
please consider instead writing your OpenMM-calling routines in
C++, using 'extern "C"' so that your main program can call them.
If that isn't feasible for you, you can use the C or Fortran 95
bindings.
Building the examples
---------------------
This directory includes a Makefile suitable for building the
examples under Mac or Linux and possibly Cygwin, using the
gcc compiler suite. See MakefileNotes.txt for more info.
There is a file "NMakefile" which can be used with Microsoft's
NMake program to build the examples using Microsoft's "cl" compiler
for C++ and C, and Intel's "ifort" Fortran compiler.
There is a subdirectory here providing Visual Studio "solutions"
for building HelloArgon in C++, C, and Fortran. You will have to
make your own for the other examples or just substitute a different
source file for HelloArgon.
HelloArgon (C++, C, Fortran 95)
-------------------------------
This is the simplest example we could come up with that
does anything interesting. It is three argon atoms interacting
in a vacuum via van der Waals forces. It is primarily so you can
check that you are able to compile, link, and run correctly with
OpenMM. You will also get a many-frame pdb file generated
which you can view as an animation in VMD or most other
molecular viewers.
HelloSodiumChloride (C++, C, Fortran 95)
----------------------------------------
This example shows how we recommend using OpenMM so that you
can call it from an existing Molecular Dynamics code with
minimal disruption. The example contains Coulomb and van der
Waals interactions and implicit solvation in a constant
temperature simulation.
HelloEthane (C++ only)
----------------------
This example shows how to convey bond information to
OpenMM. It is organized similarly to HelloSodiumChloride.
HelloWaterBox (C++ only)
------------------------
This example shows use of explicit solvent in a periodic box.
It is organized like the previous two.
C Wrapper
---------
The folling header file is available in the OpenMM/include
directory (where you installed OpenMM):
OpenMMCWrapper.h
The C functions it declares are built in to the main OpenMM
library that you link with. If you are building your own
OpenMM, be sure to enable the OPENMM_BUILD_API_WRAPPERS
CMake option.
Your C code (and the C examples above) include the header file
and link with the OpenMM library.
Consult the code or the example programs to figure out how
to use the wrappers; they are for the most part a very
straightforward rehashing of the well-documented OpenMM C++
API.
Fortran Wrapper
---------------
The file that defines the OpenMM Fortran bindings is in the
OpenMM/include directory (where you installed OpenMM):
OpenMMFortranModule.f90
You have to compile this .f90 file yourself so that you
get appropriate OpenMM*.mod module files. This allows your
Fortran program units to have "use OpenMM" statements.
The functions described there are built in to the main OpenMM
library that you link with. If you are building your own
OpenMM, be sure to enable the OPENMM_BUILD_API_WRAPPERS
CMake option.
# Generate and install C++, C, and Fortran examples.
#
# This is boilerplate code for generating a set of executables, one per
# .cpp file in the "cpp-examples" subdirectory.
#
# For IDEs that can deal with PROJECT_LABEL properties (at least
# Visual Studio) the projects for building each of these adhoc
# executables will be labeled "Example - TheExampleName" if a file
# TheExampleName.cpp is found in this directory.
#
# We check the BUILD_TESTING_{SHARED,STATIC} variables to determine
# whether to build dynamically linked, statically linked, or both
# versions of the executable.
SET(OpenMM_CWRAPPER "OpenMMCWrapper")
SET(OpenMM_FWRAPPER "OpenMMFortranWrapper")
SET(OpenMM_FMODULE "OpenMMFortranModule")
SET(CPP_EXAMPLES HelloArgon HelloSodiumChloride HelloEthane HelloWaterBox)
SET(C_EXAMPLES HelloArgonInC HelloSodiumChlorideInC)
SET(F_EXAMPLES HelloArgonInFortran HelloSodiumChlorideInFortran)
FOREACH(EX_ROOT ${CPP_EXAMPLES})
IF (OPENMM_BUILD_SHARED_LIB)
# Link with shared library
ADD_EXECUTABLE(${EX_ROOT} ${EX_ROOT}.cpp)
SET_TARGET_PROPERTIES(${EX_ROOT}
PROPERTIES
PROJECT_LABEL "Example - ${EX_ROOT}"
LINK_FLAGS "${EXTRA_LINK_FLAGS}"
COMPILE_FLAGS "${EXTRA_COMPILE_FLAGS}")
TARGET_LINK_LIBRARIES(${EX_ROOT} ${SHARED_TARGET})
ENDIF (OPENMM_BUILD_SHARED_LIB)
IF (OPENMM_BUILD_STATIC_LIB)
# Link with static library
SET(EX_STATIC ${EX_ROOT}Static)
ADD_EXECUTABLE(${EX_STATIC} ${EX_ROOT}.cpp)
SET_TARGET_PROPERTIES(${EX_STATIC}
PROPERTIES
PROJECT_LABEL "Example - ${EX_STATIC}"
LINK_FLAGS "${EXTRA_LINK_FLAGS}"
COMPILE_FLAGS "${EXTRA_COMPILE_FLAGS} -DOPENMM_USE_STATIC_LIBRARIES")
TARGET_LINK_LIBRARIES(${EX_STATIC} ${STATIC_TARGET})
ENDIF (OPENMM_BUILD_STATIC_LIB)
INSTALL(FILES ${EX_ROOT}.cpp DESTINATION examples/cpp-examples)
ENDFOREACH(EX_ROOT ${CPP_EXAMPLES})
# Only build wrapper examples if wrappers have been built
IF(OPENMM_BUILD_C_AND_FORTRAN_WRAPPERS)
INCLUDE_DIRECTORIES(BEFORE ${PROJECT_BINARY_DIR}/wrappers)
FOREACH(EX_ROOT ${C_EXAMPLES})
IF (OPENMM_BUILD_SHARED_LIB)
# Link with shared library
# We need at least one .cpp here to get CMake to include
# C++ libraries on the link line.
ADD_EXECUTABLE(${EX_ROOT} ${EX_ROOT}.c Empty.cpp)
SET_TARGET_PROPERTIES(${EX_ROOT}
PROPERTIES
PROJECT_LABEL "Example C - ${EX_ROOT}"
LINK_FLAGS "${EXTRA_LINK_FLAGS}"
COMPILE_FLAGS "${EXTRA_COMPILE_FLAGS}")
TARGET_LINK_LIBRARIES(${EX_ROOT} ${SHARED_TARGET})
ADD_DEPENDENCIES(${EX_ROOT} ApiWrappers)
ENDIF (OPENMM_BUILD_SHARED_LIB)
IF (OPENMM_BUILD_STATIC_LIB)
# Link with static library
SET(EX_STATIC ${EX_ROOT}Static)
# We need at least one .cpp here to get CMake to include
# C++ libraries on the static link line.
ADD_EXECUTABLE(${EX_STATIC} ${EX_ROOT}.c Empty.cpp)
SET_TARGET_PROPERTIES(${EX_STATIC}
PROPERTIES
PROJECT_LABEL "Example C - ${EX_STATIC}"
LINK_FLAGS "${EXTRA_LINK_FLAGS}"
COMPILE_FLAGS "${EXTRA_COMPILE_FLAGS} -DOPENMM_USE_STATIC_LIBRARIES")
TARGET_LINK_LIBRARIES(${EX_STATIC} ${STATIC_TARGET})
ADD_DEPENDENCIES(${EX_STATIC} ApiWrappers)
ENDIF (OPENMM_BUILD_STATIC_LIB)
ENDFOREACH(EX_ROOT ${C_EXAMPLES})
ENDIF(OPENMM_BUILD_C_AND_FORTRAN_WRAPPERS)
FOREACH(EX_ROOT ${C_EXAMPLES})
INSTALL(FILES ${EX_ROOT}.c DESTINATION examples/cpp-examples)
ENDFOREACH(EX_ROOT ${C_EXAMPLES})
FOREACH(EX_ROOT ${F_EXAMPLES})
INSTALL(FILES ${EX_ROOT}.f90 DESTINATION examples/cpp-examples)
ENDFOREACH(EX_ROOT ${F_EXAMPLES})
INSTALL(FILES VisualStudio/HelloArgon.vcproj
VisualStudio/HelloArgon.sln
VisualStudio/HelloArgonInC.sln
VisualStudio/HelloArgonInC.vcproj
VisualStudio/HelloArgonInFortran.sln
VisualStudio/HelloArgonInFortran.vfproj
DESTINATION examples/cpp-examples/VisualStudio)
INSTALL(FILES Makefile NMakefile Empty.cpp README.md DESTINATION examples/cpp-examples)
// -----------------------------------------------------------------------------
// OpenMM(tm) HelloArgon example in C++ (June 2009)
// OpenMM HelloArgon example in C++ (June 2009)
// -----------------------------------------------------------------------------
// This program demonstrates a simple molecular simulation using the OpenMM
// API for GPU-accelerated molecular dynamics simulation. The primary goal is
......
/* -----------------------------------------------------------------------------
* OpenMM(tm) HelloArgon example in C (June 2009)
* OpenMM HelloArgon example in C (June 2009)
* -----------------------------------------------------------------------------
* This program demonstrates a simple molecular simulation using the OpenMM
* API for GPU-accelerated molecular dynamics simulation. The primary goal is
......
! -----------------------------------------------------------------------------
! OpenMM(tm) HelloArgon example in Fortran 95 (June 2009)
! OpenMM HelloArgon example in Fortran 95 (June 2009)
! -----------------------------------------------------------------------------
! This program demonstrates a simple molecular simulation using the OpenMM
! API for GPU-accelerated molecular dynamics simulation. The primary goal is
......
/* -----------------------------------------------------------------------------
* OpenMM(tm) HelloEthane example in C++ (June 2009)
* OpenMM HelloEthane example in C++ (June 2009)
* -----------------------------------------------------------------------------
* This is a complete, self-contained "hello world" example demonstrating
* GPU-accelerated simulation of a system with both bonded and nonbonded forces,
......
// -----------------------------------------------------------------------------
// OpenMM(tm) HelloSodiumChloride example in C++ (June 2009)
// OpenMM HelloSodiumChloride example in C++ (June 2009)
// -----------------------------------------------------------------------------
// This is a complete, self-contained "hello world" example demonstrating
// GPU-accelerated constant temperature simulation of a very simple system with
......
/* -----------------------------------------------------------------------------
* OpenMM(tm) HelloSodiumChloride example in C (June 2009)
* OpenMM HelloSodiumChloride example in C (June 2009)
* -----------------------------------------------------------------------------
* This is a complete, self-contained "hello world" example demonstrating
* GPU-accelerated constant temperature simulation of a very simple system with
......
! -----------------------------------------------------------------------------
! OpenMM(tm) HelloSodiumChloride example in Fortran 95 (June 2009)
! OpenMM HelloSodiumChloride example in Fortran 95 (June 2009)
! ------------------------------------------------------------------------------
! This is a complete, self-contained "hello world" example demonstrating
! GPU-accelerated constant temperature simulation of a very simple system with
......
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