Applied edits/optimizations suggested by Axel. Further simplifified/fixed MC acceptance equations, few clarifications to documentation.

doc/src/fix_charge_regulation.rst

@@ -1,22 +1,18 @@
 
-.. Yuan documentation master file, created by
-   sphinx-quickstart on Sat Jan 30 14:06:22 2021.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-   tc387: Multiple text additions/changes, Feb 2 2021
-.. index:: fix fix_charge_regulation
+.. index:: fix charge/regulation
 
-fix_charge_regulation command
+fix charge/regulation command
 =============================
+
 Syntax
 """"""
 
 .. parsed-literal::
    
-    fix ID group-ID charge_regulation cation_type anion_type keyword value(s)
+    fix ID group-ID charge/regulation cation_type anion_type keyword value(s)
 
 * ID, group-ID are documented in fix command
-* charge_regulation = style name of this fix command
+* charge/regulation = style name of this fix command
 * cation_type = atom type of free cations
 * anion_type = atom type of free anions
   
@@ -51,9 +47,9 @@ Examples
 """"""""
 .. code-block:: LAMMPS
 
-    fix chareg all charge_regulation 1 2 acid_type 3 base_type 4 pKa 5 pKb 7 lb 1.0 nevery 200 nexchange 200 seed 123 tempfixid fT 
+    fix chareg all charge/regulation 1 2 acid_type 3 base_type 4 pKa 5 pKb 7 lb 1.0 nevery 200 nexchange 200 seed 123 tempfixid fT 
 
