reformat docs, correct spelling errors, and update false positives list

doc/src/fix_charge_regulation.rst

@@ -53,58 +53,98 @@ Examples
 
 Description
 """""""""""
-This fix performs Monte Carlo (MC) sampling of charge regulation and exchange of ions with a reservoir as discussed in :ref:`(Curk1) <Curk1>` and :ref:`(Curk2) <Curk2>`.  
-The implemented method is largely analogous to the grand-reaction ensemble method in :ref:`(Landsgesell) <Landsgesell>`.
-The implementation is parallelized, compatible with existing LAMMPS functionalities, and applicable to any system utilizing discreet, ionizable groups or surface sites.
 
+This fix performs Monte Carlo (MC) sampling of charge regulation and
+exchange of ions with a reservoir as discussed in :ref:`(Curk1) <Curk1>`
+and :ref:`(Curk2) <Curk2>`.  The implemented method is largely analogous
+to the grand-reaction ensemble method in :ref:`(Landsgesell)
+<Landsgesell>`.  The implementation is parallelized, compatible with
+existing LAMMPS functionalities, and applicable to any system utilizing
+discrete, ionizable groups or surface sites.
 
-Specifically, the fix implements the following three types of  MC moves, which discretely change the charge state of individual particles and insert ions into the systems: :math:`\mathrm{A} \rightleftharpoons \mathrm{A}^-+\mathrm{X}^+`, :math:`\mathrm{B} \rightleftharpoons \mathrm{B}^++\mathrm{X}^-`,
+Specifically, the fix implements the following three types of MC moves,
-and :math:`\emptyset \rightleftharpoons Z^-\mathrm{X}^{Z^+}+Z^+\mathrm{X}^{-Z^-}`.
+which discretely change the charge state of individual particles and
-In the former two types of reactions, Monte Carlo moves alter the charge value of specific atoms (:math:`\mathrm{A}`,  :math:`\mathrm{B}`) and simultaneously insert a counterion to preserve the charge neutrality of the system, modeling the dissociation/association process.
+insert ions into the systems: :math:`\mathrm{A} \rightleftharpoons
-The last type of reaction performs grand canonical MC exchange of ion pairs with a (fictitious) reservoir.
+\mathrm{A}^-+\mathrm{X}^+`, :math:`\mathrm{B} \rightleftharpoons
+\mathrm{B}^++\mathrm{X}^-`, and :math:`\emptyset \rightleftharpoons
+Z^-\mathrm{X}^{Z^+}+Z^+\mathrm{X}^{-Z^-}`.  In the former two types of
+reactions, Monte Carlo moves alter the charge value of specific atoms
+(:math:`\mathrm{A}`, :math:`\mathrm{B}`) and simultaneously insert a
+counterion to preserve the charge neutrality of the system, modeling the
+dissociation/association process.  The last type of reaction performs
+grand canonical MC exchange of ion pairs with a (fictitious) reservoir.
 
-In our implementation "acid" refers to particles that can attain charge :math:`q=\{0,-1\}` and "base" to particles with :math:`q=\{0,1\}`,
+In our implementation "acid" refers to particles that can attain charge
-whereas the MC exchange of free ions allows any integer charge values of :math:`{Z^+}` and :math:`{Z^-}`.
+:math:`q=\{0,-1\}` and "base" to particles with :math:`q=\{0,1\}`,
+whereas the MC exchange of free ions allows any integer charge values of
+:math:`{Z^+}` and :math:`{Z^-}`.
 
-Here we provide  several practical examples for modeling charge regulation effects in solvated systems.
+Here we provide several practical examples for modeling charge
-An acid ionization reaction (:math:`\mathrm{A} \rightleftharpoons \mathrm{A}^-+\mathrm{H}^+`) can be defined via a single line in the input file
+regulation effects in solvated systems.  An acid ionization reaction
+(:math:`\mathrm{A} \rightleftharpoons \mathrm{A}^-+\mathrm{H}^+`) can be
+defined via a single line in the input file
 
 .. 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
 
-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}^-`.
+where the fix attempts to charge :math:`\mathrm{A}` (discharge
-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.
+: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.
 
-A more efficient way is to allow salt ions to 
+A more efficient way is to allow salt ions to participate in ionization
-participate in ionization reactions, which can be easily achieved via 
+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
 
-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.
+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.
 
 
- Similarly, we could have simultanously added a base ionization reaction (:math:`\mathrm{B} \rightleftharpoons \mathrm{B}^++\mathrm{OH}^-`)  
+ Similarly, we could have simultaneously added a base ionization reaction
+ (:math:`\mathrm{B} \rightleftharpoons \mathrm{B}^++\mathrm{OH}^-`)
 
 .. 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
 
-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.
+where the fix will attempt to charge :math:`\mathrm{B}` (discharge
-If neither the acid or the base type is specified, for example, 
+: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
 
-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.
+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.
 
 
-The fix is compatible with LAMMPS sub-packages such as *molecule* or *rigid*. That said, the acid and base particles can be part of larger molecules or rigid bodies. Free ions that are inserted to or deleted from the system must be defined as single particles (no bonded interactions allowed) and cannot be part of larger molecules or rigid bodies. If *molecule* package is used, all inserted ions have a molecule ID equal to zero.
+The fix is compatible with LAMMPS sub-packages such as *molecule* or
+*rigid*. That said, the acid and base particles can be part of larger
+molecules or rigid bodies. Free ions that are inserted to or deleted
+from the system must be defined as single particles (no bonded
+interactions allowed) and cannot be part of larger molecules or rigid
+bodies. If *molecule* package is used, all inserted ions have a molecule
+ID equal to zero.
 
-Note that LAMMPS implicitly assumes a constant number of particles (degrees of freedom). Since using this fix alters the total number of particles during the simulation, any thermostat used by LAMMPS, such as NVT or Langevin, must use a dynamic calculation of system temperature. This can be achieved by specifying a dynamic temperature compute (e.g. dtemp) and using it with the desired thermostat, e.g. a Langevin thermostat:
+Note that LAMMPS implicitly assumes a constant number of particles
+(degrees of freedom). Since using this fix alters the total number of
+particles during the simulation, any thermostat used by LAMMPS, such as
+NVT or Langevin, must use a dynamic calculation of system
+temperature. This can be achieved by specifying a dynamic temperature
+compute (e.g. dtemp) and using it with the desired thermostat, e.g. a
+Langevin thermostat:
 
 .. code-block:: LAMMPS
 
@@ -113,28 +153,64 @@ Note that LAMMPS implicitly assumes a constant number of particles (degrees of f
     fix fT all langevin 1.0 1.0 1.0 123
     fix_modify fT temp dtemp
 
-The chemical potential units (e.g. pH) are in the standard log10 representation assuming reference concentration :math:`\rho_0 = \mathrm{mol}/\mathrm{l}`. 
+The chemical potential units (e.g. pH) are in the standard log10
-Therefore, to perform the internal unit conversion, the length (in nanometers) of the LAMMPS unit length 
+representation assuming reference concentration :math:`\rho_0 =
-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 
+\mathrm{mol}/\mathrm{l}`.  Therefore, to perform the internal unit
-will be :math:`c_\mathrm{I} = 10^{-\mathrm{pIp}}\mathrm{mol}/\mathrm{l}`.
+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 temperature *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*.   
+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*.
 
-The *xrd* keyword can be used to restrict the inserted/deleted counterions to a specific radial distance from an acid or base particle that is currently participating in a reaction. This can be used to simulate more realist reaction dynamics. If *xrd* = 0 or *xrd* > *L* / 2, where *L* is the smallest box dimension, the radial restriction is automatically turned off and free ion can be inserted or deleted anywhere in the simulation box. 
+The *xrd* keyword can be used to restrict the inserted/deleted
+counterions to a specific radial distance from an acid or base particle
+that is currently participating in a reaction. This can be used to
+simulate more realist reaction dynamics. If *xrd* = 0 or *xrd* > *L* /
+2, where *L* is the smallest box dimension, the radial restriction is
+automatically turned off and free ion can be inserted or deleted
+anywhere in the simulation box.
 
-If the *tag yes* is used, every inserted atom gets a unique tag ID, otherwise, the tag of every inserted atom is set to 0. *tag yes* might cause an integer overflow in very long simulations since the tags are unique to every particle and thus increase with every successful particle insertion. 
+If the *tag yes* is used, every inserted atom gets a unique tag ID,
+otherwise, the tag of every inserted atom is set to 0. *tag yes* might
+cause an integer overflow in very long simulations since the tags are
+unique to every particle and thus increase with every successful
+particle insertion.
 
-The *pmcmoves* keyword sets the relative probability of attempting the three types of MC moves (reactions): acid charging, base charging, and ion pair exchange. 
+The *pmcmoves* keyword sets the relative probability of attempting the
-The fix only attempts to perform particle charging MC moves if *acid_type* or *base_type* is defined. Otherwise fix only performs free ion insertion/deletion. For example, if *acid_type* is not defined, *pmcA* is automatically set to 0. The vector *pmcmoves* is automatically normalized, for example, if set to *pmcmoves* 0 0.33 0.33, the vector would be normalized to [0,0.5,0.5]. 
+three types of MC moves (reactions): acid charging, base charging, and
+ion pair exchange.  The fix only attempts to perform particle charging
+MC moves if *acid_type* or *base_type* is defined. Otherwise fix only
+performs free ion insertion/deletion. For example, if *acid_type* is not
+defined, *pmcA* is automatically set to 0. The vector *pmcmoves* is
+automatically normalized, for example, if set to *pmcmoves* 0 0.33 0.33,
+the vector would be normalized to [0,0.5,0.5].
 
-The *only_salt* option can be used to perform multivalent grand-canonical ion-exchange moves. If *only_salt yes* is used, no charge exchange is performed, only ion insertion/deletion (*pmcmoves* is set to [0,0,1]), but ions can be multivalent. In the example above, an MC move would consist of three ion insertion/deletion to preserve the charge neutrality of the system.
+The *only_salt* option can be used to perform multivalent
+grand-canonical ion-exchange moves. If *only_salt yes* is used, no
+charge exchange is performed, only ion insertion/deletion (*pmcmoves* is
+set to [0,0,1]), but ions can be multivalent. In the example above, an
+MC move would consist of three ion insertion/deletion to preserve the
+charge neutrality of the system.
 
-The *group* keyword can be used to add inserted particles to a specific group-ID. All inserted particles are automatically added to group *all*.
+The *group* keyword can be used to add inserted particles to a specific
+group-ID. All inserted particles are automatically added to group *all*.
 
 
 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 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
@@ -148,12 +224,24 @@ This fix computes a global vector of length 8, which can be accessed by various
 
 Restrictions
 """"""""""""
-This fix is part of the USER-MISC package. It is only enabled if LAMMPS was built with that package.
-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.
+This fix is part of the USER-MISC package. It is only enabled if LAMMPS
+was built with that package.  See the :doc:`Build package
+<Build_package>` doc page for more info.
 
-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*.
+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.
 

doc/utils/sphinx-config/false_positives.txt

@@ -260,6 +260,7 @@ bitmask
 bitrate
 bitrates
 Bitzek
+Bjerrum
 Blaise
 blanchedalmond
 blocksize
@@ -500,6 +501,8 @@ coulgauss
 coulombic
 Coulombic
 Coulombics
+counterion
+counterions
 Courant
 covalent
 covalently
@@ -728,6 +731,7 @@ DRUDE
 dsf
 dsmc
 dt
+dtemp
 dtgrow
 dtheta
 dtshrink
@@ -876,6 +880,7 @@ equilibrates
 equilibrating
 equilibration
 Equilibria
+equilibria
 equilization
 equipartitioning
 Ercolessi
@@ -1210,6 +1215,7 @@ hbnewflag
 hbond
 hcp
 heatconduction
+Hebbeker
 Hebenstreit
 Hecht
 Heenen
@@ -1277,6 +1283,7 @@ hy
 hydrophobicity
 hydrostatic
 hydrostatically
+hydroxyl
 Hynninen
 Hyoungki
 hyperdynamics
@@ -1367,6 +1374,7 @@ ints
 inv
 invariants
 inversed
+ionizable
 ionocovalent
 iostreams
 iparam
@@ -1546,6 +1554,7 @@ Koning
 Kooser
 Korn
 Koskinen
+Kosovan
 Koster
 Kosztin
 Kp
@@ -1591,6 +1600,7 @@ Lamoureux
 Lanczos
 Lande
 Landron
+Landsgesell
 langevin
 Langevin
 Langston
@@ -1728,10 +1738,13 @@ lpsapi
 lrt
 lsfftw
 ltbbmalloc
+Lua
 lubricateU
 lucy
-Lua
 Luding
+Luijten
+lunit
+Lunkad
 Lussetti
 Lustig
 lval
@@ -2015,6 +2028,7 @@ multiscale
 multisectioning
 multithreading
 Multithreading
+multivalent
 Mundy
 Murdick
 Murtola
@@ -2060,6 +2074,7 @@ Nanoletters
 nanomechanics
 nanometer
 nanometers
+nanoparticle
 nanoparticles
 Nanotube
 nanotube
@@ -2167,6 +2182,7 @@ nm
 Nm
 Nmax
 nmax
+nmc
 Nmin
 nmin
 Nmols
@@ -2299,6 +2315,7 @@ omp
 OMP
 onelevel
 oneway
+onlysalt
 onn
 ons
 OO
@@ -2380,6 +2397,8 @@ pbc
 pc
 pchain
 Pchain
+pcmoves
+pmcmoves
 Pdamp
 pdb
 pdf
@@ -2424,6 +2443,7 @@ phosphide
 Phs
 Physica
 physik
+pI
 Piaggi
 picocoulomb
 picocoulombs
@@ -2435,7 +2455,9 @@ pid
 piecewise
 Pieniazek
 Pieter
+pIm
 pimd
+pIp
 Piola
 Pisarev
 Pishevar
@@ -2450,6 +2472,9 @@ ploop
 PloS
 plt
 plumedfile
+pKa
+pKb
+pKs
 pmb
 Pmolrotate
 Pmoltrans
@@ -2768,6 +2793,7 @@ rst
 rstyle
 Rubensson
 Rubia
+Rud
 Rudd
 Rudra
 Rudranarayan