Merge pull request #5030 from epretti/cleanup-examples

Cleanup examples, documentation, and README files

.github/workflows/CI.yml

@@ -634,19 +634,19 @@ jobs:
         shell: bash -l {0}
         env:
           # Pipe-seperated list of domains to skip
-          SKIP_DOMAIN: support.amd.com|www.pnas.org|doi.org|commonfund.nih.gov
+          SKIP_DOMAIN: support.amd.com|www.pnas.org|doi.org|commonfund.nih.gov|openmm.org/development
         run: |
           set +e
           # Linkinator accepts regex for its --skip argument, so we
           # should pre-process the domains into the relevant pattern
           SKIP_REGEX=$(python -c "print(
-            '^(https?://)?([a-zA-Z0-9\-_.]+\.)?', # Optionally match protocol and subdomains
-            '(',                                  # Open sub-pattern for domain names
-              '$SKIP_DOMAIN'.replace('.', '\.'),     # Escape out periods
-            ')',                                  # Close sub-pattern of domains
-            '(/.*)?$',                            # only match if this is the end of the domain name
-            sep='',                               # Concatenate the above strings exactly
-            end=''                                # No newline at end of print()
+            r'^(https?://)?([a-zA-Z0-9\-_.]+\.)?', # Optionally match protocol and subdomains
+            '(',                                   # Open sub-pattern for domain names
+              '$SKIP_DOMAIN'.replace('.', r'\.'),  # Escape out periods
+            ')',                                   # Close sub-pattern of domains
+            '(/.*)?$',                             # only match if this is the end of the domain name
+            sep='',                                # Concatenate the above strings exactly
+            end=''                                 # No newline at end of print()
           )")
           for d in api-c++ api-python developerguide userguide; do
             echo "::group:: Check ${d}"

README.md

