Merge branch 'main' into adding_new_tests

.gitattributes

@@ -1 +1 @@
-stability_test/_version.py export-subst
+guardowl/_version.py export-subst

.github/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # How to contribute
 
 We welcome contributions from external contributors, and this document
-describes how to merge code changes into this stability_test. 
+describes how to merge code changes into this guardowl. 
 
 ## Getting Started
 
@@ -19,7 +19,7 @@ describes how to merge code changes into this stability_test.
   [branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/)
   with the branch name relating to the feature you are going to add.
 * When you are ready for others to examine and comment on your new feature,
-  navigate to your fork of stability_test on GitHub and open a [pull
+  navigate to your fork of guardowl on GitHub and open a [pull
   request](https://help.github.com/articles/using-pull-requests/) (PR). Note that
   after you launch a PR from one of your fork's branches, all
   subsequent commits to that branch will be added to the open pull request
@@ -29,7 +29,7 @@ describes how to merge code changes into this stability_test.
 * If you're providing a new feature, you must add test cases and documentation.
 * When the code is ready to go, make sure you run the test suite using pytest.
 * When you're ready to be considered for merging, check the "Ready to go"
-  box on the PR page to let the stability_test devs know that the changes are complete.
+  box on the PR page to let the guardowl devs know that the changes are complete.
   The code will not be merged until this box is checked, the continuous
   integration returns checkmarks,
   and multiple core developers give "Approved" reviews.

.github/workflows/CI.yaml

@@ -36,12 +36,12 @@ jobs:
 
       # More info on options: https://github.com/marketplace/actions/provision-with-micromamba
       - uses: mamba-org/provision-with-micromamba@main
+        env:
+          CONDA_OVERRIDE_CUDA: "11.4"
         with:
+          python-version: ${{ matrix.python-version }}
           environment-file: devtools/conda-envs/test_env.yaml
-          environment-name: test
           channels: conda-forge,defaults
-          extra-specs: |
-            python=${{ matrix.python-version }}
 
       - name: Install package
         # conda setup requires this special shell
@@ -54,7 +54,7 @@ jobs:
         # conda setup requires this special shell
         shell: bash -l {0}
         run: |
-          pytest -v --cov=stability_test --cov-report=xml --color=yes stability_test/tests/
+          pytest -v --cov=guardowl --cov-report=xml --color=yes guardowl/tests/
 
       - name: CodeCov
         uses: codecov/codecov-action@v1

.lgtm.yml

@@ -1,12 +1,12 @@
 # Configure LGTM for this package
 
 extraction:
-  python:  # Configure Python
-    python_setup:  # Configure the setup
-      version: 3  # Specify Version 3
+  python: # Configure Python
+    python_setup: # Configure the setup
+      version: 3 # Specify Version 3
 path_classifiers:
   library:
-    - versioneer.py  # Set Versioneer.py to an external "library" (3rd party code)
+    - versioneer.py # Set Versioneer.py to an external "library" (3rd party code)
     - devtools/*
   generated:
-    - stability_test/_version.py
+    - guardowl/_version.py

README.md

@@ -1,72 +1,88 @@
-# Perform stability tests for Neural Network Potentials
-
+<p align="center">
+<img src="https://github.com/Exscientia/StableNetGuardOwl/assets/31651017/6e72dbdd-3fae-4463-bde3-bbaf54b459a7" alt="Simple Icons" width=150>
+<h3 align="center">StableNetGuardOwl: Perform stability tests for Neural Network Potentials</h3>
+</p>
+<p align="center">
+
 [//]: # (Badges)
-[![GitHub Actions Build Status](https://github.com/Exscientia/stability_test/workflows/CI/badge.svg)](https://github.com/Exscientia/stability_test/actions?query=workflow%3ACI)
-[![codecov](https://codecov.io/gh/Exscientia/stability_test/branch/main/graph/badge.svg)](https://codecov.io/gh/Exscientia/stability_test/branch/main)
+[![GitHub Actions Build Status](https://github.com/Exscientia/StableNetGuardOwl/workflows/CI/badge.svg)](https://github.com/Exscientia/StableNetGuardOwl/actions?query=workflow%3ACI)
+[![codecov](https://codecov.io/gh/Exscientia/StableNetGuardOwl/branch/main/graph/badge.svg)](https://codecov.io/gh/Exscientia/StableNetGuardOwl/branch/main)
 [![Supported Python versions](https://img.shields.io/badge/python-%5E3.10-blue.svg)](https://docs.python.org/3/whatsnew/index.html)
 [![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)](http://mypy-lang.org/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![Github release](https://badgen.net/github/release/Exscientia/stability_test)](https://github.com/Exscientia/stability_test/)
-[![GitHub license](https://img.shields.io/github/license/Exscientia/stability_test?color=green)](https://github.com/Exscientia/stability_test/blob/main/LICENSE)
-
+[![Github release](https://badgen.net/github/release/Exscientia/StableNetGuardOwl)](https://github.com/Exscientia/StableNetGuardOwl/)
+[![GitHub license](https://img.shields.io/github/license/Exscientia/StableNetGuardOwl?color=green)](https://github.com/Exscientia/StableNetGuardOwl/blob/main/LICENSE)
+</p>
 
 ---
 
 # What this package contains
 
 ## Stability testing
 
-This repository provides the essential code for performing a variety of stability tests on test systems. The tests and systems can be customized or redefined by inheriting from the appropriate base classes. Key components include:
+This repository provides the essential code for performing a variety of stability tests with Neural Network Potentials. Tests are currently limited to `openMM`` and the Neural Network Potentials implemented in `openmm-ml`. The tests and systems can be customized or redefined by inheriting from the appropriate base classes. Key components include:
 
-- Script for Stability Testing: Located in the scripts directory (perform_stability_tests.py).
-- Results Visualization Notebook: Found in the notebooks directory (visualize_stability_tests.ipynb).
+- Script for stability testing: located in the scripts directory (`perform_guardowls.py``).
+- Results visualization notebook: found in the notebooks directory (`visualize_guardowls.ipynb``).
 
 Each stability test produces three types of output files:
 
 1. A PDB file defining the molecular system's topology.
 2. A CSV file containing the monitored properties.
 3. A DCD trajectory file to visualize the system's temporal evolution.
 
+To perform a stability test the general syntax is as follows:
 Command Syntax
-'''bash
-python perform_stability_tests.py TESTSYSTEM OPTIONS
-'''
-Different TESTSYSTEM options provide varying control parameters.
+```bash
+python scripts/perform_guardowls.py -c config.yaml
+```
+There is an example `config.yaml` file provided in the `scripts` directory that provides default parameters for the most common test systems.
 
 ### Example
-For a stability test using a pure waterbox:
-
-
-'''bash
-python perform_stability_tests.py waterbox 20 NpT ani2x torchani --nr_of_simulation_steps 1000
-'''
-This runs a NpT simulation in a 20-angstrom waterbox using the ani-2x potential and its torchani implementation.
-
-To visualize the results, use the visualize_stability_tests.ipynb notebook.
-
-'''python
+For a stability test using a pure 15 Angstrom waterbox the config.yaml file looks like shown below
+```
+tests:
+  - protocol: "waterbox_protocol"  # which protocol is performed
+    edge_length: 15                # waterbox edge length in Angstrom
+    ensemble: "NVT"                # thermodynamic esamble that is used. Oter options are 'NpT' and 'NVE'.
+    nnp: "ani2x"                   # the NNP used
+    implementation: "nnpops"       # the implementation if multiple are available
+    annealing: false               # simulated annealing to slowly reheat the system at the beginning of a simulation
+    nr_of_simulation_steps: 10_000 # number of simulation steps
+    temperature: 300               # in Kelvin
+```
+It defines the potential (nnp and implementation), the number of simulation steps, temperature in Kelvin, and edge length of the waterbox in Angstrom as well as the thermodynamic ensemble (`NVT`). Passing this to the `perform_guardowls.py` script runs the tests
+
+To visualize the results, use the visualize_guardowls.ipynb notebook.
+
+```python
 MonitoringPlotter("trajectory.dcd", 
                   "topology.pdb", 
                   "data.csv")
-'''
+```
 
 ### Other Test Systems
-Options for TESTSYSTEM include vacuum, alanine-dipeptide, and DOF (Degree Of Freedom scan, e.g., bond, angle, or torsion scan).
+Test systems that can be used for different protocols include small molecules in vacuum (either defined with SMILES string or taken from the HiPen dataset), alanine-dipeptide in vacuum and solution, pure waterbox and degree of freedom potential energy scan, e.g., along a bond, angle, or torsion angle.
 
 ### Protocols
 Currently, the following protocols are available:
 
-MultiTemperatureProtocol
-PropagationProtocol
-BondProfileProtocol
+- MultiTemperatureProtocol. Perform simulations at different temperatures.
+- PropagationProtocol. Perform MD simulation in a given thermodynamic ensemble (NpT, NVT, NVE).
+- BondProfileProtocol. Stretch bond along its bond axis starting with 0.5 to 5 Angstrom.
 
+### Examples
+To perform a DOF scan over a bond in ethanol you need to generate a yaml file containing the following (scan over bond connecting atom index 0 and 2. 
 
-###Examples
-DOF Scan Over a Bond in Ethanol:
+```yaml
+tests:
+  - protocol: "perform_DOF_scan"
+    nnp: "ani2x"
+    implementation: "torchani"
+    DOF_definition: { "bond": [0, 2] }
+    molecule_name: "ethanol"
+```
 
-'''bash
-python perform_stability_tests.py DOF ani2x torchani "{'bond' : [0, 2]}" ethanol
-'''
 
 ### Copyright
 

devtools/README.md

@@ -52,5 +52,5 @@ is installed by looking at the `git` tags and how many commits ahead this versio
 \d+.\d+.\d+(?\+\d+-[a-z0-9]+)
 ```
 If the version of this commit is the same as a `git` tag, the installed version is the same as the tag, 
-e.g. `stability_test-0.1.2`, otherwise it will be appended with `+X` where `X` is the number of commits 
+e.g. `guardowl-0.1.2`, otherwise it will be appended with `+X` where `X` is the number of commits 
 ahead from the last tag, and then `-YYYYYY` where the `Y`'s are replaced with the `git` commit hash.

devtools/conda-envs/test_env.yaml

@@ -8,7 +8,6 @@ dependencies:
   - python
   - pip
   - openmm>=8.0
-  - openmm-ml
   - openmm-torch
   - openff-toolkit
   - openmmtools
@@ -21,9 +20,12 @@ dependencies:
   - seaborn
   - pytorch #=1.11.0
   - loguru
-  # Testing
   - nglview
-  - fire
+  # Testing
+  - pytest
+  - pytest-cov
+  - codecov
+  - black
 
     # Testing
   - pytest
@@ -32,5 +34,6 @@ dependencies:
 
     # Pip-only installs
   - pip:
-      - nvidia-ml-py3
-      - nptyping
+     - nvidia-ml-py3
+     - nptyping
+     - git+https://github.com/openmm/openmm-ml.git

docs/Makefile

@@ -4,7 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = stability_test
+SPHINXPROJ    = guardowl
 SOURCEDIR     = .
 BUILDDIR      = _build
 

docs/README.md

@@ -1,4 +1,4 @@
-# Compiling stability_test's Documentation
+# Compiling guardowl's Documentation
 
 The docs for this project are built with [Sphinx](http://www.sphinx-doc.org/en/master/).
 To compile the docs, first ensure that Sphinx and the ReadTheDocs theme are installed.

docs/api.rst

@@ -4,4 +4,4 @@ API Documentation
 .. autosummary::
    :toctree: autosummary
 
-   stability_test.canvas
+   guardowl.canvas