Merge remote-tracking branch 'github/develop' into atom-style-var-with-python

doc/src/Build.rst

@@ -14,32 +14,10 @@ As an alternative, you can download a package with pre-built executables
 or automated build trees, as described in the :doc:`Install <Install>`
 section of the manual.
 
-Prerequisites
--------------
-
-Which software you need to compile and use LAMMPS strongly depends on
-which :doc:`features and settings <Build_settings>` and which
-:doc:`optional packages <Packages_list>` you are trying to include.
-Common to all is that you need a C++ and C compiler, where the C++
-compiler has to support at least the C++11 standard (note that some
-compilers require command-line flag to activate C++11 support).
-Furthermore, if you are building with CMake, you need at least CMake
-version 3.20 and a compatible build tool (make or ninja-build); if you
-are building the the legacy GNU make based build system you need GNU
-make (other make variants are not going to work since the build system
-uses features unique to GNU make) and a Unix-like build environment with
-a Bourne shell, and shell tools like "sed", "grep", "touch", "test",
-"tr", "cp", "mv", "rm", "ln", "diff" and so on. Parts of LAMMPS
-interface with or use Python version 3.6 or later.
-
-The LAMMPS developers aim to keep LAMMPS very portable and usable -
-at least in parts - on most operating systems commonly used for
-running MD simulations.  Please see the :doc:`section on portablility
-<Intro_portability>` for more details.
-
 .. toctree::
    :maxdepth: 1
 
+   Build_prerequisites
    Build_cmake
    Build_make
    Build_link

doc/src/Build_prerequisites.rst

@@ -0,0 +1,22 @@
+Prerequisites
+-------------
+
+Which software you need to compile and use LAMMPS strongly depends on
+which :doc:`features and settings <Build_settings>` and which
+:doc:`optional packages <Packages_list>` you are trying to include.
+Common to all is that you need a C++ and C compiler, where the C++
+compiler has to support at least the C++11 standard (note that some
+compilers require command-line flag to activate C++11 support).
+Furthermore, if you are building with CMake, you need at least CMake
+version 3.20 and a compatible build tool (make or ninja-build); if you
+are building the the legacy GNU make based build system you need GNU
+make (other make variants are not going to work since the build system
+uses features unique to GNU make) and a Unix-like build environment with
+a Bourne shell, and shell tools like "sed", "grep", "touch", "test",
+"tr", "cp", "mv", "rm", "ln", "diff" and so on. Parts of LAMMPS
+interface with or use Python version 3.6 or later.
+
+The LAMMPS developers aim to keep LAMMPS very portable and usable -
+at least in parts - on most operating systems commonly used for
+running MD simulations.  Please see the :doc:`section on portablility
+<Intro_portability>` for more details.

doc/src/Commands_pair.rst

@@ -179,6 +179,7 @@ OPT.
    * :doc:`lj/long/dipole/long <pair_dipole>`
    * :doc:`lj/long/tip4p/long (o) <pair_lj_long>`
    * :doc:`lj/mdf <pair_mdf>`
+   * :doc:`lj/pirani (o) <pair_lj_pirani>`
    * :doc:`lj/relres (o) <pair_lj_relres>`
    * :doc:`lj/spica (gko) <pair_spica>`
    * :doc:`lj/spica/coul/long (gko) <pair_spica>`

doc/src/Commands_removed.rst

@@ -1,7 +1,7 @@
 Removed commands and packages
 =============================
 
-.. contents:: \
+.. contents::
 
 ------
 
@@ -15,7 +15,7 @@ with the direct alternative (if available) and print a warning.
 LAMMPS shell
 ------------
 
-.. versionchanged:: 29Aug2024
+.. deprecated:: 29Aug2024
 
 The LAMMPS shell has been removed from the LAMMPS distribution. Users
 are encouraged to use the :ref:`LAMMPS-GUI <lammps_gui>` tool instead.
@@ -23,7 +23,7 @@ are encouraged to use the :ref:`LAMMPS-GUI <lammps_gui>` tool instead.
 i-PI tool
 ---------
 
-.. versionchanged:: 27Jun2024
+.. deprecated:: 27Jun2024
 
 The i-PI tool has been removed from the LAMMPS distribution.  Instead,
 instructions to install i-PI from PyPI via pip are provided.

doc/src/Errors_details.rst

