Merge 1.0.0-development branch to devel branch.

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,73 @@
+name: Bug report
+description: Create a bug report to help us eliminate issues and improve DMFF.
+title: "[BUG] _Replace With Suitable Title_"
+labels: bug
+assignees: []
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Bug summary
+      description: Please provide a clear and concise description of what the bug is.
+      placeholder: 
+      value:
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: DMFF Version
+      description: Version of DMFF you are using.
+    validations:
+      required: true
+  - type: input
+    id: jax-version
+    attributes:
+      label: JAX Version
+      description: Version of JAX you are using.
+    validations:
+      required: true
+  - type: input
+    id: openmm-version
+    attributes:
+      label: OpenMM Version
+      description: Version of OpenMM you are using.
+    validations:
+      required: true
+  - type: dropdown
+    id: installation-way
+    attributes:
+      label: How did you download the software?
+      options:
+        - pip
+        - Built from source
+        - Others (write below)
+    validations:
+      required: true
+  - type: textarea
+    id: log
+    attributes:
+      label: Input Files, Running Commands, Error Log, etc.
+      description: "Please provide necessary information including input file, running commands, error log , etc., AS  DETAILED AS POSSIBLE to help locate and reproduce your problem. WARNING: Do not use image to show error log! Paste texts in a code block instead."
+      placeholder: 
+      value:
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: "Describe the steps required to (quickly) reproduce the issue. You can attach (small) files to the section below or add URLs where to download an archive with all necessary files. Please try to create an input set that is as minimal and small as possible and reproduces the bug as quickly as possible. **NOTE:** the less effort and time it takes to reproduce your reported bug, the more likely it becomes, that somebody will look into it and fix the problem."
+      placeholder: 
+      value:
+    validations:
+      required: true
+  - type: textarea
+    id: further
+    attributes:
+      label: Further Information, Files, and Links
+      description: Put any additional information here, attach relevant text or image files and URLs to external sites, e.g. relevant publications
+      placeholder: 
+      value:
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Request for Help
+    url: https://github.com/deepmodeling/DMFF/issues
+    about: If you have a usage question

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,42 @@
+name: Feature request
+description: Suggest an idea for DMFF.
+title: "[Feature Request] _Replace with Title_"
+labels: enhancement
+assignees: []
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: "Please provide a brief and concise description of the suggested feature or change"
+      placeholder: 
+      value:
+    validations:
+      required: true
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: "Please explain why you think this feature is important and should be implemented. If possible, provide references to relevant background information like publications or web pages, and whether you are planning to implement the enhancement yourself or would like to participate in the implementation. If applicable add a reference to an existing bug report or issue that this will address."
+      placeholder: 
+      value:
+    validations:
+      required: true
+  - type: textarea
+    id: solutions
+    attributes:
+      label: Suggested Solutions
+      description: "Please describe possible solutions to the problem. If you have a specific idea in mind, please describe it here. If you don't have a specific idea, please describe what you think would be a good solution to the problem."
+      placeholder: 
+      value:
+    validations:
+      required: false
+  - type: textarea
+    id: further
+    attributes:
+      label: Further Information, Files, and Links
+      description: Put any additional information here, attach relevant text or image files and URLs to external sites, e.g. relevant publications. If you have any further questions, please don't hesitate to ask them here. Any comments are welcomed!
+      placeholder: 
+      value:
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/generic-issue.yml

@@ -0,0 +1,54 @@
+name: Generic issue
+description: For issues that do not fit any of the other categories.
+title: _Replace With a Descriptive Title_
+labels: wontfix
+assignees: []
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: "Please provide a clear and concise description of what the question is."
+      placeholder: 
+      value:
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: DMFF Version
+      description: Version of DMFF you are using.
+    validations:
+      required: true
+  - type: input
+    id: jax-version
+    attributes:
+      label: JAX Version
+      description: Version of JAX you are using.
+    validations:
+      required: true
+  - type: input
+    id: openmm-version
+    attributes:
+      label: OpenMM Version
+      description: Version of OpenMM you are using.
+    validations:
+      required: true
+  - type: textarea
+    id: other-version
+    attributes:
+      label: Python Version, CUDA Version, GCC Version, Operating System Version etc
+      description: "If applicable, specify what platform you are running on."
+      placeholder: 
+      value:
+    validations:
+      required: false
+  - type: textarea
+    id: details
+    attributes:
+      label: Details
+      description: "Please explain the issue in detail here."
+      placeholder: 
+      value:
+    validations:
+      required: true

