The LAMMPS-SPH User's Guide has to be updated

Hi LAMMPS members!

I’m a LAMMPS freshman. I want to use LAMMPS to carry out SPH simulation. The provided User’s Guide was written in 2011. Thirteen years have passed and LAMMPS has been updated to version 2Aug2023. Many keywords have been modified. Hence, there are many “bugs” in the User’s Guide since obsolete keywords are not recognized in the current LAMMPS. To name a few, meso is changed to sph, meso_e is changed to sph/e, and meso_rho is changed to sph/rho. This is very unfriendly to freshmen like me. So I suggested the User’s Guide be updated ASAP.

I also wonder how to find the proper keywords when I encounter the obsolete keywords like meso.

Also, I found a similar issue was suggested seven years ago by @_Alessio_Alexiadis_S in @akohlmey said it was because molecule may not be installed, which is not the real reason. It is merely because the keyword meso has been changed to sph!

That is not correct. In LAMMPS version 17 November 2016 the atom style for the (USER-)SPH package was still called “meso”.

Actually, the current version is 7Feb2024. :wink:

All corrected keywords should be shown in the LAMMPS manual directly, (or when using the stable version LAMMPS Documentation (2 Aug 2023 version) — LAMMPS documentation )

Please note that such contributed additional documentation are not written by the LAMMPS developers but by the authors of the contributed packages. Thus when the package contributor does not update those along the changes to the LAMMPS code and manual, then they will become outdated. Since those are PDF files, the LAMMPS developers cannot update them, because we are lacking the corresponding source code (usually LaTeX files).

As you have noted, a lot of things have changed in LAMMPS over the last decade and longer. We no longer accept such external documentation files are contributed documentation, but rather encourage contributors to write a corresponding “Howto” document.

Now you have multiple options to get this implemented:

  • you can contact the contributing author of a package and external documentation and ask that person to update the documentation to match the current LAMMPS version and its manual
  • you can contact the contributing author to receive the sources to generate the PDF file and update it yourself from the information in the manual and the bundled examples
  • you can contribute a new Howto document based on the (outdated) external PDF and - ideally - based on the sources.

The reason why people chose to create documentation as external documents was that previously the LAMMPS manual was created with a rather simple homegrown markup language that would adding math expression from LaTex very tedious (they needed to be created as individual files, then translated with LaTeX to dvi or eps format and from dvi or eps to jpeg images and thus images then included into the markup. This is no longer a limitation since we switched to using Sphinx and ReStructuredText which has a .. math:: command and a :math: role that allows to embed LaTeX directly and included
them either via MathJAX or insert them directly into the intermediary LaTeX source for the PDF version.

Please note that most of the LAMMPS code is not written by the LAMMPS developers but contributed by external developers (otherwise the code would not have grown to such a large size, the number of core LAMMPS developers is very small and we spend a lot of our time just on integrating the contributions of others).

An example for such a converted external documentation is here: 8.5.9. Peridynamics with LAMMPS — LAMMPS documentation
The author of that package and external documentation provided his (LaTeX sources) which could then be manually translated to .rst and edited into a Howto document.

1 Like

So kind of you to give such a detailed response!

I just went through “6.1. Available Packages” in the documentation, and found some sph examples in “PACKAGE/sph”, which I missed yesterday. I’m very glad to discover that the codes therein have already corrected the obsolete keywords. Should be helpful.

Many thanks to the great efforts of LAMMPS and external developers!