Merge pull request #267 from a-ws-m/ff-switching

* Use OOP forcefields: new `forcefields.Forcefield` class to bundle all ff related information;
  overall, should be backwards compatible from a user perspective but enable much cleaner extensions
  to other FFs.
* fix #112  (Make default water model forcefield-specific)
* made system.top files real templates and use Python templating
* Add pytest settings for VSCode
* Add typehinting
* Tests for _get_forcefield() correct solvation identifier test + all new functionality.
* docs: Martini example (Jupyter notebook and input files)
* update CHANGELOG

Summary

This PR #267 implements several changes to make it easier for end-users to implement their own forcefields. 
Most of these changes revolve around the `Forcefield` class, which stores the path dictionaries that were 
previously separate entities. To use a non-default forcefield, make a new `Forcefield` instance and then pass it to
`Simulation` using the `forcefield` argument (now accepts either `str` for predefined force fields or a `Forcefield` instance). This argument is optional; passing a string value for forcefield will still work, it's simply converted behind the scenes.

Additional changes/code clean-up:

*  The `system.top` and `system_octwet.top` files have been changed to be compatible with Python's built-in 
    Template functionality. This makes the code a bit easier to understand.
*  Water models are now attributes of the individual forcefields, and are read directly from the corresponding
   watermodels.dat file. As I understand it, `GROMACS_WATER_MODELS` is a master list of all water models, 
   some of which are only available for OPLS-AA. If this is correct, it might be good to phase this out. 
   I have changed the core functions that used this: `get_solvent_model` and `get_solvent_identifier`. 
   The only other places in the code where `GROMACS_WATER_MODELS` is used is in the tests and in 
   `get_water_model`, a function which is also unused in the code base except in tests.
*   I have changed one test to check for equality rather than equivalence (`is` -> `==`).

.gitignore

@@ -15,3 +15,11 @@ coverage.xml
 *.lock
 *.npz
 dir.csv
+
+# Files for the Martini example that can be downloaded at runtime
+doc/examples/martini/*
+!doc/examples/martini/*.mdp
+!doc/examples/martini/*.ipynb
+!doc/examples/martini/water.gro
+!doc/examples/martini/octanol.gro
+!doc/examples/martini/benzene.pdb

.readthedocs.yaml

@@ -17,5 +17,4 @@ formats:
 python:
    version: 3.8
    install:
-   - requirements: doc/requirements.txt
-   system_packages: true
+   - requirements: doc/requirements.txt

.vscode/settings.json

@@ -1,5 +1,10 @@
 {
     "[python]": {
         "editor.formatOnSave": true
-    }
+    },
+    "python.testing.pytestArgs": [
+        "mdpow"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
 }

CHANGES

@@ -25,6 +25,17 @@ Changes
   EnsembleAnalysis.run() method, no longer needed (per comments, #199)
 * internal log_banner() now uses logger as argument (PR #247)
 * use `black` formatter for codebase (#271)
+* implemented `forcefields.Forcefield` class (#267)
+  - facilitates users using non-default forcefields without changing package code
+  - `equil.Simulation` has new `ff_class` argument
+  - each `Forcefield` has unique `default_water_model`, replacing global `DEFAULT_WATER_MODEL`
+  - `get_solvent_model()` and `get_solvent_identifier()` take either `str` or `Forcefield` type for the `forcefield` argument
+  - both functions also use the `Forcefield`-specific `default_water_model` (fixes #112)
+* `forcefields.DEFAULT_WATER_MODEL` removed (#267)
+* changed `system.top` and `system_octwet.top` to act as templates and added `.template` suffix (#267)
+* removed `forcefields.get_ff_paths()` (#267)
+* changed `forcefields.get_solvent_identifier()`: will raise `ValueError` instead of returning `None` (#267)
+
 
 Enhancements
 

doc/examples/martini/benzene.pdb

@@ -0,0 +1,13 @@
+REMARK    GENERATED BY TRJCONV
+TITLE     This is an auto generated system
+REMARK    THIS IS A SIMULATION BOX
+CRYST1  150.000  150.000  180.000  90.00  90.00  90.00 P 1           1
+MODEL        1
+ATOM      1  R1  BENZ    1      30.920   6.600  24.160  1.00  0.00            
+ATOM      2  R2  BENZ    1      28.820   5.000  23.610  1.00  0.00            
+ATOM      3  R3  BENZ    1      29.860   6.580  21.680  1.00  0.00            
+TER
+ENDMDL
+CONECT    1    2
+CONECT    2    3
+CONECT    1    3

doc/examples/martini/em.mdp

@@ -0,0 +1,17 @@
+include          =  
+integrator       =  steep
+dt               =  0.02
+nsteps           =  1000
+nstxout          =  0
+nstvout          =  0
+nstlog           =  100 
+nstxtcout        =  100
+xtc-precision    =  1000
+rlist            =  1.0
+coulombtype      =  Reaction-Field
+rcoulomb         =  1.0
+epsilon_r        =  15
+vdw-type         =  cutoff
+vdw-modifier     =  Potential-shift-verlet
+rvdw             =  1.0
+constraints = none

doc/examples/martini/eq.mdp

@@ -0,0 +1,24 @@
+include          =  
+dt               =  0.005 
+nsteps           =  25000
+nstxout          =  0 
+nstvout          =  0
+nstlog           =  1000
+nstxout-compressed  = 1000
+cutoff-scheme    =  Verlet
+coulombtype      =  Reaction-Field
+rcoulomb         =  1.1
+epsilon_r        =  15 
+vdw-type         =  cutoff
+vdw-modifier     =  Potential-shift-verlet 
+rvdw             =  1.1 
+tcoupl           =  v-rescale 
+tc-grps          =  System
+tau-t            =  1.0
+ref-t            =  300
+Pcoupl           =  c-rescale
+Pcoupltype       =  isotropic
+tau-p            =  3.0
+compressibility  =  3e-4
+ref-p            =  1.0
+refcoord_scaling =  all