@@ -159,13 +159,17 @@ angle, dihedral, or improper with just one atom in the actual
 sub-domain.  Typically, this cutoff is set to the largest cutoff from
 the :doc:`pair style(s) <pair_style>` plus the :doc:`neighbor list skin
 distance <neighbor>` and will typically be sufficient for all bonded
-interactions.  But if the pair style cutoff is small, this may not be
-enough.  LAMMPS will print a warning in this case using some heuristic
-based on the equilibrium bond length, but that still may not be
-sufficient for cases where the force constants are small and thus bonds
-may be stretched very far.  The communication cutoff can be adjusted
-with :doc:`comm_modify cutoff \<value\> <comm_modify>`, but setting this
-too large will waste CPU time and memory.
+interactions.  But if the pair style cutoff is small (e.g. with a
+repulsive-only Lennard-Jones potential) this may not be enough.  It is
+even worse if there is no pair style defined (or the pair style is set
+to "none"), since then there will be no ghost atoms created at all.
+
+The communication cutoff can be set or adjusted with :doc:`comm_modify
+cutoff \<value\> <comm_modify>`, but setting this too large will waste
+CPU time and memory.  LAMMPS will print warnings in these cases.  For
+bonds it uses some heuristic based on the equilibrium bond length, but
+that still may not be sufficient for cases where the force constants are
+small and thus bonds may be stretched very far.
 
 .. _hint09:
 

doc/src/Howto_lammps_gui.rst

@@ -308,7 +308,10 @@ of the *Output* window showing how many warnings and errors were
 detected and how many lines the entire output has.  By clicking on the
 button on the right with the warning symbol or by using the keyboard
 shortcut `Ctrl-N` (`Command-N` on macOS), you can jump to the next
-line with a warning or error.
+line with a warning or error.  If there is a URL pointing to additional
+explanations in the online manual, that URL will be highlighted and
+double-clicking on it shall open the corresponding manual page in
+the web browser.  The option is also available from the context menu.
 
 By default, the *Output* window is replaced each time a run is started.
 The runs are counted and the run number for the current run is displayed

doc/src/Install_git.rst

@@ -12,19 +12,10 @@ several advantages:
   LAMMPS.  For that, you should first create your own :doc:`fork on
   GitHub <Howto_github>`, though.
 
-You must have `git <git_>`_ installed on your system to use the
-commands explained below to communicate with the git servers on
-GitHub.  For people still using subversion (svn), GitHub also
-provides `limited support for subversion clients <svn_>`_.
-
-.. note::
-
-   As of October 2016, the official home of public LAMMPS development is
-   on GitHub.  The previously advertised LAMMPS git repositories on
-   git.lammps.org and bitbucket.org are now offline or deprecated.
+You must have `git <git_>`_ installed on your system to use the commands
+explained below to communicate with the git servers on GitHub.
 
 .. _git: https://git-scm.com
-.. _svn: https://help.github.com/en/github/importing-your-projects-to-github/working-with-subversion-on-github
 
 You can follow the LAMMPS development on 4 different git branches:
 

doc/src/Modify_pair.rst

@@ -46,6 +46,8 @@ Here is a brief list of some the class methods in the Pair class that
 +---------------------------------+------------------------------------------------------------------------+
 | compute_inner/middle/outer      | versions of compute used by rRESPA                                     |
 +---------------------------------+------------------------------------------------------------------------+
+| compute_atomic_energy           | energy of one atom, equivalent to per-atom energy                      |
++---------------------------------+------------------------------------------------------------------------+
 | memory_usage                    | return estimated amount of memory used by the pair style               |
 +---------------------------------+------------------------------------------------------------------------+
 | modify_params                   | process arguments to pair_modify command                               |
@@ -122,3 +124,5 @@ setting.
 +---------------------------------+-------------------------------------------------------------+---------+
 | spinflag                        | 1 if compatible with spin kspace_style                      | 0       |
 +---------------------------------+-------------------------------------------------------------+---------+
+| atomic_energy_enable            | 1 if compute_atomic_energy() routine exists                 | 0       |
++---------------------------------+-------------------------------------------------------------+---------+

doc/src/Tools.rst

@@ -1250,10 +1250,10 @@ tabulate tool
 
 .. versionadded:: 22Dec2022
 
