Merge pull request #5030 from epretti/cleanup-examples

Cleanup examples, documentation, and README files

examples/cpp-examples/CMakeLists.txt

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

examples/HelloArgon.cpp → examples/cpp-examples/HelloArgon.cpp

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

examples/HelloArgonInC.c → examples/cpp-examples/HelloArgonInC.c

 /* -----------------------------------------------------------------------------
- *             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

examples/HelloArgonInFortran.f90 → examples/cpp-examples/HelloArgonInFortran.f90

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

examples/HelloEthane.cpp → examples/cpp-examples/HelloEthane.cpp

 /* -----------------------------------------------------------------------------
- *               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, 

examples/HelloSodiumChloride.cpp → examples/cpp-examples/HelloSodiumChloride.cpp

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

examples/HelloSodiumChlorideInC.c → examples/cpp-examples/HelloSodiumChlorideInC.c

 /* -----------------------------------------------------------------------------
- *           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

examples/HelloSodiumChlorideInFortran.f90 → examples/cpp-examples/HelloSodiumChlorideInFortran.f90

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

examples/HelloWaterBox.cpp → examples/cpp-examples/HelloWaterBox.cpp

 /* -----------------------------------------------------------------------------
- *              OpenMM(tm) HelloWaterBox example in C++ (June 2009)
+ *                OpenMM HelloWaterBox 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, 

examples/Makefile → examples/cpp-examples/Makefile

 # ----------------------------------------------------------------------
-# Makefile for OpenMM Preview Release 4 workshop "hello world" examples.
+# Makefile for OpenMM "hello world" examples.
 # August 18, 2009
-# See https://simtk.org/home/openmm.
 # ----------------------------------------------------------------------
 # This assumes you have gcc compilers for whatever language you are
 # using: g++ for C++ and C, gfortran for Fortran 95.

examples/NMakefile → examples/cpp-examples/NMakefile

 # ----------------------------------------------------------------------
-# Microsoft NMakefile for OpenMM Preview Release 4 "hello world" examples.
+# Microsoft NMakefile for OpenMM "hello world" examples.
 # August 19, 2009.
-# See https://simtk.org/home/openmm.
 # ----------------------------------------------------------------------
 # This assumes you have gcc compilers for whatever language you are
 # using: cl for C++ and C, ifort for Fortran 95.

examples/cpp-examples/README.md

+## OpenMM C++, C, and Fortran API Examples
+
+These simple "hello world" examples were developed by Christopher Bruns and
+Michael Sherman.  They demonstrate use of the C++, C, and Fortran APIs for
+OpenMM.
+
+### Example Details
+
+Consult the OpenMM user guide for
+[more information on these examples](https://docs.openmm.org/latest/userguide/library/03_tutorials.html),
+as well as
+[use of the C and Fortran API wrappers](https://docs.openmm.org/latest/userguide/library/05_languages_not_cpp.html).
+
+#### `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.
+
+### 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.  There is also 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).  In the `VisualStudio` subdirectory, there are 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.
+
+You must already have the OpenMM binaries installed to build the examples from
+source.  See the
+[user guide](https://docs.openmm.org/latest/userguide/application/01_getting_started.html#installing-openmm)
+for more information.  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`):
+  ```bash
+  $ 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`):
+  ```bash
+  $ export DYLD_LIBRARY_PATH=/usr/local/openmm/lib
+  ```
+- For Windows (command tool, assuming installation was done in the default
+  location `C:\Program Files\OpenMM`):
+  ```bat
+  C:\> set path=%path%;C:\Program Files\OpenMM\lib
+  ```