From a7a66100c6b9d57b21a988c1e379235f4ca59d00 Mon Sep 17 00:00:00 2001 From: Trung Nguyen Date: Fri, 11 Mar 2022 14:13:34 -0600 Subject: [PATCH] Updated the doc page of the polarize fixes --- doc/src/fix_polarize.rst | 81 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 74 insertions(+), 7 deletions(-) diff --git a/doc/src/fix_polarize.rst b/doc/src/fix_polarize.rst index e130d3010d..5e039067b7 100644 --- a/doc/src/fix_polarize.rst +++ b/doc/src/fix_polarize.rst @@ -21,7 +21,7 @@ Syntax * ID, group-ID are documented in :doc:`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 ` 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 ` and +:doc:`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 `d). -There are some example scripts for using this fix -with LAMMPS in the examples/PACKAGES/dielectric directory. +Consider an interface between two media: one with dielectric constant +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 +beyond the conventional fields *id*, *mol*, *type*, *q*, *x*, *y*, and *z*. ---------- @@ -75,12 +110,41 @@ as described in :ref:`(Barros) ` to solve :math:`\sigma_b`. Fix *polarize/bem/icc* employs the successive over-relaxation algorithm as described in :ref:`(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) ` to solve :math:`\sigma_b`. + + +More details on the implementation of these fixes and their recommended use +are described in :ref:`(NguyenTD) `. + Restart, fix_modify, output, run start/stop, minimize info """""""""""""""""""""""""""""""""""""""""""""""""""""""""" -... +No information about this fix is written to :doc:`binary restart files `. + +The :doc:`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 `. +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 `, :doc:`fix polarize `, :doc:`read_data `, +:doc:`pair_style lj/cut/coul/long/dielectric `, +:doc:`kspace_style pppm/dielectric `, :doc:`compute efield/atom ` Default """"""" -None. +*iter_max* = 20 ----------