diff --git a/doc/src/Errors_details.rst b/doc/src/Errors_details.rst index 32ebafbae2..820721a581 100644 --- a/doc/src/Errors_details.rst +++ b/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 ` +such that the sum is non-zero or by reading in a system through :doc:`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 `) fail. + +A similar warning/error may be raised when using certain charge equilibration +methods: :doc:`fix qeq `, :doc:`fix qeq/comb `, :doc:`fix +qeq/reaxff `, and :doc:`fix qtpie/reaxff `. In +such cases, this warning/error will be raised for the fix :doc:`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 ` command, +error in the data file read by :doc:`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 `, pair styles that include charge +interactions :doc:`pair_style coul/XXX `, and kspace methods +:doc:`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. diff --git a/src/DIELECTRIC/pppm_dielectric.cpp b/src/DIELECTRIC/pppm_dielectric.cpp index 72d7e908e1..0a24c44bd6 100644 --- a/src/DIELECTRIC/pppm_dielectric.cpp +++ b/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; } } diff --git a/src/DIELECTRIC/pppm_disp_dielectric.cpp b/src/DIELECTRIC/pppm_disp_dielectric.cpp index aba8ccf486..252a9386e3 100644 --- a/src/DIELECTRIC/pppm_disp_dielectric.cpp +++ b/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; } } diff --git a/src/KSPACE/ewald_disp.cpp b/src/KSPACE/ewald_disp.cpp index 9c81b21448..1ba8daa60c 100644 --- a/src/KSPACE/ewald_disp.cpp +++ b/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; diff --git a/src/MANYBODY/fix_qeq_comb.cpp b/src/MANYBODY/fix_qeq_comb.cpp index 88c6fb4be4..308a6e17db 100644 --- a/src/MANYBODY/fix_qeq_comb.cpp +++ b/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); } /* ---------------------------------------------------------------------- */ diff --git a/src/REAXFF/fix_qeq_reaxff.cpp b/src/REAXFF/fix_qeq_reaxff.cpp index dc8fbd5afd..ed54ba0cbe 100644 --- a/src/REAXFF/fix_qeq_reaxff.cpp +++ b/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. diff --git a/src/REAXFF/fix_qtpie_reaxff.cpp b/src/REAXFF/fix_qtpie_reaxff.cpp index 22866fc363..6e4924eb1b 100644 --- a/src/REAXFF/fix_qtpie_reaxff.cpp +++ b/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; diff --git a/src/kspace.cpp b/src/kspace.cpp index 7d51c46ea8..bf5fdf8378 100644 --- a/src/kspace.cpp +++ b/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; } }