From 093fbfd4b5337937fd4f47d4cd7e41445559103d Mon Sep 17 00:00:00 2001
From: Axel Kohlmeyer <akohlmey@gmail.com>
Date: Thu, 19 Aug 2021 05:25:36 -0400
Subject: [PATCH] add documentation for pair style coul/exclude

---
 doc/src/Commands_pair.rst   |  1 +
 doc/src/Developer_utils.rst |  2 +-
 doc/src/pair_coul.rst       | 21 +++++++++++++++++++++
 doc/src/pair_style.rst      |  1 +
 4 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/doc/src/Commands_pair.rst b/doc/src/Commands_pair.rst
index 184fb25300..7cf4e7635b 100644
--- a/doc/src/Commands_pair.rst
+++ b/doc/src/Commands_pair.rst
@@ -75,6 +75,7 @@ OPT.
    * :doc:`coul/debye (gko) <pair_coul>`
    * :doc:`coul/diel (o) <pair_coul_diel>`
    * :doc:`coul/dsf (gko) <pair_coul>`
+   * :doc:`coul/exclude <pair_coul>`
    * :doc:`coul/long (gko) <pair_coul>`
    * :doc:`coul/long/cs (g) <pair_cs>`
    * :doc:`coul/long/dielectric <pair_dielectric>`
diff --git a/doc/src/Developer_utils.rst b/doc/src/Developer_utils.rst
index 60eded42e0..e419520edd 100644
--- a/doc/src/Developer_utils.rst
+++ b/doc/src/Developer_utils.rst
@@ -336,7 +336,7 @@ repetitive tasks.
 The :cpp:class:`LAMMPS_NS::ArgInfo` class provides an abstraction
 for parsing references to compute or fix styles, variables or custom
 integer or double properties handled by :doc:`fix property/atom <fix_property_atom>`.
-These would start with a "c\_", "f\_", "v\_", "d\_", "d2\_", "i\_", or "i2_"
+These would start with a "c\_", "f\_", "v\_", "d\_", "d2\_", "i\_", or "i2\_"
 followed by the ID or name of than instance and may be postfixed with
 one or two array indices "[<number>]" with numbers > 0.
 
diff --git a/doc/src/pair_coul.rst b/doc/src/pair_coul.rst
index 990458887d..4e0793467b 100644
--- a/doc/src/pair_coul.rst
+++ b/doc/src/pair_coul.rst
@@ -10,6 +10,7 @@
 .. index:: pair_style coul/dsf/gpu
 .. index:: pair_style coul/dsf/kk
 .. index:: pair_style coul/dsf/omp
+.. index:: pair_style coul/exclude
 .. index:: pair_style coul/cut/global
 .. index:: pair_style coul/cut/global/omp
 .. index:: pair_style coul/long
@@ -42,6 +43,9 @@ pair_style coul/dsf command
 
 Accelerator Variants: *coul/dsf/gpu*, *coul/dsf/kk*, *coul/dsf/omp*
 
+pair_style coul/exclude command
+===============================
+
 pair_style coul/cut/global command
 ==================================
 
@@ -83,6 +87,7 @@ Syntax
    pair_style coul/cut cutoff
    pair_style coul/debye kappa cutoff
    pair_style coul/dsf alpha cutoff
+   pair_style coul/exclude cutoff
    pair_style coul/cut/global cutoff
    pair_style coul/long cutoff
    pair_style coul/wolf alpha cutoff
@@ -110,6 +115,9 @@ Examples
    pair_style coul/dsf 0.05 10.0
    pair_coeff * *
 
+   pair_style hybrid/overlay coul/exclude 10.0 ...
+   pair_coeff * * coul/exclude
+
    pair_style coul/long 10.0
    pair_coeff * *
 
@@ -257,6 +265,19 @@ as style *coul/cut* except that it allows only a single global cutoff
 and thus makes it compatible for use in combination with long-range
 coulomb styles in :doc:`hybrid pair styles <pair_hybrid>`.
 
+Pair style *coul/exclude* computes Coulombic interactions like *coul/cut*
+but **only** applies them to excluded pairs using a scaling factor
+of :math:`\gamma - 1.0` with :math:`\gamma` being the factor assigned
+to that excluded pair via the :doc:`special_bonds coul <special_bonds>`
+setting. With this it is possible to treat Coulomb interactions for
+molecular systems with :doc:`kspace style scafacos <kspace_style>`,
+which always computes the *full* Coulomb interactions without exclusions.
+Pair style *coul/exclude* will then *subtract* the excluded interactions
+accordingly. So to achieve the same forces as with ``pair_style lj/cut/coul/long 12.0``
+with ``kspace_style pppm 1.0e-6``, one would use
+``pair_style hybrid/overlay lj/cut 12.0 coul/exclude 12.0`` with
+``kspace_style scafacos p3m 1.0e-6``.
+
 Styles *coul/long* and *coul/msm* compute the same Coulombic
 interactions as style *coul/cut* except that an additional damping
 factor is applied so it can be used in conjunction with the
diff --git a/doc/src/pair_style.rst b/doc/src/pair_style.rst
index 7677cd9535..1cf033ddba 100644
--- a/doc/src/pair_style.rst
+++ b/doc/src/pair_style.rst
@@ -139,6 +139,7 @@ accelerated styles exist.
 * :doc:`coul/debye <pair_coul>` - cutoff Coulomb potential with Debye screening
 * :doc:`coul/diel <pair_coul_diel>` - Coulomb potential with dielectric permittivity
 * :doc:`coul/dsf <pair_coul>` - Coulomb with damped-shifted-force model
+* :doc:`coul/exclude <pair_coul>` - subtract Coulomb potential for excluded pairs
 * :doc:`coul/long <pair_coul>` - long-range Coulomb potential
 * :doc:`coul/long/cs <pair_cs>` - long-range Coulomb potential and core/shell
 * :doc:`coul/long/dielectric <pair_dielectric>` -