Merge branch 'dielectric-updates' of github.com:ndtrung81/lammps into collected-small-changes

doc/src/fix_polarize.rst

@@ -21,7 +21,7 @@ Syntax
 * ID, group-ID are documented in :doc:`fix <fix>` command
 * style = *polarize/bem/gmres* or *polarize/bem/icc* or *polarize/functional*
 * Nevery = this fixed is invoked every this many timesteps
-* tolerance = the tolerance for the iterative solver to stop
+* tolerance = the relative tolerance for the iterative solver to stop
 
 
 Examples
@@ -45,10 +45,45 @@ Description
 """""""""""
 
 These fixes compute induced charges at the interface between two
-impermeable media with different dielectric constants.
+impermeable media with different dielectric constants. The interfaces
+need to be discretized into vertices, each representing a boundary element.
+The vertices are treated as if they were regular atoms or particles.
+:doc:`atom_style dielectric <atom_style>` should be used since it defines
+the additional properties of each interface particle such as
+interface normal vectors, element areas, and local dielectric mismatch.
+These fixes also require the use of :doc:`pair_style <pair_style>` and
+:doc:`kspace_style <kspace_style>` with the *dielectric* suffix.
+At every time step, given a configuration of the physical charges in the system
+(such as atoms and charged particles) these fixes compute and update
+the charge of the interface particles. The interfaces are allowed to move
+during the simulation with appropriate time integrators (for example,
+with :doc:`fix_rigid <fix_rigid>`d).
 
-There are some example scripts for using this fix
+Consider an interface between two media: one with dielectric constant
-with LAMMPS in the examples/PACKAGES/dielectric directory.
+of 78 (water), the other of 4 (silica). The interface is discretized
+into 2000 boundary elements, each represented by an interface particle. Suppose that
+each interface particle has a normal unit vector pointing from the silica medium to water.
+The dielectric difference along the normal vector is then 78 - 4 = 74,
+the mean dielectric value is (78 + 4) / 2 = 41. Each boundary element
+also has its area and the local mean curvature (which is used by these fixes
+for computing a correction term in the local electric field).
+To model charged interfaces, the interface particle will have a non-zero charge value,
+coming from its area and surface charge density.
+
+For non-interface particles such as atoms and charged particles,
+the interface normal vectors, element area, and dielectric mismatch are
+irrelevant. Their local dielectric value is used to rescale their actual charge
+when computing the Coulombic interactions. For instance, for a cation carrying
+a charge of +2 (in charge unit) in an implicit solvent with dielectric constant of 40
+would have actual charge of +2, and a local dielectric constant value of 40.
+It is assumed that the particles cannot pass through the interface during the simulation
+so that its local dielectric constant value does not change.
+
+There are some example scripts for using these fixes
+with LAMMPS in the examples/PACKAGES/dielectric directory. The README file
+therein contains specific details on the system setup. Note that the example data files
+show the additional fields (columns) needed for :doc:`atom_style dielectric <atom_style>
+beyond the conventional fields *id*, *mol*, *type*, *q*, *x*, *y*, and *z*.
 
 ----------
 
@@ -75,12 +110,41 @@ as described in :ref:`(Barros) <Barros>` to solve :math:`\sigma_b`.
 Fix *polarize/bem/icc* employs the successive over-relaxation algorithm
 as described in :ref:`(Tyagi) <Tyagi>` to solve :math:`\sigma_b`.
 
-Fix *polarize/functional* ...
+The iterative solvers would terminate either when the maximum relative change
+in the induced charges in consecutive iterations is below the set tolerance,
+or when the number of iterations reaches *iter_max* (see below).
+
+Fix *polarize/functional* employs the energy functional variation approach
+as described in :ref:`(Jadhao) <Jadhao>` to solve :math:`\sigma_b`.
+
+
+More details on the implementation of these fixes and their recommended use
+are described in :ref:`(NguyenTD) <NguyenTD>`.
+
 
 Restart, fix_modify, output, run start/stop, minimize info
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-...
+No information about this fix is written to :doc:`binary restart files <restart>`.
+
+The :doc:`fix_modify <fix_modify>` command provides certain options to
+control the induced charge solver and the initial values of the interface elements:
+
+  .. parsed-literal::
+      *itr_max* arg
+         arg = maximum number of iterations for convergence
+      *dielectrics* ediff emean epsilon area charge
+         ediff = dielectric difference
+         emean = dielectric mean
+         epsilon = local dielectric value
+         aree = element area
+         charge = real interface charge
+
+*polarize/bem/gmres* or *polarize/bem/icc* compute a global 2-element vector
+which can be accessed by various :doc:`output commands <Howto_output>`.
+The first element is the number of iterations when the solver terminates
+(of which the upperbound is set by *iter_max*). The second element is the RMS error.
+
 
 Restrictions
 """"""""""""
@@ -94,12 +158,15 @@ KSPACE package is installed.  See the :doc:`Build package
 Related commands
 """"""""""""""""
 
+:doc:`pair_coeff <pair_coeff>`, :doc:`fix polarize <fix_polarize>`, :doc:`read_data <read_data>`,
+:doc:`pair_style lj/cut/coul/long/dielectric <pair_dielectric>`,
+:doc:`kspace_style pppm/dielectric <kspace_style>`,
 :doc:`compute efield/atom <compute_efield_atom>`
 
 Default
 """""""
 
-None.
+*iter_max* = 20
 
 ----------