-The ``tabulate`` folder contains Python scripts scripts to generate tabulated
-potential files for LAMMPS.  The bulk of the code is in the ``tabulate`` module
-in the ``tabulate.py`` file.  Some example files demonstrating its use are
-included.  See the README file for more information.
+The ``tabulate`` folder contains Python scripts scripts to generate and
+visualize tabulated potential files for LAMMPS.  The bulk of the code is in the
+``tabulate`` module in the ``tabulate.py`` file.  Some example files
+demonstrating its use are included.  See the README file for more information.
 
 ----------
 
@@ -1276,7 +1276,7 @@ Those scripts were written by Steve Plimpton sjplimp at gmail.com
 valgrind tool
 -------------
 
-The ``valgrind`` folder contains additional suppressions fur LAMMPS when
+The ``valgrind`` folder contains additional suppressions for LAMMPS when
 using `valgrind's <https://valgrind.org/>`_ ` `memcheck tool
 <https://valgrind.org/info/tools.html#memcheck>`_ to search for memory
 access violation and memory leaks.  These suppressions are automatically

doc/src/bond_bpm_rotational.rst

@@ -215,6 +215,9 @@ for an overview of LAMMPS output options.
 The vector or array will be floating point values that correspond to
 the specified attribute.
 
+Any settings with the *store/local* option are not saved to a restart
+file and must be redefined.
+
 The single() function of this bond style returns 0.0 for the energy
 of a bonded interaction, since energy is not conserved in these
 dissipative potentials.  It also returns only the normal component of

doc/src/bond_bpm_spring.rst

@@ -215,6 +215,9 @@ for an overview of LAMMPS output options.
 The vector or array will be floating point values that correspond to
 the specified attribute.
 
+Any settings with the *store/local* option are not saved to a restart
+file and must be redefined.
+
 The potential energy and the single() function of this bond style return
 :math:`k (r - r_0)^2 / 2` as a proxy of the energy of a bonded interaction,
 ignoring any volumetric/smoothing factors or dissipative forces.  The single()

doc/src/compute_rheo_property_atom.rst

@@ -88,7 +88,7 @@ The *phase* property indicates whether the particle is in a fluid state,
 a value of 0, or a solid state, a value of 1.
 
 The *surface* property indicates the surface designation produced by
-the *interface/reconstruct* option of :doc:`fix rheo <fix_rheo>`. Bulk
+the *surface/detection* option of :doc:`fix rheo <fix_rheo>`. Bulk
 particles have a value of 0, surface particles have a value of 1, and
 splash particles have a value of 2. The *surface/r* property is the
 distance from the surface, up to the kernel cutoff length. Surface particles

doc/src/fix_adapt.rst

@@ -214,6 +214,8 @@ formulas for the meaning of these parameters:
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`lj/mdf <pair_mdf>`                                                     | epsilon,sigma                                    | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
+| :doc:`lj/pirani <pair_lj_pirani>`                                            | alpha, beta, gamma, rm, epsilon                  | type pairs  |
++------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`lj/sf/dipole/sf <pair_dipole>`                                         | epsilon,sigma,scale                              | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`lubricate <pair_lubricate>`                                            | mu                                               | global      |

doc/src/fix_sgcmc.rst

@@ -30,7 +30,9 @@ Syntax
          N = number of times sampling window is moved during one MC cycle
        *window_size* frac
          frac = size of sampling window (must be between 0.5 and 1.0)
-
+       *atomic/energy* yes/no
+         yes = use the atomic energy method to calculate energy changes
+         no = use the default method to calculate energy changes
 
 Examples
 """"""""
@@ -127,6 +129,14 @@ The number of times the window is moved during a MC cycle is set using
 the parameter *window_moves* (see Sect. III.B in :ref:`Sadigh1
 <Sadigh1>` for details).
 
+The *atomic/energy* keyword controls which method is used for calculating
+the energy change when atom types are swapped. A value of *no*
+uses the default method, see discussion below in Restrictions section.
+A value of *yes* uses the atomic energy method,
+if the method has been implemented for the LAMMPS energy model,
+otherwise LAMMPS will exit with an error message.
+So far this has only been implemented for EAM type potentials.
+
 ------------
 
 Restart, fix_modify, output, run start/stop, minimize info
@@ -159,16 +169,26 @@ page for more info.
 This fix style requires an :doc:`atom style <atom_style>` with per atom
 type masses.
 