.github/workflows/test_openmm_dmff_plugin.yml

@@ -41,10 +41,11 @@ jobs:
           export OPENMM_INSTALLED_DIR=$CONDA_PREFIX
           export CPPFLOW_INSTALLED_DIR=$CONDA_PREFIX
           export LIBTENSORFLOW_INSTALLED_DIR=$CONDA_PREFIX
-          cmake .. -DOPENMM_DIR=${OPENMM_INSTALLED_DIR} -DCPPFLOW_DIR=${CPPFLOW_INSTALLED_DIR} -DTENSORFLOW_DIR=${LIBTENSORFLOW_INSTALLED_DIR} -DUSE_HIGH_PRECISION=ON
+          cmake .. -DOPENMM_DIR=${OPENMM_INSTALLED_DIR} -DCPPFLOW_DIR=${CPPFLOW_INSTALLED_DIR} -DTENSORFLOW_DIR=${LIBTENSORFLOW_INSTALLED_DIR} -DUSE_HIGH_PRECISION=OFF
           make && make install 
-          make PythonInstall
+          make PythonInstall          
       - name: Run Tests
         run: |
           source $CONDA/bin/activate dmff_omm
-          python -m OpenMMDMFFPlugin.tests.test_dmff_plugin_nve -n 100
+          cd ${GITHUB_WORKSPACE}/backend/
+          python -m OpenMMDMFFPlugin.tests.test_dmff_plugin_nve -n 100 --pdb ../examples/water_fullpol/water_dimer.pdb --model ./openmm_dmff_plugin/python/OpenMMDMFFPlugin/data/admp_water_dimer_aux --has_aux True

.github/workflows/ut.yml

@@ -19,19 +19,19 @@ jobs:
       - name: Install Dependencies
         run: |
           source $CONDA/bin/activate
-          conda create -n dmff -y python=${{ matrix.python-version }} numpy openmm==7.7.0 mdtraj=1.9.7 pytest rdkit biopandas openbabel -c conda-forge
+          conda create -n dmff -y python=${{ matrix.python-version }} numpy openmm==7.7.0 pytest rdkit openbabel mdtraj ambertools -c conda-forge
           conda activate dmff
           pip install --upgrade pip
-          pip install jax==0.3.15 jaxlib==0.3.15 jax_md==0.2.0 pymbar==4.0.1 chex==0.1.4 dm-haiku==0.0.7 tqdm
+          pip install jax jaxlib jaxopt networkx parmed pymbar==4.0.1 optax tqdm
       - name: Install DMFF
         run: |
           source $CONDA/bin/activate dmff && pip install .
       - name: Run Tests
         run: |
           source $CONDA/bin/activate dmff
