From 42c0672d524b9ad000d3201e9f20ec49627cc9e6 Mon Sep 17 00:00:00 2001
From: Jia-Xin Zhu <jiaxinzhu@stu.xmu.edu.cn>
Date: Fri, 16 Aug 2024 23:17:44 +0800
Subject: [PATCH] update doc and comment for `ethresh` in pme

---
 dmff/admp/pme.py                   | 4 ++--
 docs/admp/readme.md                | 4 ++--
 docs/user_guide/4.2ADMPPmeForce.md | 5 ++---
 docs/user_guide/4.3ADMPQeqForce.md | 2 +-
 4 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/dmff/admp/pme.py b/dmff/admp/pme.py
index 4efa78bc6..60b5d76e8 100755
--- a/dmff/admp/pme.py
+++ b/dmff/admp/pme.py
@@ -65,7 +65,7 @@ def __init__(
             rc:
                 float: cutoff distance
             ethresh:
-                float: pme energy threshold
+                float: (empirical) average relative error in the PME forces
             lmax:
                 int: max L for multipoles
             lpol:
@@ -441,7 +441,7 @@ def setup_ewald_parameters(
     rc: float
         The cutoff distance, in nm
     ethresh: float
-        Required energy precision, in kJ/mol
+        (Empirical) average relative error in the PME forces
     box: ndarray, optional
         3*3 matrix, box size, a, b, c arranged in rows, used in openmm method
     spacing: float, optional
diff --git a/docs/admp/readme.md b/docs/admp/readme.md
index b0e157372..e94eacb27 100644
--- a/docs/admp/readme.md
+++ b/docs/admp/readme.md
@@ -112,7 +112,7 @@ In `run.py`, when creating the potential function, several key parameters are no
 ```python
 potentials = H.createPotential(pdb.topology, nonbondedCutoff=rc*angstrom, nonbondedMethod=CutoffPeriodic, ethresh=1e-4)
 ```
-* `ethresh`: this is the energy threshold for PME
+* `ethresh`: the (empirical) average relative error in the PME forces, which is used to setup the size of the meshgrid of PME (see [openmm doc](http://docs.openmm.org/latest/userguide/theory/02_standard_forces.html#coulomb-interaction-with-particle-mesh-ewald) for more details).
 * `rc`: the cutoff distance. `rc`, `ethresh`, and `box` together, determine the $K_{max}$ and $\kappa$
    (please see [theory](../user_guide/theory.md)).
    Note that the `rc` variable in here is only used to determine the PME settings. The user has to make sure the `rc`
@@ -161,7 +161,7 @@ LastAxisTypeIndex = 6
 
 * `rc`: cutoff distance in real space. Only used to determine the PME settings.
 
-* `ethresh`: energy threshold for PME.
+* `ethresh`: (empirical) average relative error in the PME forces, which is used to setup the size of the meshgrid of PME (see [openmm doc](http://docs.openmm.org/latest/userguide/theory/02_standard_forces.html#coulomb-interaction-with-particle-mesh-ewald) for more details).
 
 * `lmax`: max L for multipoles.
 
diff --git a/docs/user_guide/4.2ADMPPmeForce.md b/docs/user_guide/4.2ADMPPmeForce.md
index 70e8394e0..6e419a558 100644
--- a/docs/user_guide/4.2ADMPPmeForce.md
+++ b/docs/user_guide/4.2ADMPPmeForce.md
@@ -215,7 +215,7 @@ A few keywords in `createPotential` would impact the behavior of the function:
   settings.POL_COV = 2.0
   ```
 
-* `ethresh`: the accuracy of PME, used to setup the size of the meshgrid of PME.
+* `ethresh`: the (empirical) average relative error in the PME forces, which is used to setup the size of the meshgrid of PME (see [openmm doc](http://docs.openmm.org/latest/userguide/theory/02_standard_forces.html#coulomb-interaction-with-particle-mesh-ewald) for more details).
 
 A typical `xml` file to define an ADMPDispPmeForce frontend is:
 
@@ -255,8 +255,7 @@ generator_pme = H.getGenerators()[0] # if ADMPDispPmeForce is the First force no
 ```
 The keyword `ethresh` in `createPotential` would impact the behavior of the function:
 
-* `ethresh`: the accuracy of PME, used to setup the size of the meshgrid of PME.
-
+* `ethresh`: the (empirical) average relative error in the PME forces, which is used to setup the size of the meshgrid of PME (see [openmm doc](http://docs.openmm.org/latest/userguide/theory/02_standard_forces.html#coulomb-interaction-with-particle-mesh-ewald) for more details).
 
 
 ## 3. ADMPPmeGenerator Doc
diff --git a/docs/user_guide/4.3ADMPQeqForce.md b/docs/user_guide/4.3ADMPQeqForce.md
index 9c9812ffc..75802590a 100644
--- a/docs/user_guide/4.3ADMPQeqForce.md
+++ b/docs/user_guide/4.3ADMPQeqForce.md
@@ -205,7 +205,7 @@ A few keywords in `createPotential` would impact the behavior of the function:
 * `const_list`: the atomic numbers of all residues with different constraints.
 * `const_vals`: the corresponding constraint valu on each residue.
 
-* `ethresh`: the accuracy of PME, used to setup the size of the meshgrid of PME.
+* `ethresh`: the (empirical) average relative error in the PME forces, which is used to setup the size of the meshgrid of PME (see [openmm doc](http://docs.openmm.org/latest/userguide/theory/02_standard_forces.html#coulomb-interaction-with-particle-mesh-ewald) for more details).
 * `has_aux`: bool type, whether to intruduce auxilliary parameters, equilibrated atomic charges, etc.
 
 ## 3. ADMPQeqGenerator Doc