-At present the fix provides optimized subroutines for EAM type
-potentials (see above) that calculate potential energy changes due to
-*local* atom type swaps very efficiently.  Other potentials are
-supported by using the generic potential functions. This, however, will
-lead to exceedingly slow simulations since it implies that the
-energy of the *entire* system is recomputed at each MC trial step.  If
-other potentials are to be used it is strongly recommended to modify and
-optimize the existing generic potential functions for this purpose.
-Also, the generic energy calculation can not be used for parallel
-execution i.e. it only works with a single MPI process.
+The fix provides three methods for calculating the potential energy
+change due to atom type swaps. For EAM type potentials, the default
+method is a carefully optimized local energy change calculation that
+is part of the source code for this fix. It takes advantage of the
+specific computational and communication requirements of EAM. Customizing
+the local method to handle other energy models such as Tersoff has been done,
+but these cases are not supported in the public LAMMPS code.
+For all other LAMMPS energy models, the default method calculates
+the *total* potential energy of the system before and after each
+atom type swap.  This method does not depend on the details of the
+energy model and so is guaranteed to be correct.  It is also
+orders of magnitude slower than the custom EAM calculation.
+In addition, it can not be used with parallel execution i.e. only
+a single MPI process is allowed.
+The third method uses the *atomic/energy* keyword described above.
+This allows parallel execution and it is also a local calculation,
+making it only a bit slower than a fully-optimized local calculation.
+So far, this has been implemented for EAM type potentials.
+It is straightforward to extend this to other potentials,
+requiring adding an atomic energy method to the pair style.
 
 ------------
 
@@ -180,6 +200,7 @@ The optional parameters default to the following values:
 * *randseed* = 324234
 * *window_moves* = 8
 * *window_size* = automatic
+* *atomic/energy* = no
 
 ------------
 

doc/src/pair_lj_pirani.rst

