error explanations for net charge warning err_0029

doc/src/Errors_details.rst

@@ -521,3 +521,39 @@ example, are usually not a per-atom property, but defined through the
 atom type.  Thus it would not be required to have a Masses section and
 the included data would be ignored.  LAMMPS prints this warning to
 inform about this case.
+
+.. _err0029:
+
+System is not charge neutral, net charge = ...
+--------------------------------------------------
+
+the sum of charges in the system is not zero. When a system is not
+charge-neutral, methods that evolve/manipulate per-atom charges, evaluate
+Coulomb interactions, evaluate Coulomb forces, or evaluate/manipulate other
+properties relying on per-atom charges may raise this warning. A non-zero
+net charge most commonly arises after setting per-atom charges :doc:`set <set>`
+such that the sum is non-zero or by reading in a system through :doc:`read_data
+<read_data>` where the per-atom charges do not sum to zero. However, a loss of
+charge neutrality may occur in other less common ways, like when charge
+equilibration methods (e.g., :doc:`fix qeq <fix_qeq>`) fail.
+
+A similar warning/error may be raised when using certain charge equilibration
+methods: :doc:`fix qeq <fix_qeq>`, :doc:`fix qeq/comb <fix_qeq_comb>`, :doc:`fix
+qeq/reaxff <fix_qeq_reaxff>`, and :doc:`fix qtpie/reaxff <fix_qtpie_reaxff>`. In
+such cases, this warning/error will be raised for the fix :doc:`group <group>`
+when the group has a non-zero net charge.
+
+When the system is expected to be charge-neutral, this warning often arises due
+to an error in the lammps input (e.g., an incorrect :doc:`set <set>` command,
+error in the data file read by :doc:`read_data <read_data>`, incorrectly
+grouping atoms with charge, etc.). If the system is NOT expected to be
+charge-neutral, the user should make sure that the method(s) used are
+appropriate for systems with a non-zero net charge. Some commonly used fixes for
+charge equilibration :doc:`fix qeq <fix_qeq>`, pair styles that include charge
+interactions :doc:`pair_style coul/XXX <pair_coul>`, and kspace methods
+:doc:`kspace_style <kspace_style>` can, in theory, support systems with non-zero
+net charge. However, non-zero net charge can lead to spurious artifacts. The
+severity of these artifacts depends on the magnitude of total charge, system
+size, and methods used. Before running simulations or calculations for systems
+with non-zero net charge, users should test for artifacts and convergence of
+properties.

src/DIELECTRIC/pppm_dielectric.cpp

@@ -308,8 +308,8 @@ void PPPMDielectric::qsum_qsq(int warning_flag)
   if (fabs(qsum) > SMALL) {
     std::string message = fmt::format("System is not charge neutral, net "
                                       "charge = {:.8}",qsum);
-    if (!warn_nonneutral) error->all(FLERR,message);
-    if (warn_nonneutral == 1 && comm->me == 0) error->warning(FLERR,message);
+    if (!warn_nonneutral) error->all(FLERR,message + utils::errorurl(29));
+    if (warn_nonneutral == 1 && comm->me == 0) error->warning(FLERR,message + utils::errorurl(29));
     warn_nonneutral = 2;
   }
 }

src/DIELECTRIC/pppm_disp_dielectric.cpp

@@ -582,8 +582,8 @@ void PPPMDispDielectric::qsum_qsq(int warning_flag)
   if (fabs(qsum) > SMALL) {
     std::string message = fmt::format("System is not charge neutral, net "
                                       "charge = {:.8}",qsum);
-    if (!warn_nonneutral) error->all(FLERR,message);
-    if (warn_nonneutral == 1 && comm->me == 0) error->warning(FLERR,message);
+    if (!warn_nonneutral) error->all(FLERR,message + utils::errorurl(29));
+    if (warn_nonneutral == 1 && comm->me == 0) error->warning(FLERR,message + utils::errorurl(29));
     warn_nonneutral = 2;
   }
 }

src/KSPACE/ewald_disp.cpp

@@ -220,7 +220,7 @@ void EwaldDisp::init()
       error->all(FLERR,"Cannot use Ewald/disp solver on system without "
                  "charged, dipole, or LJ particles");
   if (fabs(qsum) > SMALL && comm->me == 0)
-    error->warning(FLERR,"System is not charge neutral, net charge = {:.8g}",qsum);
+    error->warning(FLERR,"System is not charge neutral, net charge = {:.8g}" + utils::errorurl(29),qsum);
 
   if (!function[1] && !function[2]) dispersionflag = 0;
   if (!function[3]) dipoleflag = 0;

src/MANYBODY/fix_qeq_comb.cpp

@@ -143,7 +143,7 @@ void FixQEQComb::init()
   MPI_Allreduce(&qsum_local,&qsum,1,MPI_DOUBLE,MPI_SUM,world);
 
   if ((comm->me == 0) && (fabs(qsum) > QSUMSMALL))
-    error->warning(FLERR,"Fix {} group is not charge neutral, net charge = {:.8}", style, qsum);
+    error->warning(FLERR,"Fix {} group is not charge neutral, net charge = {:.8}" + utils::errorurl(29), style, qsum);
 }
 
 /* ---------------------------------------------------------------------- */

src/REAXFF/fix_qeq_reaxff.cpp

@@ -412,7 +412,7 @@ void FixQEqReaxFF::init()
   MPI_Allreduce(&qsum_local,&qsum,1,MPI_DOUBLE,MPI_SUM,world);
 
   if ((comm->me == 0) && (fabs(qsum) > QSUMSMALL))
-    error->warning(FLERR,"Fix {} group is not charge neutral, net charge = {:.8}", style, qsum);
+    error->warning(FLERR,"Fix {} group is not charge neutral, net charge = {:.8}" + utils::errorurl(29), style, qsum);
 
   // get pointer to fix efield if present. there may be at most one instance of fix efield in use.
 

src/REAXFF/fix_qtpie_reaxff.cpp

@@ -439,7 +439,7 @@ void FixQtpieReaxFF::init()
   MPI_Allreduce(&qsum_local,&qsum,1,MPI_DOUBLE,MPI_SUM,world);
 
   if ((comm->me == 0) && (fabs(qsum) > QSUMSMALL))
-    error->warning(FLERR,"Fix {} group is not charge neutral, net charge = {:.8}", style, qsum);
+    error->warning(FLERR,"Fix {} group is not charge neutral, net charge = {:.8}" + utils::errorurl(29), style, qsum);
 
   // get pointer to fix efield if present. there may be at most one instance of fix efield in use.
   efield = nullptr;

src/kspace.cpp

@@ -323,8 +323,8 @@ void KSpace::qsum_qsq(int warning_flag)
   if (fabs(qsum) > SMALL) {
     std::string message = fmt::format("System is not charge neutral, net "
                                       "charge = {:.8}",qsum);
-    if (!warn_nonneutral) error->all(FLERR,message);
-    if (warn_nonneutral == 1 && comm->me == 0) error->warning(FLERR,message);
+    if (!warn_nonneutral) error->all(FLERR,message + utils::errorurl(29));
+    if (warn_nonneutral == 1 && comm->me == 0) error->warning(FLERR,message + utils::errorurl(29));
     warn_nonneutral = 2;
   }
 }