-    fix chareg all charge_regulation 1 2 pIp 3 pIm 3 tempfixid fT tag yes onlysalt yes 2 -1
+    fix chareg all charge/regulation 1 2 pIp 3 pIm 3 onlysalt yes 2 -1 seed 123 tag yes temp 1.0
 
 Description
 """""""""""
@@ -75,7 +71,7 @@ An acid ionization reaction (:math:`\mathrm{A} \rightleftharpoons \mathrm{A}^-+\
 
 .. code-block:: LAMMPS
 
-    fix acid_reaction all charge_regulation 2 3 acid_type 1 pH 7.0 pKa 5.0 pIp 7.0 pIm 7.0
+    fix acid_reaction all charge/regulation 2 3 acid_type 1 pH 7.0 pKa 5.0 pIp 7.0 pIm 7.0
 
 where the fix attempts to charge :math:`\mathrm{A}` (discharge :math:`\mathrm{A}^-`) to :math:`\mathrm{A}^-` (:math:`\mathrm{A}`) and insert (delete) a proton (atom type 2). Besides, the fix implements self-ionization reaction of water :math:`\emptyset \rightleftharpoons \mathrm{H}^++\mathrm{OH}^-`.
 However, this approach is highly inefficient at :math:`\mathrm{pH} \approx 7` when the concentration of both protons and hydroxyl ions is low, resulting in a relatively low acceptance rate of MC moves.
@@ -85,7 +81,7 @@ participate in ionization reactions, which can be easily achieved via
 
 .. code-block:: LAMMPS
 
-    fix acid_reaction all charge_regulation 4 5 acid_type 1 pH 7.0 pKa 5.0 pIp 2.0 pIm 2.0
+    fix acid_reaction all charge/regulation 4 5 acid_type 1 pH 7.0 pKa 5.0 pIp 2.0 pIm 2.0
 
 where particles of atom type 4 and 5 are the salt cations and anions, both at chemical potential pI=2.0, see :ref:`(Curk1) <Curk1>` and :ref:`(Landsgesell) <Landsgesell>` for more details.
 
@@ -94,14 +90,14 @@ where particles of atom type 4 and 5 are the salt cations and anions, both at ch
 
 .. code-block:: LAMMPS
 
-    fix base_reaction all charge_regulation 2 3 base_type 6 pH 7.0 pKb 6.0 pIp 7.0 pIm 7.0
+    fix base_reaction all charge/regulation 2 3 base_type 6 pH 7.0 pKb 6.0 pIp 7.0 pIm 7.0
     
 where the fix will attempt to charge :math:`\mathrm{B}` (discharge :math:`\mathrm{B}^+`) to :math:`\mathrm{B}^+` (:math:`\mathrm{B}`) and insert (delete) a hydroxyl ion  :math:`\mathrm{OH}^-` of atom type 3.
 If neither the acid or the base type is specified, for example, 
 
 .. code-block:: LAMMPS
 
-    fix salt_reaction all charge_regulation 4 5 pIp 2.0 pIm 2.0
+    fix salt_reaction all charge/regulation 4 5 pIp 2.0 pIm 2.0
     
 the fix simply inserts or deletes an ion pair of a free cation (atom type 4) and a free anion (atom type 5) as done in a conventional grand-canonical MC simulation.
 
@@ -119,7 +115,7 @@ Note that LAMMPS implicitly assumes a constant number of particles (degrees of f
 
 The chemical potential units (e.g. pH) are in the standard log10 representation assuming reference concentration :math:`\rho_0 = \mathrm{mol}/\mathrm{l}`. 
 Therefore, to perform the internal unit conversion, the length (in nanometers) of the LAMMPS unit length 
-must be specified via *lunit_nm* (default is set to the Bjerrum length in water at room temprature *lunit_nm* = 0.72nm). For example, in the dilute ideal solution limit, the concentration of free ions 
+must be specified via *lunit_nm* (default is set to the Bjerrum length in water at room temprature *lunit_nm* = 0.71nm). For example, in the dilute ideal solution limit, the concentration of free ions 
 will be :math:`c_\mathrm{I} = 10^{-\mathrm{pIp}}\mathrm{mol}/\mathrm{l}`.
 
 The temperature used in MC acceptance probability is set by  *temp*. This temperature should be the same as the temperature set by the molecular dynamics thermostat. For most purposes, it is probably best to use *tempfixid* keyword which dynamically sets the temperature equal to the chosen MD thermostat temperature, in the example above we assumed the thermostat fix-ID is *fT*. The inserted particles attain a random velocity corresponding to the specified temperature. Using *tempfixid* overrides any fixed temperature set by *temp*.   
@@ -138,14 +134,14 @@ The *group* keyword can be used to add inserted particles to a specific group-ID
 
 Output
 """"""
-This fix computes a global vector of length 8, which can be accessed by various output commands. The vector values are the following global cumulative quantities:
+This fix computes a global vector of length 8, which can be accessed by various output commands. The vector values are the following global quantities:
 
 * 1 = cumulative MC attempts
 * 2 = cumulative MC successes
 * 3 = current # of neutral acid atoms 
 * 4 = current # of -1 charged acid atoms 
 * 5 = current # of neutral base atoms 
-* 6 = current # of +1 charged acid atoms 
+* 6 = current # of +1 charged base atoms 
 * 7 = current # of free cations 
 * 8 = current # of free anions
 
@@ -157,6 +153,8 @@ See the :doc:`Build package <Build_package>` doc page for more info.
 
 The :doc:`atom_style <atom_style>`, used must contain the charge property, for example, the style could be *charge* or *full*. Only usable for 3D simulations. Atoms specified as free ions cannot be part of rigid bodies or molecules and cannot have bonding interactions. The scheme is limited to integer charges, any atoms with non-integer charges will not be considered by the fix.
 
+All interaction potentials used must be continuous, otherwise the MD integration and the particle exchange MC moves do not correspond to the same equilibrium ensemble. For example, if an lj/cut pair style is used, the LJ potential must be shifted so that it vanishes at the cutoff. This can be easily achieved  using the :doc:`pair_modify <pair_modify>` command, i.e., by using:  *pair_modify shift yes*.
+
 Note: Region restrictions are not yet implemented. 
 
 Related commands
@@ -167,7 +165,7 @@ Related commands
 
 Default
 """""""
-pH = 7.0; pKa = 100.0; pKb = 100.0; pIp = 5.0; pIm = 5.0; pKs=14.0; acid_type = -1; base_type = -1; lunit_nm = 0.72; temp = 1.0; nevery = 100; nmc = 100; xrd = 0; seed = 2345; tag = no; onlysalt = no, pmcmoves = 0.33 0.33 0.33, group-ID = all
+pH = 7.0; pKa = 100.0; pKb = 100.0; pIp = 5.0; pIm = 5.0; pKs = 14.0; acid_type = -1; base_type = -1; lunit_nm = 0.71; temp = 1.0; nevery = 100; nmc = 100; xrd = 0; seed = 0; tag = no; onlysalt = no, pmcmoves = [1/3, 1/3, 1/3], group-ID = all
 
 ----------
 
@@ -181,4 +179,4 @@ pH = 7.0; pKa = 100.0; pKb = 100.0; pIp = 5.0; pIm = 5.0; pKs=14.0; acid_type =
 
 .. _Landsgesell:
 
-**(Landsgesell)** J. Landsgesell, P. Hebbeker, O. Rud, R. Lunkad, P. Kosovan, and C. Holm, “Grand-reaction method for simulations of ionization equilibria coupled to ion partitioning,” Macromolecules 53, 3007–3020 (2020).
+**(Landsgesell)** J. Landsgesell, P. Hebbeker, O. Rud, R. Lunkad, P. Kosovan, and C. Holm, "Grand-reaction method for simulations of ionization equilibria coupled to ion partitioning", Macromolecules 53, 3007–3020 (2020).