ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'develop' into collected-small-changes

Browse Source
This commit is contained in:
Axel Kohlmeyer
2023-03-16 12:54:48 -04:00
parent d71a78449a 6069e8cb14
commit 180ed2553c
64 changed files with 859 additions and 346 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/src/Commands_bond.rst
View File

@ -42,6 +42,7 @@ OPT.
* :doc:`gaussian <bond_gaussian>`
* :doc:`gromos (o) <bond_gromos>`
* :doc:`harmonic (iko) <bond_harmonic>`
* :doc:`harmonic/restrain <bond_harmonic_restrain>`
* :doc:`harmonic/shift (o) <bond_harmonic_shift>`
* :doc:`harmonic/shift/cut (o) <bond_harmonic_shift_cut>`
* :doc:`lepton (o) <bond_lepton>`

25
doc/src/Developer_notes.rst
View File

@ -11,6 +11,7 @@ Available topics are:
- `Reading and parsing of text and text files`_
- `Requesting and accessing neighbor lists`_
- `Choosing between a custom atom style, fix property/atom, and fix STORE/ATOM`_
- `Fix contributions to instantaneous energy, virial, and cumulative energy`_
- `KSpace PPPM FFT grids`_
@ -216,6 +217,30 @@ command:
neighbor->add_request(this, "delete_atoms", NeighConst::REQ_FULL);
Choosing between a custom atom style, fix property/atom, and fix STORE/ATOM
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are multiple ways to manage per-atom data within LAMMPS. Often
the per-atom storage is only used locally and managed by the class that
uses it. If the data has to persist between multiple time steps and
migrate with atoms when they move from sub-domain to sub-domain or
across periodic boundaries, then using a custom atom style, or :doc:`fix
property/atom <fix_property_atom>`, or the internal fix STORE/ATOM are
possible options.
- Using the atom style is usually the most programming effort and mostly
needed when the per-atom data is an integral part of the model like a
per-atom charge or diameter and thus should be part of the Atoms
section of a :doc:`data file <read_data>`.
- Fix property/atom is useful if the data is optional or should be
entered by the user, or accessed as a (named) custom property. In this
case the fix should be entered as part of the input (and not
internally) which allows to enter and store its content with data files.
- Fix STORE/ATOM should be used when the data should be accessed internally
only and thus the fix can be created internally.
Fix contributions to instantaneous energy, virial, and cumulative energy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

29
doc/src/Developer_updating.rst
View File

