Merge pull request lammps#4389 from akohlmey/collected-small-changes

Collected small changes and fixes

.github/release_steps.md

@@ -1,28 +1,78 @@
 # LAMMPS Release Steps
 
-The following notes chronicle the current steps for preparing and publishing LAMMPS releases.
-For definition of what LAMMPS versions and the different kinds of releases mean, please
-refer to [the corresponding section in the LAMMPS manual](https://docs.lammps.org/Manual_version.html).
+The following notes chronicle the current steps for preparing and publishing LAMMPS releases.  For
+definitions of LAMMPS versions and releases mean, please refer to [the corresponding section in the
+LAMMPS manual](https://docs.lammps.org/Manual_version.html).
 
 ## LAMMPS Feature Release
 
-A LAMMPS feature release is currently prepared after about 500 to 750 commits to the
-'develop' branch or after a period of four weeks up to two months.
+A LAMMPS feature release is currently prepared after about 500 to 750 commits to the 'develop'
+branch or after a period of four weeks up to two months.  This is not a fixed rule, though, since
+external circumstances can cause delays in preparing a release, or pull requests that are desired to
+be merged for the release are not yet completed.
 
 ### Preparing a 'next\_release' branch
 
 Create a 'next\_release' branch off 'develop' and make the following changes:
-- set the LAMMPS\_VERSION define to the planned release date in src/version.h in the format "D Mmm YYYY" or "DD Mmm YYYY"
+
+- set the LAMMPS\_VERSION define to the planned release date in src/version.h in the format
+  "D Mmm YYYY" or "DD Mmm YYYY"
 - remove the LAMMPS\_UPDATE define in src/version.h
 - update the release date in doc/lammps.1
 - update all TBD arguments for ..versionadded::, ..versionchanged:: ..deprecated:: to the
   planned release date in the format "DMmmYYYY" or "DDMmmYYYY"
-
-Submit this pull request, rebase if needed. This is the last pull request merged for the release
+- check release notes for merged new features and check if ..versionadded:: or ..versionchanged::
+  are missing and need to be added
+Submit this pull request, rebase if needed.  This is the last pull request merged for the release
 and should not contain any other changes. (Exceptions: this document, last minute trivial(!) changes).
+
 This PR shall not be merged before **all** pending tests have completed and cleared. If needed, a
 bugfix pull request should be created and merged to clear all tests.
 
+### Create release on GitHub
+
+When all pending pull requests for the release are merged and have cleared testing, the
+'next\_release' branch is merged into 'develop'.
+
+Check out 'develop' locally, pull the latest changes, merge them into 'release', apply a suitable
+release tag (for historical reasons the tag starts with "patch_" followed by the date, and finally
+push everything back to GitHub. Example:
+
+```
+git checkout develop
+git pull
+git checkout release
+git pull
+git merge --ff-only develop
+git tag -s -m "LAMMPS feature release 19 November 2024" patch_19Nov2024
+git push [email protected]:lammps/lammps.git --tags develop release
+```
+
+Go to https://github.com/lammps/lammps/releases and create a new (draft) release page or check the
+existing draft for any necessary changes from pull requests that were merged but are not listed.
+Then select the applied tag for the release in the "Choose a tag" dropdown list. Go to the bottom of
+the list and select the "Set as pre-release" checkbox.  The "Set as the latest release" button is
+reserved for stable releases and updates to them.
+
+If everything is in order, you can click on the "Publish release" button.  Otherwise, click on "Save
+draft" and finish pending tasks until you can return to edit the release page and publish it.
+
+### Update download website, prepare pre-compiled packages, update packages to GitHub
+
+Publishing the release on GitHub will trigger the Temple Jenkins cluster to update
+the https://docs.lammps.org/ website with the documentation for the new feature release
+and it will create a tarball for download (which contains the translated manual).
+
+Build a fully static LAMMPS installation using a musl-libc cross-compiler, install into a
+lammps-static folder, and create a tarball called lammps-linux-x86_64-19Nov2024.tar.gz (or using a
+corresponding date with a future release) from the lammps-static folder and upload it to GitHub
+with:
+
+```
+gh release upload patch_19Nov2024 ~/Downloads/lammps-linux-x86_64-19Nov2024.tar.gz
+```
+
+
 ## LAMMPS Stable Release
 
 A LAMMPS stable release is prepared about once per year in the months July, August, or September.

doc/src/Errors_details.rst

@@ -54,3 +54,26 @@ header of a data file (e.g. the number of atoms) is larger than the
 number of lines provided (e.g. in the corresponding Atoms section)
 and then LAMMPS will continue reading into the next section and that
 would have a completely different format.
+
+.. _err0003:
+
+Illegal variable command: expected X arguments but found Y
+----------------------------------------------------------
+
+This error indicates that there are the wrong number of arguments for a
+specific variable command, but a common reason for that is a variable
+expression that has whitespace but is not enclosed in single or double
+quotes.
+
+To explain, the LAMMPS input parser reads and processes lines.  The
+resulting line is broken down into "words".  Those are usually
+individual commands, labels, names, values separated by whitespace (a
+space or tab character).  For "words" that may contain whitespace, they
+have to be enclosed in single (') or double (") quotes.  The parser will
+then remove the outermost pair of quotes and then pass that string as
+"word" to the variable command.
+
+Thus missing quotes or accidental extra whitespace will lead to the
+error shown in the header because the unquoted whitespace will result
+in the text being broken into more "words", i.e. the variable expression
+being split.

doc/src/compute_stress_curvilinear.rst

@@ -87,7 +87,7 @@ This array can be output with :doc:`fix ave/time <fix_ave_time>`,
 
 .. code-block:: LAMMPS
 
-  compute 1 all stress/spherical 0 0 0 0.1 10
+  compute p all stress/spherical 0 0 0 0.1 10
   fix 2 all ave/time 100 1 100 c_p[*] file dump_p.out mode vector
 
 The values calculated by this compute are "intensive".  The stress

doc/src/fix_external.rst

@@ -139,9 +139,9 @@ properties are:
    void set_vector_length(int n);
    void set_vector(int idx, double val);
 
-These allow to set per-atom energy contributions, per-atom stress
-contributions, the length and individual values of a global vector
-of properties that the caller code may want to communicate  to LAMMPS
+These enable setting per-atom energy and  per-atom stress contributions,
+the length and individual values of a global vector of properties that
+the caller code may want to communicate  to LAMMPS
 (e.g. for use in :doc:`fix ave/time <fix_ave_time>` or in
 :doc:`equal-style variables <variable>` or for
 :doc:`custom thermo output <thermo_style>`.
@@ -173,9 +173,19 @@ stress/atom <compute_stress_atom>` commands.  The former can be
 accessed by :doc:`thermodynamic output <thermo_style>`.  The default
 setting for this fix is :doc:`fix_modify virial yes <fix_modify>`.
 
-This fix computes a global scalar which can be accessed by various
-:doc:`output commands <Howto_output>`.  The scalar is the potential
-energy discussed above.  The scalar stored by this fix is "extensive".
+This fix computes a global scalar, a global vector, and a per-atom array
+which can be accessed by various :doc:`output commands <Howto_output>`.
+The scalar is the potential energy discussed above.  The scalar stored
+by this fix is "extensive".
+The global vector has a custom length and needs to be set by the external
+program using the
+:cpp:func:`lammps_fix_external_set_vector() <lammps_fix_external_set_vector>`
+and :cpp:func:`lammps_fix_external_set_vector_length()
+<lammps_fix_external_set_vector_length>`
+calls of the LAMMPS library interface or the equivalent call of the Python
+or Fortran modules.
+The per-atom array has 3 values for each atom and is the applied external
+force.
 
 No parameter of this fix can be used with the *start/stop* keywords of
 the :doc:`run <run>` command.

src/fix_external.cpp

@@ -30,31 +30,33 @@ enum{PF_CALLBACK,PF_ARRAY};
 /* ---------------------------------------------------------------------- */
 
 FixExternal::FixExternal(LAMMPS *lmp, int narg, char **arg) :
-  Fix(lmp, narg, arg),
-  fexternal(nullptr), caller_vector(nullptr)
+  Fix(lmp, narg, arg), fexternal(nullptr), caller_vector(nullptr)
 {
   if (narg < 4) error->all(FLERR,"Illegal fix external command");
 
   scalar_flag = 1;
   global_freq = 1;
+  peratom_flag = 1;
+  peratom_freq = 1;
+  size_peratom_cols = 3;
   extscalar = 1;
   energy_global_flag = energy_peratom_flag = 1;
   virial_global_flag = virial_peratom_flag = 1;
   thermo_energy = thermo_virial = 1;
 
   if (strcmp(arg[3],"pf/callback") == 0) {
-    if (narg != 6) error->all(FLERR,"Illegal fix external command");
+    if (narg != 6) error->all(FLERR,"Incorrect number of args for fix external pf/callback");
     mode = PF_CALLBACK;
     ncall = utils::inumeric(FLERR,arg[4],false,lmp);
     napply = utils::inumeric(FLERR,arg[5],false,lmp);
     if (ncall <= 0 || napply <= 0)
-      error->all(FLERR,"Illegal fix external command");
+      error->all(FLERR,"Illegal values for ncall or napply in fix external pf/callback");
   } else if (strcmp(arg[3],"pf/array") == 0) {
-    if (narg != 5) error->all(FLERR,"Illegal fix external command");
+    if (narg != 5) error->all(FLERR,"Incorrect number of args for fix external pf/array");
     mode = PF_ARRAY;
     napply = utils::inumeric(FLERR,arg[4],false,lmp);
-    if (napply <= 0) error->all(FLERR,"Illegal fix external command");
-  } else error->all(FLERR,"Illegal fix external command");
+    if (napply <= 0) error->all(FLERR,"Illegal value for napply for fix external pf/array");
+  } else error->all(FLERR,"Unknown fix external mode {}", arg[3]);
 
   callback = nullptr;
 
@@ -323,6 +325,7 @@ void FixExternal::grow_arrays(int nmax)
 {
   memory->grow(fexternal,nmax,3,"external:fexternal");
   memset(&fexternal[0][0], 0, sizeof(double)*3*nmax);
+  array_atom = fexternal;
 }
 
 /* ----------------------------------------------------------------------

src/variable.cpp

@@ -277,7 +277,8 @@ void Variable::set(int narg, char **arg)
       copy(num[nvar],&arg[2],data[nvar]);
     } else if (strcmp(arg[1],"uloop") == 0) {
       if (narg < 3 || narg > 4)
-        error->all(FLERR,"Illegal variable command: expected 3 or 4 arguments but found {}", narg);
+        error->all(FLERR,"Illegal variable command: expected 3 or 4 arguments but found {}: {}",
+                   narg, utils::errorurl(3));
       if (narg == 4 && strcmp(arg[3],"pad") != 0)
         error->all(FLERR, "Invalid variable uloop argument: {}", arg[3]);
       if (find(arg[0]) >= 0) return;
@@ -314,7 +315,9 @@ void Variable::set(int narg, char **arg)
   // data = 1 value, string to eval
 
   } else if (strcmp(arg[1],"string") == 0) {
-    if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg);
+    if (narg != 3)
+      error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}{}",
+                 narg, utils::errorurl(3));
 
     int maxcopy = strlen(arg[2]) + 1;
     int maxwork = maxcopy;
@@ -348,7 +351,9 @@ void Variable::set(int narg, char **arg)
   // data = 1 value, string to eval
 
   } else if (strcmp(arg[1],"getenv") == 0) {
-    if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg);
+    if (narg != 3)
+      error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}{}",
+                 narg, utils::errorurl(3));
     if (find(arg[0]) >= 0) {
       if (style[find(arg[0])] != GETENV)
         error->all(FLERR,"Cannot redefine variable as a different style");
@@ -368,7 +373,9 @@ void Variable::set(int narg, char **arg)
   // data = 1 value, string to eval
 
   } else if (strcmp(arg[1],"file") == 0) {
-    if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg);
+    if (narg != 3)
+      error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}{}",
+                 narg, utils::errorurl(3));
     if (find(arg[0]) >= 0) return;
     if (nvar == maxvar) grow();
     style[nvar] = SCALARFILE;
@@ -387,7 +394,9 @@ void Variable::set(int narg, char **arg)
   // data = nullptr
 
   } else if (strcmp(arg[1],"atomfile") == 0) {
-    if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg);
+    if (narg != 3)
+      error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}{}",
+                 narg, utils::errorurl(3));
     if (find(arg[0]) >= 0) return;
     if (nvar == maxvar) grow();
     style[nvar] = ATOMFILE;
@@ -409,7 +418,9 @@ void Variable::set(int narg, char **arg)
 
   } else if (strcmp(arg[1],"format") == 0) {
     constexpr char validfmt[] = "^% ?-?[0-9]*\\.?[0-9]*[efgEFG]$";
-    if (narg != 4) error->all(FLERR,"Illegal variable command: expected 4 arguments but found {}", narg);
+    if (narg != 4)
+      error->all(FLERR,"Illegal variable command: expected 4 arguments but found {}{}",
+                 narg, utils::errorurl(3));
     int ivar = find(arg[0]);
     int jvar = find(arg[2]);
     if (jvar < 0)
@@ -446,7 +457,9 @@ void Variable::set(int narg, char **arg)
   // data = 2 values, 1st is string to eval, 2nd is filled on retrieval
 
   } else if (strcmp(arg[1],"equal") == 0) {
-    if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg);
+    if (narg != 3)
+      error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}{}",
+                 narg, utils::errorurl(3));
     int ivar = find(arg[0]);
     if (ivar >= 0) {
       if (style[ivar] != EQUAL)
@@ -472,7 +485,9 @@ void Variable::set(int narg, char **arg)
   // data = 1 value, string to eval
 
   } else if (strcmp(arg[1],"atom") == 0) {
-    if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg);
+    if (narg != 3)
+      error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}{}",
+                 narg, utils::errorurl(3));
     int ivar = find(arg[0]);
     if (ivar >= 0) {
       if (style[ivar] != ATOM)
@@ -498,7 +513,9 @@ void Variable::set(int narg, char **arg)
   //   immediately store it as N-length vector and set dynamic flag to 0
 
   } else if (strcmp(arg[1],"vector") == 0) {
-    if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg);
+    if (narg != 3)
+      error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}{}",
+                 narg, utils::errorurl(3));
     int ivar = find(arg[0]);
     if (ivar >= 0) {
       if (style[ivar] != VECTOR)
@@ -540,7 +557,9 @@ void Variable::set(int narg, char **arg)
   // data = 2 values, 1st is Python func to invoke, 2nd is filled by invoke
 
   } else if (strcmp(arg[1],"python") == 0) {
-    if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg);
+    if (narg != 3)
+      error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}{}",
+                 narg, utils::errorurl(3));
     if (!python->is_enabled())
       error->all(FLERR,"LAMMPS is not built with Python embedded");
     int ivar = find(arg[0]);
@@ -593,7 +612,9 @@ void Variable::set(int narg, char **arg)
   // dvalue = numeric initialization from 2nd arg, reset by internal_set()
 
   } else if (strcmp(arg[1],"internal") == 0) {
-    if (narg != 3) error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}", narg);
+    if (narg != 3)
+      error->all(FLERR,"Illegal variable command: expected 3 arguments but found {}{}",
+                 narg, utils::errorurl(3));
     int ivar = find(arg[0]);
     if (ivar >= 0) {
       if (style[ivar] != INTERNAL)

src/version.h

@@ -1 +1,2 @@
 #define LAMMPS_VERSION "19 Nov 2024"
+#define LAMMPS_UPDATE "Development"

unittest/c-library/test_library_external.cpp

@@ -123,6 +123,18 @@ TEST(lammps_external, callback)
     EXPECT_DOUBLE_EQ(reduce[5], 1.4);
     EXPECT_DOUBLE_EQ(reduce[6], 1.4);
 
+    double **fext =
+        (double **)lammps_extract_fix(handle, "ext", LMP_STYLE_ATOM, LMP_TYPE_ARRAY, 0, 0);
+    EXPECT_DOUBLE_EQ(fext[0][0], 10.0);
+    EXPECT_DOUBLE_EQ(fext[0][1], 10.0);
+    EXPECT_DOUBLE_EQ(fext[0][2], 10.0);
+    EXPECT_DOUBLE_EQ(fext[3][0], 10.0);
+    EXPECT_DOUBLE_EQ(fext[3][1], 10.0);
+    EXPECT_DOUBLE_EQ(fext[3][2], 10.0);
+    EXPECT_DOUBLE_EQ(fext[7][0], 10.0);
+    EXPECT_DOUBLE_EQ(fext[7][1], 10.0);
+    EXPECT_DOUBLE_EQ(fext[7][2], 10.0);
+
     ::testing::internal::CaptureStdout();
     lammps_close(handle);
     output = ::testing::internal::GetCapturedStdout();
@@ -193,6 +205,18 @@ TEST(lammps_external, array)
     EXPECT_DOUBLE_EQ(pe, 1.0 / 8.0);
     EXPECT_DOUBLE_EQ(press, 0.15416666666666667);
 
+    double **fext =
+        (double **)lammps_extract_fix(handle, "ext", LMP_STYLE_ATOM, LMP_TYPE_ARRAY, 0, 0);
+    EXPECT_DOUBLE_EQ(fext[0][0], 6.0);
+    EXPECT_DOUBLE_EQ(fext[0][1], 6.0);
+    EXPECT_DOUBLE_EQ(fext[0][2], 6.0);
+    EXPECT_DOUBLE_EQ(fext[3][0], 6.0);
+    EXPECT_DOUBLE_EQ(fext[3][1], 6.0);
+    EXPECT_DOUBLE_EQ(fext[3][2], 6.0);
+    EXPECT_DOUBLE_EQ(fext[7][0], 6.0);
+    EXPECT_DOUBLE_EQ(fext[7][1], 6.0);
+    EXPECT_DOUBLE_EQ(fext[7][2], 6.0);
+
     ::testing::internal::CaptureStdout();
     lammps_close(handle);
     output = ::testing::internal::GetCapturedStdout();