@@ -0,0 +1,163 @@
+.. index:: pair_style lj/pirani
+.. index:: pair_style lj/pirani/omp
+
+pair_style lj/pirani command
+============================
+
+Accelerator Variants: *lj/pirani/omp*
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   pair_style lj/pirani cutoff
+
+* lj/pirani = name of the pair style
+* cutoff = global cutoff (distance units)
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   pair_style lj/pirani 10.0
+   pair_coeff 1 1 4.0 7.0 6.0 3.5 0.0045
+
+Description
+"""""""""""
+
+.. versionadded:: TBD
+
+Pair style *lj/pirani* computes pairwise interactions from an Improved
+Lennard-Jones (ILJ) potential according to :ref:`(Pirani) <Pirani>`.
+The ILJ force field is adequate to model both equilibrium and
+non-equilibrium properties of matter, in gaseous and condensed phases,
+and at gas-surface interfaces. In particular, its use improves the
+description of elementary process dynamics where the traditional
+Lennard-Jones (LJ) formulation is usually applied.
+
+
+.. math::
+
+   x = r/R_m   \\
+   n_x = \alpha*x^2 + \beta   \\
+   \gamma \equiv m  \\
+
+  V(x) = \varepsilon \cdot \left( \frac{\gamma}{ n_x - \gamma}  \left(\frac{1}{x} \right)^{n_x}
+          -  \frac{n_x}{n_x - \gamma}  \left(\frac{1}{x} \right)^{\gamma} \right) \qquad r < r_c
+
+:math:`r_c` is the cutoff.
+
+
+An additional parameter, :math:`\alpha`, has been introduced in order to
+be able to recover the traditional Lennard-Jones 12-6 with a specific
+choice of parameters. With :math:`R_m \equiv r_0 = \sigma \cdot 2^{1 /
+6}`, :math:`\alpha = 0`, :math:`\beta = 12` and :math:`\gamma = 6` it is
+straightforward to prove that LJ 12-6 is obtained. Also, it can be
+verified that using :math:`\alpha= 4`, :math:`\beta= 8` and
+:math:`\gamma = 6`, at the equilibrium distance, the first and second
+derivatives of ILJ match those of LJ 12-6. The parameter :math:`R_m`
+corresponds to the equilibrium distance and :math:`\epsilon` to the well
+depth.
+
+
+This potential provides some advantages with respect to the standard LJ
+potential, as explained in :ref:`(Pirani) <Pirani>`: it provides a more
+realistic description of the long range behavior and an attenuation of
+the hardness of the repulsive wall.
+
+This force field can be used for neutral-neutral (:math:`\gamma = 6`),
+ion-neutral (:math:`\gamma = 4`) or ion-ion systems (:math:`\gamma =
+1`).  Notice that this implementation does not include explicit
+electrostatic interactions.  If these are desired, this pair style
+should be used along with a Coulomb pair style like
+:doc:`pair styles coul/cut or coul/long <pair_coul>` by using
+:doc:`pair style hybrid/overlay <pair_hybrid>` and a suitable
+:doc:`kspace style <kspace_style>`, if needed.
+
+As discussed in :ref:`(Pirani) <Pirani>`, analysis of a variety of
+systems showed that :math:`\alpha= 4` generally works very well.  In
+some special cases (e.g. those involving very small multiple charged
+ions) this factor may take a slightly different value. The parameter
+:math:`\beta` codifies the hardness (polarizability) of the interacting
+partners, and for neutral-neutral systems it usually ranges from 6
+to 11.  Moreover, the modulation of :math:`\beta` can model additional
+interaction effects, such as charge transfer in the perturbative limit,
+and can mitigate the effect of some uncertainty in the data used to
+build up the potential function.
+
+The following coefficients must be defined for each pair of atoms
+types via the :doc:`pair_coeff <pair_coeff>` command as in the examples
+above, or in the data file or restart files read by the
+:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
+commands:
+
+* :math:`\alpha` (dimensionless)
+* :math:`\beta` (dimensionless)
+* :math:`\gamma` (dimensionless)
+* :math:`R_m` (distance units)
+* :math:`\epsilon` (energy units)
+* cutoff (distance units)
+
+The last coefficient is optional. If not specified, the global cutoff is used.
+
+----------
+
+.. include:: accel_styles.rst
+
+----------
+
+Mixing, shift, table, tail correction, restart, rRESPA info
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+This pair style does not support mixing.  Thus, coefficients for all I,J
+pairs must be specified explicitly.
+
+This pair style supports the :doc:`pair_modify <pair_modify>` shift
+option for the energy of the pair interaction.
+
+The :doc:`pair_modify <pair_modify>` table options are not relevant for
+this pair style.
+
+This pair style does not support the :doc:`pair_modify <pair_modify>`
+tail option for adding long-range tail corrections to energy and
+pressure.
+
+This pair style writes its information to :doc:`binary restart files
+<restart>`, so pair_style and pair_coeff commands do not need to be
+specified in an input script that reads a restart file.
+
+This pair style supports the use of the *inner*, *middle*, and
+*outer* keywords of the :doc:`run_style respa <run_style>` command,
+meaning the pairwise forces can be partitioned by distance at different
+levels of the rRESPA hierarchy. See the :doc:`run_style <run_style>`
+command for details.
+
+
+----------
+
+Restrictions
+""""""""""""
+
+This pair style is only enabled if LAMMPS was built with the EXTRA-PAIR
+package.  See the :doc:`Build package <Build_package>` page for more
+info.
+
+Related commands
+""""""""""""""""
+
+* :doc:`pair_coeff <pair_coeff>`
+* :doc:`pair_style lj/cut <pair_lj>`
+
+Default
+"""""""
+
+none
+
+--------------
+
+.. _Pirani:
+
+**(Pirani)** F. Pirani, S. Brizi, L. Roncaratti, P. Casavecchia, D. Cappelletti and F. Vecchiocattivi,
+Phys. Chem. Chem. Phys., 2008, 10, 5489-5503.

doc/src/pair_style.rst

@@ -272,6 +272,7 @@ accelerated styles exist.
 * :doc:`lj/long/dipole/long <pair_dipole>` - long-range LJ and long-range point dipoles
 * :doc:`lj/long/tip4p/long <pair_lj_long>` - long-range LJ and long-range Coulomb for TIP4P water
 * :doc:`lj/mdf <pair_mdf>` - LJ potential with a taper function
+* :doc:`lj/pirani <pair_lj_pirani>` - Improved LJ potential
 * :doc:`lj/relres <pair_lj_relres>` - LJ using multiscale Relative Resolution (RelRes) methodology :ref:`(Chaimovich) <Chaimovich2>`.
 * :doc:`lj/spica <pair_spica>` - LJ for SPICA coarse-graining
 * :doc:`lj/spica/coul/long <pair_spica>` - LJ for SPICA coarse-graining with long-range Coulomb