-          pytest -vs tests/test_classical/*
-          pytest -vs tests/test_common/*
-          pytest -vs tests/test_admp/*
-          pytest -vs tests/test_api.py
+          pytest -vs tests/test_classical/test_*
+          pytest -vs tests/test_common/test_*
+          pytest -vs tests/test_admp/test_*
           pytest -vs tests/test_utils.py
-          pytest -vs tests/test_mbar/*     
+          pytest -vs tests/test_mbar/test_* 
+          pytest -vs tests/test_sgnn/test_*

.gitignore

@@ -785,3 +785,10 @@ FodyWeavers.xsd
 
 # hmtff cache
 *.hmtff/
+
+# debugging ipynb
+debug.ipynb
+test.xml
+
+# PyCharm Cache
+.idea/

README.md

@@ -1,6 +1,6 @@
 # DMFF
 
-[![doi:10.26434/chemrxiv-2022-2c7gv](https://img.shields.io/badge/DOI-10.26434%2Fchemrxiv--2022--2c7gv-blue)](https://doi.org/10.26434/chemrxiv-2022-2c7gv)
+[![DOI: 10.1021/acs.jctc.2c01297](https://img.shields.io/badge/DOI-10.1021%2Facs.jctc.2c01297-blue)](https://pubs.acs.org/doi/10.1021/acs.jctc.2c01297)
 
 ## About DMFF
 
@@ -10,24 +10,34 @@ The behavior of organic molecular systems (e.g., protein folding, polymer struct
 
 ### License and credits
 
-The project DMFF is licensed under [GNU LGPL v3.0](LICENSE). If you use this code in any future publications, please cite this using `Wang X, Li J, Yang L, Chen F, Wang Y, Chang J, et al. DMFF: An Open-Source Automatic
-Differentiable Platform for Molecular Force Field
-Development and Molecular Dynamics
-Simulation. ChemRxiv. Cambridge: Cambridge Open Engage; 2022;  This content is a preprint and has not been peer-reviewed.`
+The project DMFF is licensed under [GNU LGPL v3.0](LICENSE). If you use this code in any future publications, please cite this using `Xinyan Wang, Jichen Li, Lan Yang, Feiyang Chen, Yingze Wang, Junhan Chang, Junmin Chen, Wei Feng, Linfeng Zhang, and Kuang Yu 
+Journal of Chemical Theory and Computation 2023 19 (17), 5897-5909
+DOI: 10.1021/acs.jctc.2c01297`
 
 ## User Guide
 
-+ [1. Introduction](docs/user_guide/introduction.md)
-+ [2. Installation](docs/user_guide/installation.md)
-+ [3. Basic usage](docs/user_guide/usage.md)
-+ [4. XML format force field](docs/user_guide/xml_spec.md)
-+ [5. Theory](docs/user_guide/theory.md)
++ [1. Introduction](docs/user_guide/1.introduction.md)
++ [2. Installation](docs/user_guide/2.installation.md)
++ [3. Basic Usage](docs/user_guide/3.usage.md)
++ [4. Modules](docs/user_guide/4.modules.md)
+  + [Classical](docs/user_guide/4.1classical.md)
+  + [ADMP](docs/user_guide/4.2ADMPPmeForce.md)
+  + [Qeq](docs/user_guide/4.3ADMPQeqForce.md)
+  + [Machine Learning](docs/user_guide/4.4MLForce.md)
+  + [Optimization](docs/user_guide/4.5Optimization.md)
+  + [Mbar Estimator](docs/user_guide/4.6MBAR.md)
+  + [OpenMM Plugin](docs/user_guide/4.7OpenMMplugin.md)
++ [5. Advanced examples](docs/user_guide/DMFF_example.ipynb)
++ [And here is a tutorial notebook of the basic usage of DMFF. Welcome to read it and get started with DMFF!](docs/user_guide/test.ipynb)
+
+[And here is a tutorial notebook, which would tell you some basic usage of DMFF. Welcome to read it and get started witn DMFF！](docs/user_guide/test.ipynb)
 
 ## Developer Guide
 + [1. Introduction](docs/dev_guide/introduction.md)
 + [2. Software architecture](docs/dev_guide/arch.md)
 + [3. Coding conventions](docs/dev_guide/convention.md)
 + [4. Document writing](docs/dev_guide/write_docs.md)
++ [5. An example for developing: how to write a generator?](docs/dev_guide/generator.ipynb)
 
 ## Code Structure
 
@@ -38,11 +48,15 @@ The code is organized as follows:
 + `package`: files for constructing packages or images, such as conda recipe and docker files.
 + `tests`: unit tests.
 + `dmff`: DMFF python codes
++ `dmff/api`: source code of application programming interface of DMFF.
 + `dmff/admp`: source code of automatic differentiable multipolar polarizable (ADMP) force field module.
 + `dmff/classical`: source code of classical force field module.
 + `dmff/common`: source code of common functions, such as neighbor list.
-+ `dmff/generators`: source code of force generators.
 + `dmff/sgnn`: source of subgragh neural network force field model.
++ `dmff/eann`: source of embedded atom neural network force field model.
++ `dmff/generators`: source code of force generators.
++ `dmff/operators`: source code of operators.
+
 
 ## Support and Contribution
 

backend/openmm_dmff_plugin/README.md

@@ -2,7 +2,7 @@
 
 
 This is a plugin for [OpenMM](http://openmm.org) that used the trained JAX model by [DMFF](https://github.com/deepmodeling/DMFF) as an independent Force class for dynamics.
-To use it, you need to save you DMFF model with the script in `DMFF/backend/save_dmff2tf.py`.
+To use it, you need to save your DMFF model with the script in `DMFF/backend/save_dmff2tf.py`.
 
 ## Installation
 
@@ -15,10 +15,9 @@ conda create -n dmff_omm -c conda-forge python=3.9 openmm cudatoolkit=11.6
 conda activate dmff_omm
 ```
 ### Download `libtensorflow_cc` and install `cppflow` package
-Install the precompiled libtensorflow_cc library from deepmodeling channel.
+Install the precompiled libtensorflow_cc library from conda.
 ```shell
-
-conda install -c deepmodeling libtensorflow_cc=2.9.1=cuda112h02da4e0_0
+conda install -y libtensorflow_cc=2.9.1 -c conda-forge
 ```
 Download the tensorflow sources file. Copy the `c` direcotry in source code to installed header files of tensorflow library, since it's needed by package `cppflow`.
 ```shell
@@ -37,9 +36,9 @@ mkdir ${CONDA_PREFIX}/include/cppflow
 cp -r include/cppflow ${CONDA_PREFIX}/include/
 ```
 
-### Install the OpenMM DMFF plugin from source 
+### Install the OpenMM DMFF plugin from the source 
 
-Compile the plugin from source with following steps.
+Compile the plugin from the source with the following steps.
 1. Set up environment variables.
    ```shell
    export OPENMM_INSTALLED_DIR=$CONDA_PREFIX
@@ -49,7 +48,7 @@ Compile the plugin from source with following steps.
    mkdir build && cd build
    ```
 
-2. Run `cmake` command with required parameters.
+2. Run `cmake` command with the required parameters.
    ```shell
    cmake .. -DOPENMM_DIR=${OPENMM_INSTALLED_DIR} -DCPPFLOW_DIR=${CPPFLOW_INSTALLED_DIR} -DTENSORFLOW_DIR=${LIBTENSORFLOW_INSTALLED_DIR}
    make && make install

backend/openmm_dmff_plugin/openmmapi/include/DMFFForce.h

@@ -50,7 +50,7 @@ typedef double ENERGYTYPE;
 #else
 typedef float FORCETYPE;
 typedef float COORDTYPE;
-typedef float ENERGYTYPE;
+typedef double ENERGYTYPE;
 #endif
 
 namespace DMFFPlugin {
@@ -71,6 +71,12 @@ class OPENMM_EXPORT_DMFF DMFFForce : public OpenMM::Force {
      * @param energyCoefficient : the energy transform coefficient.
      */
     void setUnitTransformCoefficients(const double coordCoefficient, const double forceCoefficient, const double energyCoefficient);
+    /**
+     * @brief Set the has_aux flag when model was saved with auxilary input.
+     * 
+     * @param hasAux  : true if model was saved with auxilary input.
+     */
+    void setHasAux(const bool hasAux);
 
     const std::string& getDMFFGraphFile() const;
     /**
@@ -97,6 +103,13 @@ class OPENMM_EXPORT_DMFF DMFFForce : public OpenMM::Force {
      * @return double
      */
     double getCutoff() const;
+    /**
+     * @brief Get the Has Aux object
+     * 
+     * @return true 
+     * @return false 
+     */
+    bool getHasAux() const;
     void updateParametersInContext(OpenMM::Context& context);
     bool usesPeriodicBoundaryConditions() const {
         return use_pbc;
@@ -106,6 +119,7 @@ class OPENMM_EXPORT_DMFF DMFFForce : public OpenMM::Force {
 private:
     string graph_file;
     bool use_pbc = true;
+    bool has_aux = false;
     double cutoff = 1.2;
     double coordCoeff, forceCoeff, energyCoeff;