Includes doctest for CompositeRMSDForce (#10)

Charlles Abreu · web-flow · commit 65a9b94fb092 · 2024-01-29T17:55:23.000-05:00
* Removed doxygen as dependency

* Fixed python docstrings

* Fixed force implementation

* Fixed comments

* Completed doctest

* Updated Docs

* Included test dependencies for GH Actions
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -91,7 +91,6 @@ SET(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}")
 
 # Build the Python API
 
-FIND_PROGRAM(DOXYGEN_EXECUTABLE doxygen)
 FIND_PROGRAM(PYTHON_EXECUTABLE python REQUIRED)
 FIND_PROGRAM(SWIG_EXECUTABLE swig REQUIRED)
 SET(PLUGIN_BUILD_PYTHON_WRAPPERS ON CACHE BOOL "Build wrappers for Python")
diff --git a/devtools/conda-envs/build-docs.yml b/devtools/conda-envs/build-docs.yml
@@ -9,7 +9,6 @@ dependencies:
   - pip >=22.2
   - pytest
   - python
-  - doxygen
   - swig =4.0
   - sysroot_linux-64 2.17
   - numpy
diff --git a/devtools/conda-envs/build-macos-latest.yml b/devtools/conda-envs/build-macos-latest.yml
@@ -2,12 +2,15 @@ name: build
 channels:
   - conda-forge
 dependencies:
-  - cmake
   - compilers
+  - cmake
   - make
+  - numpy
   - openmm
   - pip >=22.2
-  - pytest
   - python
   - swig =4.0
-  - numpy
+
+  # Test dependencies
+  - openmmtools
+  - pytest
diff --git a/devtools/conda-envs/build-ubuntu-latest.yml b/devtools/conda-envs/build-ubuntu-latest.yml
@@ -5,11 +5,13 @@ dependencies:
   - cmake
   - gxx_linux-64
   - make
+  - numpy
   - openmm
   - pip >=22.2
-  - pytest
   - python
-  - doxygen
   - swig =4.0
   - sysroot_linux-64 2.17
-  - numpy
+
+  # Test dependencies
+  - openmmtools
+  - pytest
diff --git a/devtools/conda-recipes/anaconda/meta.yaml b/devtools/conda-recipes/anaconda/meta.yaml
@@ -14,7 +14,6 @@ requirements:
   build:
     - python
     - swig <4.1
-    - doxygen
     - openmm >=8.1
     - {{ compiler('cxx') }}
     - cmake
diff --git a/docs/conf.py b/docs/conf.py
@@ -58,7 +58,7 @@ def create_rst_file(cls):
 source_suffix = '.rst'
 master_doc = 'index'
 
-project = 'OpenMM OpenMM CPP Forces'
+project = 'OpenMM CPP Forces'
 copyright = ('2024, Charlles Abreu. Project based on OpenMM')
 author = 'Charlles Abreu'
 
@@ -83,8 +83,6 @@ def create_rst_file(cls):
 html_theme = 'alabaster'
 html_static_path = ['_static']
 html_theme_options = {
-    'logo': 'logo_small.png',
-    'logo_name': True,
     'github_button': False,
     'github_user': 'craabreu',
     'github_repo': 'openmmcppforces',
diff --git a/docs/overview.rst b/docs/overview.rst
@@ -2,41 +2,29 @@
 Overview
 ========
 
-This OpenMM_ plugin is a laboratory for low-level code implementation.
+This `OpenMM`_ plugin provides Platform-agnostic Force classes.
 
-Building the Plugin
-===================
+Installation and Usage
+======================
 
-This project uses CMake_ for its build system.  To build it, follow these steps:
+OpenMM-CPP-Forces is available as a conda package on the `mdtools`_ channel. To install it, run:
 
-#. Create a directory in which to build the plugin.
-#. Run the CMake GUI or ccmake, specifying your new directory as the build directory and the top level directory of this project as the source directory.
-#. Press "Configure".
-#. Set OPENMM_DIR to point to the directory where OpenMM is installed.  This is needed to locate the OpenMM header files and libraries.
-#. Set CMAKE_INSTALL_PREFIX to the directory where the plugin should be installed.  Usually, this will be the same as OPENMM_DIR, so the plugin will be added to your OpenMM installation.
-#. If you plan to build the OpenCL platform, make sure that OPENCL_INCLUDE_DIR and OPENCL_LIBRARY are set correctly, and that PLUGIN_BUILD_OPENCL_LIB is selected.
-#. If you plan to build the CUDA platform, make sure that CUDA_TOOLKIT_ROOT_DIR is set correctly and that PLUGIN_BUILD_CUDA_LIB is selected.
-#. Press "Configure" again if necessary, then press "Generate".
-#. Use the build system you selected to build and install the plugin.  For example, if you selected Unix Makefiles, type `make install`.
+.. code-block:: bash
 
-Python Wrapper
-==============
+    conda install -c conda-forge -c mdtools openmm-cpp-forces
 
-As OpenMM_, this project uses SWIG_ to generate its Python API.  SWIG takes an "interface
-file", which is essentially a C++ header file with some extra annotations added, as its input.
-It then generates a Python extension module exposing the C++ API in Python.
+Or:
 
-To build and install the Python API, build the `PythonInstall` target, for example by typing
-`make PythonInstall` (if you are installing into the system Python, you may need to use sudo).
+.. code-block:: bash
 
-Test Cases
-==========
+    mamba install -c mdtools openmm-cpp-forces
 
-To run the C++ test cases, build the "test" target, for example by typing `make test`.
+To use OpenMM-CPP-Forces in your own Python script or Jupyter notebook, simply import it as follows:
 
-To run the Python test cases, build the "PythonTest" target by typing `make PythonTest`.
+.. code-block:: python
 
+    import openmmcppforces
 
-.. _CMake:                http://www.cmake.org
-.. _OpenMM:               https://openmm.org
-.. _SWIG:                 http://www.swig.org
+
+.. _OpenMM:  https://openmm.org
+.. _mdtools: https://anaconda.org/mdtools/openmm-cpp-forces
diff --git a/docs/pythonapi/index.rst b/docs/pythonapi/index.rst
@@ -5,12 +5,9 @@ To use the plugin from your Python script, you can do:
 
 .. code-block:: python
 
-    import openmm as mm
     import openmmcppforces
 
-    force = openmmcppforces.CompositeRMSDForce()
-
-This is the implemented subclass of :OpenMM:`Force`:
+These are the implemented subclasses of :OpenMM:`Force`:
 
 .. toctree::
     :titlesonly:
diff --git a/openmmcppforces/include/CompositeRMSDForce.h b/openmmcppforces/include/CompositeRMSDForce.h
@@ -8,7 +8,7 @@
  *  A plugin for distributing platform-agnostic OpenMM Forces                 *
  *                                                                            *
  *  Copyright (c) 2024 Charlles Abreu                                         *
- *  https://github.com/craabreu/openmm-cpp-forces                               *
+ *  https://github.com/craabreu/openmm-cpp-forces                             *
  * -------------------------------------------------------------------------- */
 
 #include "internal/windowsExportOpenMMCPPForces.h"
@@ -44,7 +44,7 @@ class CUSTOM_CPP_FORCES_EXPORT CompositeRMSDForce : public Force {
      * @param referencePositions  the reference positions to compute the deviation from.
      *                            The length of this vector must equal the number of
      *                            particles in the system, even if not all particles are
-     *                            used in computing the Concerted RMSD.
+     *                            used in computing the Composite RMSD.
      */
     explicit CompositeRMSDForce(const vector<Vec3>& referencePositions);
     /**
@@ -59,29 +59,29 @@ class CUSTOM_CPP_FORCES_EXPORT CompositeRMSDForce : public Force {
      * @param positions    the reference positions to compute the deviation from.
      *                     The length of this vector must equal the number of
      *                     particles in the system, even if not all particles are
-     *                     used in computing the concerted RMSD.
+     *                     used in computing the composite RMSD.
      */
     void setReferencePositions(const vector<Vec3>& positions);
     /**
-     * Add a group of particles to be included in the concerted RMSD calculation.
+     * Add a group of particles to be included in the composite RMSD calculation.
      *
      * @param particles    the indices of the particles to include
      *
      * @return the index of the group that was added
      */
     int addGroup(const vector<int>& particles);
     /**
-     * Get the number of particle groups included in the concerted RMSD calculation.
+     * Get the number of particle groups included in the composite RMSD calculation.
      */
     int getNumGroups() const;
     /**
-     * Get the particles of a group included in the concerted RMSD calculation.
+     * Get the particles of a group included in the composite RMSD calculation.
      *
      * @param index    the index of the group whose particles are to be retrieved
      */
     const vector<int>& getGroup(int index) const;
     /**
-     * Set the particles of a group included in the concerted RMSD calculation.
+     * Set the particles of a group included in the composite RMSD calculation.
      */
     void setGroup(int index, const vector<int>& particles);
     /**
diff --git a/openmmcppforces/include/internal/CompositeRMSDForceImpl.h b/openmmcppforces/include/internal/CompositeRMSDForceImpl.h
@@ -8,7 +8,7 @@
  *  A plugin for distributing platform-agnostic OpenMM Forces                 *
  *                                                                            *
  *  Copyright (c) 2024 Charlles Abreu                                         *
- *  https://github.com/craabreu/openmm-cpp-forces                               *
+ *  https://github.com/craabreu/openmm-cpp-forces                             *
  * -------------------------------------------------------------------------- */
 
 #include "CompositeRMSDForce.h"
@@ -40,6 +40,7 @@ class CompositeRMSDForceImpl : public CustomCPPForceImpl {
     const CompositeRMSDForce& owner;
     vector<vector<int>> groups;
     vector<Vec3> referencePos;
+    double sumRefPosSquared;
 };
 
 } // namespace OpenMMCPPForces
diff --git a/openmmcppforces/src/CompositeRMSDForce.cpp b/openmmcppforces/src/CompositeRMSDForce.cpp
@@ -5,7 +5,7 @@
  *  A plugin for distributing platform-agnostic OpenMM Forces                 *
  *                                                                            *
  *  Copyright (c) 2024 Charlles Abreu                                         *
- *  https://github.com/craabreu/openmm-cpp-forces                               *
+ *  https://github.com/craabreu/openmm-cpp-forces                             *
  * -------------------------------------------------------------------------- */
 
 #include "CompositeRMSDForce.h"
diff --git a/openmmcppforces/src/CompositeRMSDForceImpl.cpp b/openmmcppforces/src/CompositeRMSDForceImpl.cpp
@@ -5,7 +5,7 @@
  *  A plugin for distributing platform-agnostic OpenMM Forces                 *
  *                                                                            *
  *  Copyright (c) 2024 Charlles Abreu                                         *
- *  https://github.com/craabreu/openmm-cpp-forces                               *
+ *  https://github.com/craabreu/openmm-cpp-forces                             *
  * -------------------------------------------------------------------------- */
 
 #include "internal/CompositeRMSDForceImpl.h"
@@ -69,6 +69,10 @@ void CompositeRMSDForceImpl::updateParameters(int systemSize) {
         for (int i : group)
             referencePos.push_back(positions[i] - center);
     }
+
+    sumRefPosSquared = 0.0;
+    for (auto& p : referencePos)
+        sumRefPosSquared += p.dot(p);
 }
 
 void CompositeRMSDForceImpl::initialize(ContextImpl& context) {
@@ -134,15 +138,17 @@ double CompositeRMSDForceImpl::computeForce(ContextImpl& context, const vector<V
 
     // Compute the RMSD.
 
-    double sum = 0.0;
-    for (auto& group : groups)
-        for (int index = 0; index < group.size(); index++)
-            sum += centeredPos[index].dot(centeredPos[index]) + referencePos[index].dot(referencePos[index]);
+    double sum = sumRefPosSquared;
+    for (auto& p : centeredPos)
+        sum += p.dot(p);
 
     double msd = (sum - 2*values[3])/numParticles;
     if (msd < 1e-20) {
         // The particles are perfectly aligned, so all the forces should be zero.
         // Numerical error can lead to NaNs, so just return 0 now.
+        for (auto& group : groups)
+            for (int i : group)
+                forces[i] = Vec3(0, 0, 0);
         return 0.0;
     }
     double rmsd = sqrt(msd);
@@ -161,14 +167,18 @@ double CompositeRMSDForceImpl::computeForce(ContextImpl& context, const vector<V
     // Rotate the reference positions and compute the forces.
 
     index = 0;
-    for (auto& group : groups)
+    for (auto& group : groups) {
+        double scale = 1.0 / (rmsd*group.size());
         for (int i : group) {
             const Vec3& p = referencePos[index];
-            Vec3 rotatedRef(U[0][0]*p[0] + U[1][0]*p[1] + U[2][0]*p[2],
-                            U[0][1]*p[0] + U[1][1]*p[1] + U[2][1]*p[2],
-                            U[0][2]*p[0] + U[1][2]*p[1] + U[2][2]*p[2]);
-            forces[i] = -(centeredPos[index] - rotatedRef) / (rmsd*groups[0].size());
+            Vec3 rotatedRef(
+                U[0][0]*p[0] + U[1][0]*p[1] + U[2][0]*p[2],
+                U[0][1]*p[0] + U[1][1]*p[1] + U[2][1]*p[2],
+                U[0][2]*p[0] + U[1][2]*p[1] + U[2][2]*p[2]
+            );
+            forces[i] = scale * (rotatedRef - centeredPos[index]);
             index++;
+        }
     }
     return rmsd;
 }
diff --git a/python/openmmcppforces/CMakeLists.txt b/python/openmmcppforces/CMakeLists.txt
@@ -17,7 +17,6 @@ add_custom_command(
     TARGET PythonWrapper
     COMMAND "${SWIG_EXECUTABLE}"
         -python -c++
-        -doxygen
         -o "${WRAP_FILE}"
         "-I${OPENMM_DIR}/include"
         "${MODULE_NAME}.i"
diff --git a/python/openmmcppforces/openmmcppforces.i b/python/openmmcppforces/openmmcppforces.i
diff --git a/serialization/include/CompositeRMSDForceProxy.h b/serialization/include/CompositeRMSDForceProxy.h
diff --git a/serialization/src/OpenMMCPPForcesSerializationProxyRegistration.cpp b/serialization/src/OpenMMCPPForcesSerializationProxyRegistration.cpp
diff --git a/serialization/tests/TestSerializeCompositeRMSDForce.cpp b/serialization/tests/TestSerializeCompositeRMSDForce.cpp
diff --git a/tests/TestCompositeRMSDForce.cpp b/tests/TestCompositeRMSDForce.cpp