@@ -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
+[OpenMM](https://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](https://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).

SUPPORT.md

 ## 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
-thorough, and you may be able to find the answer to your question.
\ No newline at end of file
+You also may want to consult the [documentation](https://docs.openmm.org/).  It is quite
+thorough, and you may be able to find the answer to your question.

docs-source/api-c++/conf.py

@@ -21,7 +21,7 @@ source_suffix = ".rst"
 master_doc = "index"
 
 project = u"OpenMM C++ API"
-copyright = u"2015, Stanford University and the Authors"
+copyright = u"2015-2025, Stanford University and the Authors"
 
 version = "@OPENMM_MAJOR_VERSION@.@OPENMM_MINOR_VERSION@"
 release = "@OPENMM_MAJOR_VERSION@.@OPENMM_MINOR_VERSION@"

docs-source/api-python/conf.py

@@ -25,7 +25,7 @@ source_suffix = ".rst"
 master_doc = "index"
 
 project = u"OpenMM Python API"
-copyright = u"2015, Stanford University and the Authors"
+copyright = u"2015-2025, Stanford University and the Authors"
 
 version = openmm.version.short_version
 release = openmm.version.full_version

docs-source/developerguide/conf.py

@@ -51,7 +51,7 @@ master_doc = "index"
 
 # General information about the project.
 project = u"OpenMM Dev Guide"
-copyright = u"2011-2017, Stanford University"
+copyright = u"2011-2025, Stanford University"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs-source/developerguide/license.rst

-Portions copyright (c) 2011-2023 Stanford University and the Authors
+License
+*******
+
+Portions copyright (c) 2011-2025 Stanford University and the Authors
 
 Contributors: Peter Eastman
 
@@ -21,9 +24,8 @@ OUT OF OR IN CONNECTION WITH THE DOCUMENT OR THE USE OR OTHER DEALINGS IN THE
 DOCUMENT.
 
 Acknowledgments
+***************
 
-OpenMM software and all related activities, such as this manual, are funded by
-the Simbios National Center for Biomedical Computing through the National
-Institutes of Health Roadmap for Medical Research, Grant U54 GM072970.
-Information on the National Centers can be found at
-https://commonfund.nih.gov/bioinformatics.
+OpenMM research and development activities are supported by various individuals
+and funded from a number of sources: for up-to-date information, consult
+https://openmm.org/development.
\ No newline at end of file

docs-source/licenses/Licenses.txt

-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.

docs-source/usersguide/conf.py

@@ -59,7 +59,7 @@ master_doc = "index"
 
 # General information about the project.
 project = u"OpenMM User Guide"
-copyright = u"2008-2017, Stanford University"
+copyright = u"2008-2025, Stanford University"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs-source/usersguide/introduction.rst

@@ -25,8 +25,11 @@ Online Resources
 ****************
 
 You can find more documentation and other material at our website
-http://openmm.org.   Among other things there is a discussion forum,
-a wiki, and videos of lectures on using OpenMM.
+https://openmm.org/.  In particular, you may want to consult the
+`Python API documentation <https://docs.openmm.org/latest/api-python/>`__ or the
+`C++ API documentation <https://docs.openmm.org/latest/api-c++/>`__, read the
+`Frequently Asked Questions (FAQ) <https://github.com/openmm/openmm/wiki/Frequently-Asked-Questions>`__,
+or browse the `discussion forum on GitHub <https://github.com/openmm/openmm/discussions>`__.
 
 
 Referencing OpenMM
@@ -48,8 +51,6 @@ citations of our publication will help demonstrate the value of OpenMM.
 Acknowledgments
 ***************
 
-OpenMM software and all related activities, such as this manual, are funded by
-the Simbios National Center for Biomedical Computing through the National
-Institutes of Health Roadmap for Medical Research, Grant U54 GM072970, and by
-National Institutes of Health grant R01-GM062868.
-
+OpenMM research and development activities are supported by various individuals
+and funded from a number of sources: for up-to-date information, consult
+https://openmm.org/development.

docs-source/usersguide/library/03_tutorials.rst

 .. _openmm-tutorials:
 
-OpenMM Tutorials
-################
+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
 **********************
 
-Four example files are provided in the examples folder, each designed with
-a specific objective.
+Four example files are provided in the :code:`examples/cpp-examples` folder,
+each designed with a specific objective.
 
 * **HelloArgon:**  A very simple example intended for verifying that you
   have installed OpenMM correctly.  It also introduces you to the basic classes
@@ -246,7 +248,7 @@ and C examples.
 The Fortran compiler needs to load a version of the libstdc++.dylib library that
 is compatible with the version of gcc used to build OpenMM;   OpenMM for Mac is
 compiled using gcc 4.2.  If you are compiling with a different version, edit the
-Makefile and add the following flag to FCPPLIBS: :code:`–L/usr/lib/gcc/i686
+Makefile and add the following flag to FCPPLIBS: :code:`-L/usr/lib/gcc/i686
 -apple-darwin10/4.2.1`\ .
 
 When the Makefile has been updated, type:

docs-source/usersguide/library/07_testing_validation.rst

@@ -9,25 +9,16 @@ produces correct results.  Furthermore, it must work correctly on a variety of
 hardware platforms (e.g. different models of GPU), software platforms (e.g.
 operating systems and OpenCL implementations), and types of simulations.
 
-Three types of tests are used to validate OpenMM:
+OpenMM includes unit tests, which are small tests designed to test specific features
+or pieces of code in isolation.  For example, a test of HarmonicBondForce might
+create a System with just a few particles and bonds, compute the forces and
+energy, and compare them to the analytically expected values.  There are
+thousands of unit tests that collectively cover all of OpenMM.
 
-* **Unit tests:** These are small tests designed to test specific features
-  or pieces of code in isolation.  For example, a test of HarmonicBondForce might
-  create a System with just a few particles and bonds, compute the forces and
-  energy, and compare them to the analytically expected values.  There are
-  thousands of unit tests that collectively cover all of OpenMM.
+In addition, a direct comparison has been made of the individual forces computed
+by OpenMM to those computed by other programs for a collection of biomolecules.
 
-* **System tests:** Whereas unit tests validate small features in
-  isolation, system tests are designed to validate the entire library as a whole.
-  They simulate realistic models of biomolecules and perform tests that are likely
-  to fail if any problem exists anywhere in the library.
-
-* **Direct comparison between OpenMM and other programs:**  The third type
-  of validation performed is a direct comparison of the individual forces computed
-  by OpenMM to those computed by other programs for a collection of biomolecules.
-
-
-Each type of test is outlined in greater detail below; a discussion of the
+Each of these types of tests is outlined in greater detail below; a discussion of the
 current status of the tests is then given.
 
 
@@ -58,51 +49,11 @@ suite took to execute.  Otherwise it prints an error message.  If any tests
 failed, you can then run them individually (each one is a separate executable)
 to get more details on what went wrong.
 
-System tests
-============
-
-Several different types of system tests are performed.  Each type is run for a
-variety of systems, including both proteins and nucleic acids, and involving
-both implicit and explicit solvent.  The full suite of tests is repeated for
-both the CUDA and OpenCL platforms, using both single and double precision (and
-for the integration tests, mixed precision as well), on a variety of operating
-systems and hardware.  There are four types of tests:
-
-* **Consistency between platforms:** The forces and energy are computed
-  using the platform being tested, then compared to ones computed with the
-  Reference platform.  The results are required to agree to within a small
-  tolerance.
-* **Energy-force consistency:** This verifies that the force really is the
-  gradient of the energy.   It first computes the vector of forces for a given
-  conformation.  It then generates four other conformations by displacing the
-  particle positions by small amounts along the force direction.  It computes the
-  energy of each one, uses those to calculate a fourth order finite difference
-  approximation to the derivative along that direction, and compares it to the
-  actual forces.  They are required to agree to within a small tolerance.
-* **Energy conservation:** The system is simulated at constant energy using
-  a Verlet integrator, and the total energy is periodically recorded.  A linear
-  regression is used to estimate the rate of energy drift.  In addition, all
-  constrained distances are monitored during the simulation to make sure they
-  never differ from the expected values by more than the constraint tolerance.
-* **Thermostability:** The system is simulated at constant temperature
-  using a Langevin integrator.  The mean kinetic energy over the course of the
-  simulation is computed and compared to the expected value based on the
-  temperature.  In addition, all constrained distances are monitored during the
-  simulation to make sure they never differ from the expected values by more than
-  the constraint tolerance.
-
-
-If you want to run the system tests yourself, they can be found in the
-Subversion repository at https://simtk.org/svn/pyopenmm/trunk/test/system-tests.
-Check out that directory, then execute the runAllTests.sh shell script.  It will
-create a series of files with detailed information about the results of the
-tests.  Be aware that running the full test suite may take a long time (possibly
-several days) depending on the speed of your GPU.
 
 Direct comparisons between OpenMM and other programs
 ====================================================
 
-As a final check, identical systems are set up in OpenMM and in another program
+As another check, identical systems are set up in OpenMM and in another program
 (Gromacs 4.5 or Tinker 6.1), each one is used to compute the forces on atoms,
 and the results are directly compared to each other.
 

docs-source/usersguide/license.rst

-Portions copyright (c) 2008-2017 Stanford University and the Authors
+License
+*******
+
+Portions copyright (c) 2008-2025 Stanford University and the Authors
 
 Contributors:  Kyle Beauchamp, Christopher Bruns, John Chodera, Peter Eastman, Mark
 Friedrichs, Joy P. Ku, Tom Markland, Vijay Pande, Randy Radmer, Michael Sherman,

examples/CMakeLists.txt

 # 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)

examples/MakefileNotes.txt

-Instructions for using the Makefile provided.
----------------------------------------------
-
-There is a Makefile for use on Linux and Mac, and an NMakefile
-for use with Microsoft's "nmake" program. For Fortran, the
-Makefile expects gfortran to be in the path while NMakefile
-expects "ifort" (Intel Fortran).
-
-You must already have the OpenMM binaries installed from 
-SimTK.org/home/OpenMM. Pay careful attention to the installation 
-instructions -- if you are hoping to get GPU acceleration you 
-may also have to install appropriate vendor libraries and a driver.
-
-You may need to slightly edit the Makefile or NMakefile to make 
-it run on your system, depending where you installed OpenMM and 
-the particular requirements of your compiler versions for mixed 
-Fortran/C++ programming. 
-
-Type "make" (or "make default") to get just one C++ example built
-(HelloArgon). Make sure it runs.
-
-To compile all example programs type "make all". That includes Fortran
-examples though so you will see failures unless you have gfortran
-installed (Linux and Mac) or ifort installed (Windows). However, 
-the C++ and C examples should compile with just g++ or cl.
-
-To build just one example, type "make HelloArgonInC" or whatever.
-
-Before you run the executables, remember to add the OpenMM dynamic 
-library directory to your library path. 
-
-The simplest way to do this is to type the following commands:
-
-For linux (for the bash shell, assuming installation was done in 
-the default location: /usr/local/openmm): 
-  $ export LD_LIBRARY_PATH=/usr/local/openmm/lib 
-
-For MAC (for the bash shell, assuming installation was done 
-in the default location: /usr/local/openmm):
-  $ export DYLD_LIBRARY_PATH=/usr/local/openmm/lib 
-
-For Windows (command tool, assuming installation was done 
-in the default location: C:/Program Files/OpenMM):
-C:\> set path=%path%;C:\Program Files\OpenMM\lib
-

examples/README.md

+## 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`)
+
+These examples can also be found in the
+[Running Simulations chapter](https://docs.openmm.org/latest/userguide/application/02_running_sims.html)
+of the user guide, along with explanations of how they work.
+
+### 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`

examples/README.txt

-----------------------------------------------------------------
-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.
-
-
-
-
-
-
-
-
-