@ -24,6 +24,7 @@ Available topics in mostly chronological order are:
- `Use of "override" instead of "virtual"`_
- `Simplified and more compact neighbor list requests`_
- `Split of fix STORE into fix STORE/GLOBAL and fix STORE/PERATOM`_
- `Rename of fix STORE/PERATOM to fix STORE/ATOM and change of arguments`_
- `Use Output::get_dump_by_id() instead of Output::find_dump()`_
- `Refactored grid communication using Grid3d/Grid2d classes instead of GridComm`_
@ -385,6 +386,34 @@ New:
This change is **required** or else the code will not compile.
Rename of fix STORE/PERATOM to fix STORE/ATOM and change of arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionchanged:: TBD
The available functionality of the internal fix to store per-atom
properties was expanded to enable storing data with ghost atoms and to
support binary restart files. With those changes, the fix was renamed
to fix STORE/ATOM and the number and order of (required) arguments has
changed.
Old syntax: ``ID group-ID STORE/PERATOM rflag n1 n2 [n3]``
- *rflag* = 0/1, *no*/*yes* store per-atom values in restart file
- :math:`n1 = 1, n2 = 1, \mathrm{no}\;n3 \to` per-atom vector, single value per atom
- :math:`n1 = 1, n2 > 1, \mathrm{no}\;n3 \to` per-atom array, *n2* values per atom
- :math:`n1 = 1, n2 > 0, n3 > 0 \to` per-atom tensor, *n2* x *n3* values per atom
New syntax: ``ID group-ID STORE/ATOM n1 n2 gflag rflag``
- :math:`n1 = 1, n2 = 0 \to` per-atom vector, single value per atom
- :math:`n1 > 1, n2 = 0 \to` per-atom array, *n1* values per atom
- :math:`n1 > 0, n2 > 0 \to` per-atom tensor, *n1* x *n2* values per atom
- *gflag* = 0/1, *no*/*yes* communicate per-atom values with ghost atoms
- *rflag* = 0/1, *no*/*yes* store per-atom values in restart file
Since this is an internal fix, there is no user visible change.
Use Output::get_dump_by_id() instead of Output::find_dump()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

141
doc/src/Python_install.rst
View File

@ -27,124 +27,19 @@ interpreter can find it and installing the LAMMPS shared library into a
folder that the dynamic loader searches or inside of the installed
``lammps`` package folder. There are multiple ways to achieve this.
#. Do a full LAMMPS installation of libraries, executables, selected
headers, documentation (if enabled), and supporting files (only
available via CMake), which can also be either system-wide or into
user specific folders.
#. Install both components into a Python ``site-packages`` folder, either
system-wide or in the corresponding user-specific folder. This way no
additional environment variables need to be set, but the shared
library is otherwise not accessible.
#. Do an installation into a virtual environment. This can either be an
installation of the Python package only or a full installation of LAMMPS.
#. Do an installation into a virtual environment.
#. Leave the files where they are in the source/development tree and
adjust some environment variables.
.. tabs::
.. tab:: Full install (CMake-only)
:ref:`Build the LAMMPS executable and library <library>` with
``-DBUILD_SHARED_LIBS=on``, ``-DLAMMPS_EXCEPTIONS=on`` and
``-DPKG_PYTHON=on`` (The first option is required, the other two
are optional by recommended). The exact file name of the shared
library depends on the platform (Unix/Linux, macOS, Windows) and
the build configuration being used. The installation base folder
is already set by default to the ``$HOME/.local`` directory, but
it can be changed to a custom location defined by the
``CMAKE_INSTALL_PREFIX`` CMake variable. This uses a folder
called ``build`` to store files generated during compilation.
.. code-block:: bash
# create build folder
mkdir build
cd build
# configure LAMMPS compilation
cmake -C ../cmake/presets/basic.cmake -D BUILD_SHARED_LIBS=on \
-D LAMMPS_EXCEPTIONS=on -D PKG_PYTHON=on ../cmake
# compile LAMMPS
cmake --build .
# install LAMMPS into $HOME/.local
cmake --install .
This leads to an installation to the following locations:
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=================================================================+=============================================================+
| LAMMPS Python package | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/`` (32bit) | Set shared loader environment variable to this path |
| | * ``$HOME/.local/lib64/`` (64bit) | (see below for more info on this) |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``$HOME/.local/bin/`` | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$HOME/.local/share/lammps/potentials/`` | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
For a system-wide installation you need to set
``CMAKE_INSTALL_PREFIX`` to a system folder like ``/usr`` (or
``/usr/local``); the default is ``${HOME}/.local``. The
installation step for a system folder installation (**not** the
configuration/compilation) needs to be done with superuser
privilege, e.g. by using ``sudo cmake --install .``. The
installation folders will then be changed to (assuming ``/usr`` as
prefix):
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=========================================================+=============================================================+
| LAMMPS Python package | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``/usr/lib/`` (32bit) | |
| | * ``/usr/lib64/`` (64bit) | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``/usr/bin/`` | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``/usr/share/lammps/potentials/`` | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
To be able to use the "user" installation you have to ensure that
the folder containing the LAMMPS shared library is either included
in a path searched by the shared linker (e.g. like
``/usr/lib64/``) or part of the ``LD_LIBRARY_PATH`` environment
variable (or ``DYLD_LIBRARY_PATH`` on macOS). Otherwise you will
get an error when trying to create a LAMMPS object through the
Python module.
.. code-block:: bash
# Unix/Linux
export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
# macOS
export DYLD_LIBRARY_PATH=$HOME/.local/lib:$DYLD_LIBRARY_PATH
If you plan to use the LAMMPS executable (e.g., ``lmp``), you may
also need to adjust the ``PATH`` environment variable (but many
newer Linux distributions already have ``$HOME/.local/bin``
included). Example:
.. code-block:: bash
export PATH=$HOME/.local/bin:$PATH
To make those changes permanent, you can add the commands to your
``$HOME/.bashrc`` file. For a system-wide installation is is not
necessary due to files installed in system folders that are loaded
automatically when a login shell is started.
.. tab:: Python package only
.. tab:: Python package
Compile LAMMPS with either :doc:`CMake <Build_cmake>` or the
:doc:`traditional make <Build_make>` procedure in :ref:`shared
@ -272,38 +167,6 @@ folder that the dynamic loader searches or inside of the installed
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
If you do a full installation (CMake only) with "install", this
leads to the following installation locations:
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+========================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/`` (32bit) | Set shared loader environment variable to this path |
| | * ``$VIRTUAL_ENV/lib64/`` (64bit) | (see below for more info on this) |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``$VIRTUAL_ENV/bin/`` | |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$VIRTUAL_ENV/share/lammps/potentials/`` | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
In that case you need to modify the ``$HOME/myenv/bin/activate``
script in a similar fashion you need to update your
``$HOME/.bashrc`` file to include the shared library and
executable locations in ``LD_LIBRARY_PATH`` (or
``DYLD_LIBRARY_PATH`` on macOS) and ``PATH``, respectively.
For example with:
.. code-block:: bash
# Unix/Linux
echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
# macOS
echo 'export DYLD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$DYLD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
.. tab:: In place usage
You can also :doc:`compile LAMMPS <Build>` as usual in

90
doc/src/bond_harmonic_restrain.rst Normal file
View File

@ -0,0 +1,90 @@
.. index:: bond_style harmonic/restrain
bond_style harmonic/restrain command
====================================
Syntax
""""""
.. code-block:: LAMMPS
bond_style harmonic/restrain
Examples
""""""""
.. code-block:: LAMMPS
bond_style harmonic
bond_coeff 5 80.0
Description
"""""""""""
.. versionadded:: TBD
The *harmonic/restrain* bond style uses the potential
.. math::
E = K (r - r_{t=0})^2
where :math:`r_{t=0}` is the distance between the bonded atoms at the
beginning of the first :doc:`run <run>` or :doc:`minimize <minimize>`
command after the bond style has been defined (*t=0*). Note that the
usual 1/2 factor is included in :math:`K`. This will effectively
restrain bonds to their initial length, whatever that is. This is where
this bond style differs from :doc:`bond style harmonic <bond_harmonic>`
where the bond length is set through the per bond type coefficients.
The following coefficient must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example 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:`K` (energy/distance\^2)
This bond style differs from other options to add harmonic restraints
like :doc:`fix restrain <fix_restrain>` or :doc:`pair style list
<pair_list>` or :doc:`fix colvars <fix_colvars>` in that it requires a
bond topology, and thus the defined bonds will trigger exclusion of
special neighbors from the neighbor list according to the
:doc:`special_bonds <special_bonds>` settings.
Restart info
""""""""""""
This bond style supports the :doc:`write_restart <write_restart>` and
:doc:`read_restart <read_restart>` commands. The state of the initial
bond lengths is stored with restart files and read back.
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>`
page for more info.
This bond style maintains internal data to determine the original bond
lengths :math:`r_{t=0}`. This information will be written to
:doc:`binary restart files <write_restart>` but **not** to :doc:`data
files <write_data>`. Thus, continuing a simulation is *only* possible
with :doc:`read_restart <read_restart>`. When using the :doc:`read_data
command <read_data>`, the reference bond lengths :math:`r_{t=0}` will be
re-initialized from the current geometry.
This bond style cannot be used with :doc:`fix shake or fix rattle
<fix_shake>`, with :doc:`fix filter/corotate <fix_filter_corotate>`, or
any :doc:`tip4p pair style <pair_lj_cut_tip4p>` since there is no specific
equilibrium distance for a given bond type.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`bond_harmonic <bond_harmonic>`,
:doc:`fix restrain <fix_restrain>`, :doc:`pair style list <pair_list>`
Default
"""""""
none

3
doc/src/bond_style.rst
View File

@ -10,7 +10,7 @@ Syntax
bond_style style args
* style = *none* or *zero* or *hybrid* or *bpm/rotational* or *bpm/spring* or *class2* or *fene* or *fene/expand* or *fene/nm* or *gaussian* or *gromos* or *harmonic* or *harmonic/shift* or *harmonic/shift/cut* or *lepton* or *morse* or *nonlinear* or *oxdna/fene* or *oxdena2/fene* or *oxrna2/fene* or *quartic* or *special* or *table*
* style = *none* or *zero* or *hybrid* or *bpm/rotational* or *bpm/spring* or *class2* or *fene* or *fene/expand* or *fene/nm* or *gaussian* or *gromos* or *harmonic* or *harmonic/restrain* *harmonic/shift* or *harmonic/shift/cut* or *lepton* or *morse* or *nonlinear* or *oxdna/fene* or *oxdena2/fene* or *oxrna2/fene* or *quartic* or *special* or *table*
* args = none for any style except *hybrid*
@ -93,6 +93,7 @@ accelerated styles exist.
* :doc:`gaussian <bond_gaussian>` - multicentered Gaussian-based bond potential
* :doc:`gromos <bond_gromos>` - GROMOS force field bond
* :doc:`harmonic <bond_harmonic>` - harmonic bond
* :doc:`harmonic/restrain <bond_harmonic_restrain>` - harmonic bond to restrain to original bond distance
* :doc:`harmonic/shift <bond_harmonic_shift>` - shifted harmonic bond
* :doc:`harmonic/shift/cut <bond_harmonic_shift_cut>` - shifted harmonic bond with a cutoff
* :doc:`lepton <bond_lepton>` - bond potential from evaluating a string