diff --git a/doc/rst/Build_basics.rst b/doc/rst/Build_basics.rst index 0f454994a5..cf77c81e69 100644 --- a/doc/rst/Build_basics.rst +++ b/doc/rst/Build_basics.rst @@ -55,7 +55,7 @@ Serial build (see src/MAKE/Makefile.serial): MPI_INC = -I../STUBS MPI_PATH = -L../STUBS - MPI_LIB = -lmpi_stubs + MPI_LIB = -lmpi_stubs For a parallel build, if MPI is installed on your system in the usual place (e.g. under /usr/local), you do not need to specify the 3 @@ -205,20 +205,20 @@ Parallel build (see src/MAKE/Makefile.mpi): .. parsed-literal:: - CC = mpicxx - CCFLAGS = -g -O3 - LINK = mpicxx - LINKFLAGS = -g -O + CC = mpicxx + CCFLAGS = -g -O3 + LINK = mpicxx + LINKFLAGS = -g -O Serial build (see src/MAKE/Makefile.serial): .. parsed-literal:: - CC = g++ - CCFLAGS = -g -O3 - LINK = g++ - LINKFLAGS = -g -O + CC = g++ + CCFLAGS = -g -O3 + LINK = g++ + LINKFLAGS = -g -O The "compiler/linker settings" section of a Makefile.machine lists compiler and linker settings for your C++ compiler, including diff --git a/doc/rst/Build_extras.rst b/doc/rst/Build_extras.rst index 88b4bc2764..1b5fa1672f 100644 --- a/doc/rst/Build_extras.rst +++ b/doc/rst/Build_extras.rst @@ -342,7 +342,7 @@ files. KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd) export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper - CC = mpicxx + CC = mpicxx ---------- @@ -786,17 +786,40 @@ library in lib/linalg with a command like these: USER-COLVARS package --------------------------------------- +This package includes into the LAMMPS distribution the Colvars library, which +can be built for the most part with all major versions of the C++ language. + +A few of the most recent features require C++11 support. In particular, the +library is optionally built together with the +`Lepton `_ library, a copy of which is also +included in the LAMMPS distribution. Lepton implements the +`customFunction `_ +feature, and requires C++11 support. + +See `here `_ for a detailed list of +C++11-only features. + **CMake build**\ : -No additional settings are needed besides "-D PKG\_USER-COLVARS=yes". +This is the recommended build recipe: no additional settings are normally +needed besides "-D PKG\_USER-COLVARS=yes". + +Building and linking of Lepton (or other C++11-only features) is enabled +automatically when compilation is carried out with C++11 support, and disabled +otherwise. Optionally, Lepton build may be manually controlled with the flag +"-D COLVARS\_LEPTON=yes\|no". **Traditional make**\ : -Before building LAMMPS, you must build the COLVARS library in -lib/colvars. You can do this manually if you prefer; follow the -instructions in lib/colvars/README. You can also do it in one step -from the lammps/src dir, using a command like these, which simply -invoke the lib/colvars/Install.py script with the specified args: +Before building LAMMPS, one must build the Colvars library in lib/colvars. + +This can be done manually in the same folder by using or adapting one of the +provided Makefiles: for example, Makefile.g++ for the GNU compiler. + +In general, it is safer to use build setting consistent with the rest of +LAMMPS. This is best carried out from the LAMMPS src directory using a +command like these, which simply invoke the lib/colvars/Install.py script with +the specified args: .. parsed-literal:: @@ -806,13 +829,20 @@ invoke the lib/colvars/Install.py script with the specified args: make lib-colvars args="-m mpi" # build with default MPI compiler (settings as with "make mpi") make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled -The build should produce two files: lib/colvars/libcolvars.a and -lib/colvars/Makefile.lammps. The latter is copied from an existing -Makefile.lammps.\* and has settings needed to build LAMMPS with the -COLVARS library (though typically the settings are just blank). If -necessary, you can edit/create a new lib/colvars/Makefile.machine file -for your system, which should define an EXTRAMAKE variable to specify -a corresponding Makefile.lammps.machine file. +The "machine" argument of the "-m" flag is used to find a Makefile.machine to +use as build recipe. If it does not already exist in lib/colvars, it will be +auto-generated by using compiler flags consistent with those parsed from the +core LAMMPS makefiles. + +Optional flags may be specified as environment variables: + +COLVARS\_DEBUG=yes make lib-colvars args="-m machine" # Build with debug code (much slower) +COLVARS\_LEPTON=no make lib-colvars args="-m machine" # Build without Lepton (included otherwise) + +The build should produce two files: the library lib/colvars/libcolvars.a +(which also includes Lepton objects if enabled) and the specification file +lib/colvars/Makefile.lammps. The latter is auto-generated, and normally does +not need to be edited. ---------- @@ -972,7 +1002,7 @@ lib/h5md/Install.py script with the specified args: .. parsed-literal:: make lib-h5md # print help message - make lib-hm5d args="-m h5cc" # build with h5cc compiler + make lib-h5md args="-m h5cc" # build with h5cc compiler The build should produce two files: lib/h5md/libch5md.a and lib/h5md/Makefile.lammps. The latter is copied from an existing @@ -1030,8 +1060,8 @@ For CPUs: .. parsed-literal:: OPTFLAGS = -xHost -O2 -fp-model fast=2 -no-prec-div -qoverride-limits -qopt-zmm-usage=high - CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $(OPTFLAGS) - LINKFLAGS = -g -qopenmp $(OPTFLAGS) + CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $(OPTFLAGS) + LINKFLAGS = -g -qopenmp $(OPTFLAGS) LIB = -ltbbmalloc For KNLs: @@ -1040,8 +1070,8 @@ For KNLs: .. parsed-literal:: OPTFLAGS = -xMIC-AVX512 -O2 -fp-model fast=2 -no-prec-div -qoverride-limits - CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $(OPTFLAGS) - LINKFLAGS = -g -qopenmp $(OPTFLAGS) + CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $(OPTFLAGS) + LINKFLAGS = -g -qopenmp $(OPTFLAGS) LIB = -ltbbmalloc diff --git a/doc/rst/Build_settings.rst b/doc/rst/Build_settings.rst index e80afd482f..07d427db49 100644 --- a/doc/rst/Build_settings.rst +++ b/doc/rst/Build_settings.rst @@ -4,6 +4,7 @@ Optional build settings LAMMPS can be built with several optional settings. Each sub-section explain how to do this for building both with CMake and make. +| :ref:`C++11 standard compliance test ` when building all of LAMMPS | :ref:`FFT library ` for use with the :doc:`kspace\_style pppm ` command | :ref:`Size of LAMMPS data types ` | :ref:`Read or write compressed files ` @@ -18,6 +19,47 @@ explain how to do this for building both with CMake and make. ---------- +.. _cxx11: + +C++11 standard compliance test +------------------------------------------ + +The LAMMPS developers plan to transition to make the C++11 standard the +minimum requirement for compiling LAMMPS. Currently this only applies to +some packages like KOKKOS while the rest aims to be compatible with the C++98 +standard. Most currently used compilers are compatible with C++11; some need +to set extra flags to switch. To determine the impact of requiring C++11, +we have added a simple compliance test to the source code, that will cause +the compilation to abort, if C++11 compliance is not available or enabled. +To bypass this check, you need to change a setting in the makefile or +when calling CMake. + +**CMake variable**\ : + + +.. parsed-literal:: + + -D DISABLE_CXX11_REQUIREMENT=yes + +You can set additional C++ compiler flags (beyond those selected by CMake) +through the CMAKE\_CXX\_FLAGS variable. Example for CentOS 7: + + +.. parsed-literal:: + + -D CMAKE_CXX_FLAGS="-O3 -g -fopenmp -DNDEBUG -std=c++11" + +**Makefile.machine setting**\ : + + +.. parsed-literal:: + + LMP_INC = -DLAMMPS_CXX98 + + +---------- + + .. _fft: FFT library diff --git a/doc/rst/Commands_all.rst b/doc/rst/Commands_all.rst index fcd6cdd689..583e9e3c3a 100644 --- a/doc/rst/Commands_all.rst +++ b/doc/rst/Commands_all.rst @@ -46,11 +46,11 @@ An alphabetic list of all general LAMMPS commands. +-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ | :doc:`tad ` | :doc:`temper ` | :doc:`temper/grem ` | :doc:`temper/npt ` | :doc:`thermo ` | :doc:`thermo\_modify ` | +-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`thermo\_style ` | :doc:`timer ` | :doc:`timestep ` | :doc:`uncompute ` | :doc:`undump ` | :doc:`unfix ` | +| :doc:`thermo\_style ` | :doc:`third\_order ` | :doc:`timer ` | :doc:`timestep ` | :doc:`uncompute ` | :doc:`undump ` | +-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`units ` | :doc:`variable ` | :doc:`velocity ` | :doc:`write\_coeff ` | :doc:`write\_data ` | :doc:`write\_dump ` | +| :doc:`unfix ` | :doc:`units ` | :doc:`variable ` | :doc:`velocity ` | :doc:`write\_coeff ` | :doc:`write\_data ` | +-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ -| :doc:`write\_restart ` | | | | | | +| :doc:`write\_dump ` | :doc:`write\_restart ` | | | | | +-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ diff --git a/doc/rst/Commands_bond.rst b/doc/rst/Commands_bond.rst index f8ce437377..2eb6c1f8c7 100644 --- a/doc/rst/Commands_bond.rst +++ b/doc/rst/Commands_bond.rst @@ -66,19 +66,19 @@ have accelerated versions. This is indicated by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT. -+-------------------------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------------------+ -| :doc:`none ` | :doc:`zero ` | :doc:`hybrid ` | | -+-------------------------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------------------+ -| | | | | -+-------------------------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------------------+ -| :doc:`charmm (iko) ` | :doc:`charmmfsw ` | :doc:`class2 (ko) ` | :doc:`cosine/shift/exp (o) ` | -+-------------------------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------------------+ -| :doc:`fourier (io) ` | :doc:`harmonic (io) ` | :doc:`helix (o) ` | :doc:`multi/harmonic (o) ` | -+-------------------------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------------------+ -| :doc:`nharmonic (o) ` | :doc:`opls (iko) ` | :doc:`quadratic (o) ` | :doc:`spherical ` | -+-------------------------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------------------+ -| :doc:`table (o) ` | :doc:`table/cut ` | | | -+-------------------------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------------------+ ++-------------------------------------------+-------------------------------------------+-------------------------------------------+---------------------------------------------------------+ +| :doc:`none ` | :doc:`zero ` | :doc:`hybrid ` | | ++-------------------------------------------+-------------------------------------------+-------------------------------------------+---------------------------------------------------------+ +| | | | | ++-------------------------------------------+-------------------------------------------+-------------------------------------------+---------------------------------------------------------+ +| :doc:`charmm (iko) ` | :doc:`charmmfsw ` | :doc:`class2 (ko) ` | :doc:`cosine/shift/exp (o) ` | ++-------------------------------------------+-------------------------------------------+-------------------------------------------+---------------------------------------------------------+ +| :doc:`fourier (io) ` | :doc:`harmonic (iko) ` | :doc:`helix (o) ` | :doc:`multi/harmonic (o) ` | ++-------------------------------------------+-------------------------------------------+-------------------------------------------+---------------------------------------------------------+ +| :doc:`nharmonic (o) ` | :doc:`opls (iko) ` | :doc:`quadratic (o) ` | :doc:`spherical ` | ++-------------------------------------------+-------------------------------------------+-------------------------------------------+---------------------------------------------------------+ +| :doc:`table (o) ` | :doc:`table/cut ` | | | ++-------------------------------------------+-------------------------------------------+-------------------------------------------+---------------------------------------------------------+ ---------- diff --git a/doc/rst/Commands_pair.rst b/doc/rst/Commands_pair.rst index c25c547693..d5ed86886a 100644 --- a/doc/rst/Commands_pair.rst +++ b/doc/rst/Commands_pair.rst @@ -14,121 +14,121 @@ accelerated versions. This is indicated by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT. -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`none ` | :doc:`zero ` | :doc:`hybrid (k) ` | :doc:`hybrid/overlay (k) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| | | | | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`adp (o) ` | :doc:`agni (o) ` | :doc:`airebo (io) ` | :doc:`airebo/morse (io) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`atm ` | :doc:`awpmd/cut ` | :doc:`beck (go) ` | :doc:`body/nparticle ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`body/rounded/polygon ` | :doc:`body/rounded/polyhedron ` | :doc:`bop ` | :doc:`born (go) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`born/coul/dsf ` | :doc:`born/coul/dsf/cs ` | :doc:`born/coul/long (go) ` | :doc:`born/coul/long/cs (g) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`born/coul/msm (o) ` | :doc:`born/coul/wolf (go) ` | :doc:`born/coul/wolf/cs (g) ` | :doc:`brownian (o) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`brownian/poly (o) ` | :doc:`buck (giko) ` | :doc:`buck/coul/cut (giko) ` | :doc:`buck/coul/long (giko) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`buck/coul/long/cs ` | :doc:`buck/coul/msm (o) ` | :doc:`buck/long/coul/long (o) ` | :doc:`buck/mdf ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`buck6d/coul/gauss/dsf ` | :doc:`buck6d/coul/gauss/long ` | :doc:`colloid (go) ` | :doc:`comb (o) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`comb3 ` | :doc:`cosine/squared ` | :doc:`coul/cut (gko) ` | :doc:`coul/cut/soft (o) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`coul/debye (gko) ` | :doc:`coul/diel (o) ` | :doc:`coul/dsf (gko) ` | :doc:`coul/long (gko) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`coul/long/cs (g) ` | :doc:`coul/long/soft (o) ` | :doc:`coul/msm (o) ` | :doc:`coul/shield ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`coul/streitz ` | :doc:`coul/wolf (ko) ` | :doc:`coul/wolf/cs ` | :doc:`dpd (gio) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`dpd/fdt ` | :doc:`dpd/fdt/energy (k) ` | :doc:`dpd/tstat (go) ` | :doc:`dsmc ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`e3b ` | :doc:`drip ` | :doc:`eam (gikot) ` | :doc:`eam/alloy (gikot) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`eam/cd (o) ` | :doc:`eam/cd/old (o) ` | :doc:`eam/fs (gikot) ` | :doc:`edip (o) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`edip/multi ` | :doc:`edpd ` | :doc:`eff/cut ` | :doc:`eim (o) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`exp6/rx (k) ` | :doc:`extep ` | :doc:`gauss (go) ` | :doc:`gauss/cut (o) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`gayberne (gio) ` | :doc:`gran/hertz/history (o) ` | :doc:`gran/hooke (o) ` | :doc:`gran/hooke/history (ko) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`granular ` | :doc:`gw ` | :doc:`gw/zbl ` | :doc:`hbond/dreiding/lj (o) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`hbond/dreiding/morse (o) ` | :doc:`ilp/graphene/hbn ` | :doc:`kim ` | :doc:`kolmogorov/crespi/full ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`kolmogorov/crespi/z ` | :doc:`lcbop ` | :doc:`lebedeva/z ` | :doc:`lennard/mdf ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`line/lj ` | :doc:`list ` | :doc:`lj/charmm/coul/charmm (iko) ` | :doc:`lj/charmm/coul/charmm/implicit (ko) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`lj/charmm/coul/long (gikot) ` | :doc:`lj/charmm/coul/long/soft (o) ` | :doc:`lj/charmm/coul/msm (o) ` | :doc:`lj/charmmfsw/coul/charmmfsh ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`lj/charmmfsw/coul/long ` | :doc:`lj/class2 (gko) ` | :doc:`lj/class2/coul/cut (ko) ` | :doc:`lj/class2/coul/cut/soft ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`lj/class2/coul/long (gko) ` | :doc:`lj/class2/coul/long/soft ` | :doc:`lj/class2/soft ` | :doc:`lj/cubic (go) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`lj/cut (gikot) ` | :doc:`lj/cut/coul/cut (gko) ` | :doc:`lj/cut/coul/cut/soft (o) ` | :doc:`lj/cut/coul/debye (gko) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`lj/cut/coul/dsf (gko) ` | :doc:`lj/cut/coul/long (gikot) ` | :doc:`lj/cut/coul/long/cs ` | :doc:`lj/cut/coul/long/soft (o) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`lj/cut/coul/msm (go) ` | :doc:`lj/cut/coul/wolf (o) ` | :doc:`lj/cut/dipole/cut (go) ` | :doc:`lj/cut/dipole/long (g) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`lj/cut/dipole/sf (go) ` | :doc:`lj/cut/soft (o) ` | :doc:`lj/cut/thole/long (o) ` | :doc:`lj/cut/tip4p/cut (o) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`lj/cut/tip4p/long (ot) ` | :doc:`lj/cut/tip4p/long/soft (o) ` | :doc:`lj/expand (gko) ` | :doc:`lj/expand/coul/long (g) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`lj/gromacs (gko) ` | :doc:`lj/gromacs/coul/gromacs (ko) ` | :doc:`lj/long/coul/long (iot) ` | :doc:`lj/long/dipole/long ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`lj/long/tip4p/long (o) ` | :doc:`lj/mdf ` | :doc:`lj/sdk (gko) ` | :doc:`lj/sdk/coul/long (go) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`lj/sdk/coul/msm (o) ` | :doc:`lj/sf/dipole/sf (go) ` | :doc:`lj/smooth (o) ` | :doc:`lj/smooth/linear (o) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`lj/switch3/coulgauss/long ` | :doc:`lj96/cut (go) ` | :doc:`lubricate (o) ` | :doc:`lubricate/poly (o) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`lubricateU ` | :doc:`lubricateU/poly ` | :doc:`mdpd ` | :doc:`mdpd/rhosum ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`meam/c ` | :doc:`meam/spline (o) ` | :doc:`meam/sw/spline ` | :doc:`mgpt ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`mie/cut (g) ` | :doc:`momb ` | :doc:`morse (gkot) ` | :doc:`morse/smooth/linear (o) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`morse/soft ` | :doc:`multi/lucy ` | :doc:`multi/lucy/rx (k) ` | :doc:`nb3b/harmonic ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`nm/cut (o) ` | :doc:`nm/cut/coul/cut (o) ` | :doc:`nm/cut/coul/long (o) ` | :doc:`oxdna/coaxstk ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`oxdna/excv ` | :doc:`oxdna/hbond ` | :doc:`oxdna/stk ` | :doc:`oxdna/xstk ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`oxdna2/coaxstk ` | :doc:`oxdna2/dh ` | :doc:`oxdna2/excv ` | :doc:`oxdna2/hbond ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`oxdna2/stk ` | :doc:`oxdna2/xstk ` | :doc:`peri/eps ` | :doc:`peri/lps (o) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`peri/pmb (o) ` | :doc:`peri/ves ` | :doc:`polymorphic ` | :doc:`python ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`quip ` | :doc:`reax/c (ko) ` | :doc:`rebo (io) ` | :doc:`resquared (go) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`sdpd/taitwater/isothermal ` | :doc:`smd/hertz ` | :doc:`smd/tlsph ` | :doc:`smd/tri\_surface ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`smd/ulsph ` | :doc:`smtbq ` | :doc:`snap (k) ` | :doc:`snap (k) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`soft (go) ` | :doc:`sph/heatconduction ` | :doc:`sph/idealgas ` | :doc:`sph/lj ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`sph/rhosum ` | :doc:`sph/taitwater ` | :doc:`sph/taitwater/morris ` | :doc:`spin/dipole/cut ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`spin/dipole/long ` | :doc:`spin/dmi ` | :doc:`spin/exchange ` | :doc:`spin/magelec ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`spin/neel ` | :doc:`srp ` | :doc:`sw (giko) ` | :doc:`table (gko) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`table/rx (k) ` | :doc:`tdpd ` | :doc:`tersoff (giko) ` | :doc:`tersoff/mod (gko) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`tersoff/mod/c (o) ` | :doc:`tersoff/table (o) ` | :doc:`tersoff/zbl (gko) ` | :doc:`thole ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`tip4p/cut (o) ` | :doc:`tip4p/long (o) ` | :doc:`tip4p/long/soft (o) ` | :doc:`tri/lj ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`ufm (got) ` | :doc:`vashishta (gko) ` | :doc:`vashishta/table (o) ` | :doc:`yukawa (gko) ` | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ -| :doc:`yukawa/colloid (go) ` | :doc:`zbl (gko) ` | | | -+-------------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------+-------------------------------------------------------------+ ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`none ` | :doc:`zero ` | :doc:`hybrid (k) ` | :doc:`hybrid/overlay (k) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| | | | | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`adp (o) ` | :doc:`agni (o) ` | :doc:`airebo (io) ` | :doc:`airebo/morse (io) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`atm ` | :doc:`awpmd/cut ` | :doc:`beck (go) ` | :doc:`body/nparticle ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`body/rounded/polygon ` | :doc:`body/rounded/polyhedron ` | :doc:`bop ` | :doc:`born (go) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`born/coul/dsf ` | :doc:`born/coul/dsf/cs ` | :doc:`born/coul/long (go) ` | :doc:`born/coul/long/cs (g) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`born/coul/msm (o) ` | :doc:`born/coul/wolf (go) ` | :doc:`born/coul/wolf/cs (g) ` | :doc:`brownian (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`brownian/poly (o) ` | :doc:`buck (giko) ` | :doc:`buck/coul/cut (giko) ` | :doc:`buck/coul/long (giko) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`buck/coul/long/cs ` | :doc:`buck/coul/msm (o) ` | :doc:`buck/long/coul/long (o) ` | :doc:`buck/mdf ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`buck6d/coul/gauss/dsf ` | :doc:`buck6d/coul/gauss/long ` | :doc:`colloid (go) ` | :doc:`comb (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`comb3 ` | :doc:`cosine/squared ` | :doc:`coul/cut (gko) ` | :doc:`coul/cut/soft (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`coul/debye (gko) ` | :doc:`coul/diel (o) ` | :doc:`coul/dsf (gko) ` | :doc:`coul/long (gko) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`coul/long/cs (g) ` | :doc:`coul/long/soft (o) ` | :doc:`coul/msm (o) ` | :doc:`coul/shield ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`coul/streitz ` | :doc:`coul/wolf (ko) ` | :doc:`coul/wolf/cs ` | :doc:`dpd (gio) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`dpd/fdt ` | :doc:`dpd/fdt/energy (k) ` | :doc:`dpd/tstat (go) ` | :doc:`dsmc ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`e3b ` | :doc:`drip ` | :doc:`eam (gikot) ` | :doc:`eam/alloy (gikot) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`eam/cd (o) ` | :doc:`eam/cd/old (o) ` | :doc:`eam/fs (gikot) ` | :doc:`edip (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`edip/multi ` | :doc:`edpd ` | :doc:`eff/cut ` | :doc:`eim (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`exp6/rx (k) ` | :doc:`extep ` | :doc:`gauss (go) ` | :doc:`gauss/cut (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`gayberne (gio) ` | :doc:`gran/hertz/history (o) ` | :doc:`gran/hooke (o) ` | :doc:`gran/hooke/history (ko) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`granular ` | :doc:`gw ` | :doc:`gw/zbl ` | :doc:`hbond/dreiding/lj (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`hbond/dreiding/morse (o) ` | :doc:`ilp/graphene/hbn ` | :doc:`kim ` | :doc:`kolmogorov/crespi/full ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`kolmogorov/crespi/z ` | :doc:`lcbop ` | :doc:`lebedeva/z ` | :doc:`lennard/mdf ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`line/lj ` | :doc:`list ` | :doc:`lj/charmm/coul/charmm (iko) ` | :doc:`lj/charmm/coul/charmm/implicit (ko) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`lj/charmm/coul/long (gikot) ` | :doc:`lj/charmm/coul/long/soft (o) ` | :doc:`lj/charmm/coul/msm (o) ` | :doc:`lj/charmmfsw/coul/charmmfsh ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`lj/charmmfsw/coul/long ` | :doc:`lj/class2 (gko) ` | :doc:`lj/class2/coul/cut (ko) ` | :doc:`lj/class2/coul/cut/soft ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`lj/class2/coul/long (gko) ` | :doc:`lj/class2/coul/long/soft ` | :doc:`lj/class2/soft ` | :doc:`lj/cubic (go) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`lj/cut (gikot) ` | :doc:`lj/cut/coul/cut (gko) ` | :doc:`lj/cut/coul/cut/soft (o) ` | :doc:`lj/cut/coul/debye (gko) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`lj/cut/coul/dsf (gko) ` | :doc:`lj/cut/coul/long (gikot) ` | :doc:`lj/cut/coul/long/cs ` | :doc:`lj/cut/coul/long/soft (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`lj/cut/coul/msm (go) ` | :doc:`lj/cut/coul/wolf (o) ` | :doc:`lj/cut/dipole/cut (go) ` | :doc:`lj/cut/dipole/long (g) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`lj/cut/dipole/sf (go) ` | :doc:`lj/cut/soft (o) ` | :doc:`lj/cut/thole/long (o) ` | :doc:`lj/cut/tip4p/cut (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`lj/cut/tip4p/long (ot) ` | :doc:`lj/cut/tip4p/long/soft (o) ` | :doc:`lj/expand (gko) ` | :doc:`lj/expand/coul/long (g) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`lj/gromacs (gko) ` | :doc:`lj/gromacs/coul/gromacs (ko) ` | :doc:`lj/long/coul/long (iot) ` | :doc:`lj/long/dipole/long ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`lj/long/tip4p/long (o) ` | :doc:`lj/mdf ` | :doc:`lj/sdk (gko) ` | :doc:`lj/sdk/coul/long (go) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`lj/sdk/coul/msm (o) ` | :doc:`lj/sf/dipole/sf (go) ` | :doc:`lj/smooth (o) ` | :doc:`lj/smooth/linear (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`lj/switch3/coulgauss/long ` | :doc:`lj96/cut (go) ` | :doc:`local/density ` | :doc:`lubricate (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`lubricate/poly (o) ` | :doc:`lubricateU ` | :doc:`lubricateU/poly ` | :doc:`mdpd ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`mdpd/rhosum ` | :doc:`meam/c ` | :doc:`meam/spline (o) ` | :doc:`meam/sw/spline ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`mgpt ` | :doc:`mie/cut (g) ` | :doc:`momb ` | :doc:`morse (gkot) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`morse/smooth/linear (o) ` | :doc:`morse/soft ` | :doc:`multi/lucy ` | :doc:`multi/lucy/rx (k) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`nb3b/harmonic ` | :doc:`nm/cut (o) ` | :doc:`nm/cut/coul/cut (o) ` | :doc:`nm/cut/coul/long (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`oxdna/coaxstk ` | :doc:`oxdna/excv ` | :doc:`oxdna/hbond ` | :doc:`oxdna/stk ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`oxdna/xstk ` | :doc:`oxdna2/coaxstk ` | :doc:`oxdna2/dh ` | :doc:`oxdna2/excv ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`oxdna2/hbond ` | :doc:`oxdna2/stk ` | :doc:`oxdna2/xstk ` | :doc:`peri/eps ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`peri/lps (o) ` | :doc:`peri/pmb (o) ` | :doc:`peri/ves ` | :doc:`polymorphic ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`python ` | :doc:`quip ` | :doc:`reax/c (ko) ` | :doc:`rebo (io) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`resquared (go) ` | :doc:`sdpd/taitwater/isothermal ` | :doc:`smd/hertz ` | :doc:`smd/tlsph ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`smd/tri\_surface ` | :doc:`smd/ulsph ` | :doc:`smtbq ` | :doc:`snap (k) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`snap (k) ` | :doc:`soft (go) ` | :doc:`sph/heatconduction ` | :doc:`sph/idealgas ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`sph/lj ` | :doc:`sph/rhosum ` | :doc:`sph/taitwater ` | :doc:`sph/taitwater/morris ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`spin/dipole/cut ` | :doc:`spin/dipole/long ` | :doc:`spin/dmi ` | :doc:`spin/exchange ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`spin/magelec ` | :doc:`spin/neel ` | :doc:`srp ` | :doc:`sw (giko) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`table (gko) ` | :doc:`table/rx (k) ` | :doc:`tdpd ` | :doc:`tersoff (giko) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`tersoff/mod (gko) ` | :doc:`tersoff/mod/c (o) ` | :doc:`tersoff/table (o) ` | :doc:`tersoff/zbl (gko) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`thole ` | :doc:`tip4p/cut (o) ` | :doc:`tip4p/long (o) ` | :doc:`tip4p/long/soft (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`tri/lj ` | :doc:`ufm (got) ` | :doc:`vashishta (gko) ` | :doc:`vashishta/table (o) ` | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ +| :doc:`yukawa (gko) ` | :doc:`yukawa/colloid (go) ` | :doc:`zbl (gko) ` | | ++--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+ .. _lws: http://lammps.sandia.gov diff --git a/doc/rst/Commands_structure.rst b/doc/rst/Commands_structure.rst deleted file mode 100644 index d04d2cd98e..0000000000 --- a/doc/rst/Commands_structure.rst +++ /dev/null @@ -1,91 +0,0 @@ -Input script structure -====================== - -This page describes the structure of a typical LAMMPS input script. -The examples directory in the LAMMPS distribution contains many sample -input scripts; it is discussed on the :doc:`Examples ` doc -page. - -A LAMMPS input script typically has 4 parts: - -1. Initialization -2. Atom definition -3. Settings -4. Run a simulation - -The last 2 parts can be repeated as many times as desired. I.e. run a -simulation, change some settings, run some more, etc. Each of the 4 -parts is now described in more detail. Remember that almost all -commands need only be used if a non-default value is desired. - -(1) Initialization - -Set parameters that need to be defined before atoms are created or -read-in from a file. - -The relevant commands are :doc:`units `, -:doc:`dimension `, :doc:`newton `, -:doc:`processors `, :doc:`boundary `, -:doc:`atom\_style `, :doc:`atom\_modify `. - -If force-field parameters appear in the files that will be read, these -commands tell LAMMPS what kinds of force fields are being used: -:doc:`pair\_style `, :doc:`bond\_style `, -:doc:`angle\_style `, :doc:`dihedral\_style `, -:doc:`improper\_style `. - -(2) Atom definition - -There are 3 ways to define atoms in LAMMPS. Read them in from a data -or restart file via the :doc:`read\_data ` or -:doc:`read\_restart ` commands. These files can contain -molecular topology information. Or create atoms on a lattice (with no -molecular topology), using these commands: :doc:`lattice `, -:doc:`region `, :doc:`create\_box `, -:doc:`create\_atoms `. The entire set of atoms can be -duplicated to make a larger simulation using the -:doc:`replicate ` command. - -(3) Settings - -Once atoms and molecular topology are defined, a variety of settings -can be specified: force field coefficients, simulation parameters, -output options, etc. - -Force field coefficients are set by these commands (they can also be -set in the read-in files): :doc:`pair\_coeff `, -:doc:`bond\_coeff `, :doc:`angle\_coeff `, -:doc:`dihedral\_coeff `, -:doc:`improper\_coeff `, -:doc:`kspace\_style `, :doc:`dielectric `, -:doc:`special\_bonds `. - -Various simulation parameters are set by these commands: -:doc:`neighbor `, :doc:`neigh\_modify `, -:doc:`group `, :doc:`timestep `, -:doc:`reset\_timestep `, :doc:`run\_style `, -:doc:`min\_style `, :doc:`min\_modify `. - -Fixes impose a variety of boundary conditions, time integration, and -diagnostic options. The :doc:`fix ` command comes in many flavors. - -Various computations can be specified for execution during a -simulation using the :doc:`compute `, -:doc:`compute\_modify `, and :doc:`variable ` -commands. - -Output options are set by the :doc:`thermo `, :doc:`dump `, -and :doc:`restart ` commands. - -(4) Run a simulation - -A molecular dynamics simulation is run using the :doc:`run ` -command. Energy minimization (molecular statics) is performed using -the :doc:`minimize ` command. A parallel tempering -(replica-exchange) simulation can be run using the -:doc:`temper ` command. - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/Errors_messages.rst b/doc/rst/Errors_messages.rst index 30739bbed4..71de83afa9 100644 --- a/doc/rst/Errors_messages.rst +++ b/doc/rst/Errors_messages.rst @@ -3702,6 +3702,18 @@ Doc page with :doc:`WARNING messages ` *Fix langevin angmom requires extended particles* This fix option cannot be used with point particles. +*Fix langevin gjf and respa are not compatible* + Self-explanatory. + +*Fix langevin gjf cannot have period equal to dt/2* + If the period is equal to dt/2 then division by zero will happen. + +*Fix langevin gjf should come before fix nve* + Self-explanatory. + +*Fix langevin gjf with tbias is not yet implemented with kokkos* + This option is not yet available. + *Fix langevin omega is not yet implemented with kokkos* This option is not yet available. diff --git a/doc/rst/Errors_warnings.rst b/doc/rst/Errors_warnings.rst index 21f11607bf..ad5323c6ad 100644 --- a/doc/rst/Errors_warnings.rst +++ b/doc/rst/Errors_warnings.rst @@ -40,6 +40,10 @@ Doc page with :doc:`ERROR messages ` *Angle style in data file differs from currently defined angle style* Self-explanatory. +*Angles are defined but no angle style is set* + The topology contains angles, but there are no angle forces computed + since there was no angle\_style command. + *Atom style in data file differs from currently defined atom style* Self-explanatory. @@ -61,6 +65,10 @@ Doc page with :doc:`ERROR messages ` *Bond style in data file differs from currently defined bond style* Self-explanatory. +*Bonds are defined but no bond style is set* + The topology contains bonds, but there are no bond forces computed + since there was no bond\_style command. + *Bond/angle/dihedral extent > half of periodic box length* This is a restriction because LAMMPS can be confused about which image of an atom in the bonded interaction is the correct one to use. @@ -153,6 +161,10 @@ Doc page with :doc:`ERROR messages ` *Dihedral style in data file differs from currently defined dihedral style* Self-explanatory. +*Dihedrals are defined but no dihedral style is set* + The topology contains dihedrals, but there are no dihedral forces computed + since there was no dihedral\_style command. + *Dump dcd/xtc timestamp may be wrong with fix dt/reset* If the fix changes the timestep, the dump dcd file will not reflect the change. @@ -203,6 +215,9 @@ Doc page with :doc:`ERROR messages ` pair style, an eam pair style, or no "single" function for the pair style. +*Fix langevin gjf using random gaussians is not implemented with kokkos* +This will most likely cause errors in kinetic fluctuations. + *Fix property/atom mol or charge w/out ghost communication* A model typically needs these properties defined for ghost atoms. @@ -281,6 +296,10 @@ Doc page with :doc:`ERROR messages ` *Improper style in data file differs from currently defined improper style* Self-explanatory. +*Impropers are defined but no improper style is set* + The topology contains impropers, but there are no improper forces computed + since there was no improper\_style command. + *Inconsistent image flags* The image flags for a pair on bonded atoms appear to be inconsistent. Inconsistent means that when the coordinates of the two atoms are @@ -298,6 +317,10 @@ Doc page with :doc:`ERROR messages ` periodic boundaries and connect two atoms with the same image flag. +*Increasing communication cutoff for GPU style* + The pair style has increased the communication cutoff to be consistent with + the communication cutoff requirements for this pair style when run on the GPU. + *KIM Model does not provide 'energy'; Potential energy will be zero* Self-explanatory. @@ -327,6 +350,27 @@ Doc page with :doc:`ERROR messages ` are not consecutively numbered, or if no atom map is defined. See the atom\_modify command for details about atom maps. +*Likewise 1-2 special neighbor interactions != 1.0* + The topology contains bonds, but there is no bond style defined + and a 1-2 special neighbor scaling factor was not 1.0. This + means that pair style interactions may have scaled or missing + pairs in the neighbor list in expectation of interactions for + those pairs being computed from the bond style. + +*Likewise 1-3 special neighbor interactions != 1.0* + The topology contains angles, but there is no angle style defined + and a 1-3 special neighbor scaling factor was not 1.0. This + means that pair style interactions may have scaled or missing + pairs in the neighbor list in expectation of interactions for + those pairs being computed from the angle style. + +*Likewise 1-4 special neighbor interactions != 1.0* + The topology contains dihedrals, but there is no dihedral style defined + and a 1-4 special neighbor scaling factor was not 1.0. This + means that pair style interactions may have scaled or missing + pairs in the neighbor list in expectation of interactions for + those pairs being computed from the dihedral style. + *Lost atoms via change\_box: original %ld current %ld* The command options you have used caused atoms to be lost. diff --git a/doc/rst/Examples.rst b/doc/rst/Examples.rst index 9dc63ef21b..a223939d5a 100644 --- a/doc/rst/Examples.rst +++ b/doc/rst/Examples.rst @@ -208,6 +208,8 @@ Uppercase directories +------------+--------------------------------------------------------------------------------------------------+ | SPIN | examples for features of the SPIN package | +------------+--------------------------------------------------------------------------------------------------+ +| UNITS | examples that run the same simulation in lj, real, metal units | ++------------+--------------------------------------------------------------------------------------------------+ | USER | examples for USER packages and USER-contributed commands | +------------+--------------------------------------------------------------------------------------------------+ | VISCOSITY | compute viscosity via several methods | diff --git a/doc/rst/Howto_chunk.rst b/doc/rst/Howto_chunk.rst index c297fc1793..337a24c9b7 100644 --- a/doc/rst/Howto_chunk.rst +++ b/doc/rst/Howto_chunk.rst @@ -132,7 +132,9 @@ The :doc:`compute chunk/spread/atom ` command spreads per-chunk values to each atom in the chunk, producing per-atom values as its output. This can be useful for outputting per-chunk values to a per-atom :doc:`dump file `. Or for using an atom's -associated chunk value in an :doc:`atom-style variable `. +associated chunk value in an :doc:`atom-style variable `. Or +as input to the :doc:`fix ave/chunk ` command to +spatially average per-chunk values calculated by a per-chunk compute. The :doc:`compute reduce/chunk ` command reduces a peratom value across the atoms in each chunk to produce a value per @@ -195,14 +197,22 @@ velocity: compute size all property/chunk cc1 count fix 1 all ave/histo 100 1 100 0 20 20 c_size mode vector ave running beyond ignore file tmp.histo -(6) An example of using a per-chunk value to apply per-atom forces to +(6) An example for using a per-chunk value to apply per-atom forces to compress individual polymer chains (molecules) in a mixture, is explained on the :doc:`compute chunk/spread/atom ` command doc page. -(7) An example of using one set of per-chunk values for molecule +(7) An example for using one set of per-chunk values for molecule chunks, to create a 2nd set of micelle-scale chunks (clustered molecules, due to hydrophobicity), is explained on the :doc:`compute chunk/reduce ` command doc page. +(8) An example for using one set of per-chunk values (dipole moment +vectors) for molecule chunks, spreading the values to each atom in +each chunk, then defining a second set of chunks as spatial bins, and +using the :doc:`fix ave/chunk ` command to calculate an +average dipole moment vector for each bin. This example is explained +on the :doc:`compute chunk/spread/atom ` +command doc page. + .. _lws: http://lammps.sandia.gov .. _ld: Manual.html diff --git a/doc/rst/Howto_kappa.rst b/doc/rst/Howto_kappa.rst deleted file mode 100644 index d7fb3b3ee2..0000000000 --- a/doc/rst/Howto_kappa.rst +++ /dev/null @@ -1,86 +0,0 @@ -Calculate thermal conductivity -============================== - -The thermal conductivity kappa of a material can be measured in at -least 4 ways using various options in LAMMPS. See the examples/KAPPA -directory for scripts that implement the 4 methods discussed here for -a simple Lennard-Jones fluid model. Also, see the :doc:`Howto viscosity ` doc page for an analogous discussion -for viscosity. - -The thermal conductivity tensor kappa is a measure of the propensity -of a material to transmit heat energy in a diffusive manner as given -by Fourier's law - -J = -kappa grad(T) - -where J is the heat flux in units of energy per area per time and -grad(T) is the spatial gradient of temperature. The thermal -conductivity thus has units of energy per distance per time per degree -K and is often approximated as an isotropic quantity, i.e. as a -scalar. - -The first method is to setup two thermostatted regions at opposite -ends of a simulation box, or one in the middle and one at the end of a -periodic box. By holding the two regions at different temperatures -with a :doc:`thermostatting fix `, the energy added to -the hot region should equal the energy subtracted from the cold region -and be proportional to the heat flux moving between the regions. See -the papers by :ref:`Ikeshoji and Hafskjold ` and -:ref:`Wirnsberger et al ` for details of this idea. Note -that thermostatting fixes such as :doc:`fix nvt `, :doc:`fix langevin `, and :doc:`fix temp/rescale ` store the cumulative energy they -add/subtract. - -Alternatively, as a second method, the :doc:`fix heat ` or -:doc:`fix ehex ` commands can be used in place of thermostats -on each of two regions to add/subtract specified amounts of energy to -both regions. In both cases, the resulting temperatures of the two -regions can be monitored with the "compute temp/region" command and -the temperature profile of the intermediate region can be monitored -with the :doc:`fix ave/chunk ` and :doc:`compute ke/atom ` commands. - -The third method is to perform a reverse non-equilibrium MD simulation -using the :doc:`fix thermal/conductivity ` -command which implements the rNEMD algorithm of Muller-Plathe. -Kinetic energy is swapped between atoms in two different layers of the -simulation box. This induces a temperature gradient between the two -layers which can be monitored with the :doc:`fix ave/chunk ` and :doc:`compute ke/atom ` commands. The fix tallies the -cumulative energy transfer that it performs. See the :doc:`fix thermal/conductivity ` command for -details. - -The fourth method is based on the Green-Kubo (GK) formula which -relates the ensemble average of the auto-correlation of the heat flux -to kappa. The heat flux can be calculated from the fluctuations of -per-atom potential and kinetic energies and per-atom stress tensor in -a steady-state equilibrated simulation. This is in contrast to the -two preceding non-equilibrium methods, where energy flows continuously -between hot and cold regions of the simulation box. - -The :doc:`compute heat/flux ` command can calculate -the needed heat flux and describes how to implement the Green\_Kubo -formalism using additional LAMMPS commands, such as the :doc:`fix ave/correlate ` command to calculate the needed -auto-correlation. See the doc page for the :doc:`compute heat/flux ` command for an example input script -that calculates the thermal conductivity of solid Ar via the GK -formalism. - - ----------- - - -.. _howto-Ikeshoji: - - - -**(Ikeshoji)** Ikeshoji and Hafskjold, Molecular Physics, 81, 251-261 -(1994). - -.. _howto-Wirnsberger: - - - -**(Wirnsberger)** Wirnsberger, Frenkel, and Dellago, J Chem Phys, 143, 124104 -(2015). - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/Howto_spins.rst b/doc/rst/Howto_spins.rst index c1186bae97..eb1cf1e956 100644 --- a/doc/rst/Howto_spins.rst +++ b/doc/rst/Howto_spins.rst @@ -34,15 +34,15 @@ The magnetic Gilbert damping can also be applied using :doc:`fix langevin/spin < the thermal energy of the Langevin thermostat, or to perform a relaxation of the magnetic configuration toward an equilibrium state. -The command :doc:`fix setforce/spin ` allows to set the -components of the magnetic precession vectors (while erasing and -replacing the previously computed magnetic precession vectors on -the atom). -This command can be used to freeze the magnetic moment of certain +The command :doc:`fix setforce/spin ` allows to set the +components of the magnetic precession vectors (while erasing and +replacing the previously computed magnetic precession vectors on +the atom). +This command can be used to freeze the magnetic moment of certain atoms in the simulation by zeroing their precession vector. The command :doc:`fix nve/spin ` can be used to -perform a symplectic integration of the combined dynamics of spins +perform a symplectic integration of the combined dynamics of spins and atomic motions. The minimization style :doc:`min/spin ` can be applied diff --git a/doc/rst/Howto_viscosity.rst b/doc/rst/Howto_viscosity.rst index b86dd38591..0b74784534 100644 --- a/doc/rst/Howto_viscosity.rst +++ b/doc/rst/Howto_viscosity.rst @@ -77,7 +77,7 @@ liquid Ar via the GK formalism: # convert from LAMMPS real units to SI - variable kB equal 1.3806504e-23 # [J/K/** Boltzmann + variable kB equal 1.3806504e-23 # [J/K] Boltzmann variable atm2Pa equal 101325.0 variable A2m equal 1.0e-10 variable fs2s equal 1.0e-15 diff --git a/doc/rst/Manual.rst b/doc/rst/Manual.rst index c71dde9b9a..c5485271e1 100644 --- a/doc/rst/Manual.rst +++ b/doc/rst/Manual.rst @@ -1,8 +1,8 @@ LAMMPS Documentation #################### -7 Aug 2019 version -****************** +30 Oct 2019 version +******************* :doc:`What is a LAMMPS version? ` diff --git a/doc/rst/Packages_details.rst b/doc/rst/Packages_details.rst index 6c876526e4..a8274d5403 100644 --- a/doc/rst/Packages_details.rst +++ b/doc/rst/Packages_details.rst @@ -1960,11 +1960,12 @@ USER-PHONON package A :doc:`fix phonon ` command that calculates dynamical matrices, which can then be used to compute phonon dispersion relations, directly from molecular dynamics simulations. -And a "dynamical\_matrix" command to compute the dynamical matrix -from finite differences. +And a :doc:`dynamical\_matrix ` as well as a +:doc:`third\_order ` command to compute the dynamical matrix +and third order tensor from finite differences. **Authors:** Ling-Ti Kong (Shanghai Jiao Tong University) for "fix phonon" -and Charlie Sievers (UC Davis) for "dynamical\_matrix" +and Charlie Sievers (UC Davis) for "dynamical\_matrix" and "third\_order" **Supporting info:** @@ -1972,6 +1973,7 @@ and Charlie Sievers (UC Davis) for "dynamical\_matrix" * src/USER-PHONON/README * :doc:`fix phonon ` * :doc:`dynamical\_matrix ` +* :doc:`third\_order ` * examples/USER/phonon diff --git a/doc/rst/Python_shlib.rst b/doc/rst/Python_shlib.rst deleted file mode 100644 index 9dd1fbde6d..0000000000 --- a/doc/rst/Python_shlib.rst +++ /dev/null @@ -1,86 +0,0 @@ -Build LAMMPS as a shared library -================================ - -Build LAMMPS as a shared library using make -------------------------------------------- - -Instructions on how to build LAMMPS as a shared library are given on -the :doc:`Build\_basics ` doc page. A shared library is -one that is dynamically loadable, which is what Python requires to -wrap LAMMPS. On Linux this is a library file that ends in ".so", not -".a". - -From the src directory, type - - -.. parsed-literal:: - - make foo mode=shlib - -where foo is the machine target name, such as mpi or serial. -This should create the file liblammps\_foo.so in the src directory, as -well as a soft link liblammps.so, which is what the Python wrapper will -load by default. Note that if you are building multiple machine -versions of the shared library, the soft link is always set to the -most recently built version. - -.. note:: - - If you are building LAMMPS with an MPI or FFT library or other - auxiliary libraries (used by various packages), then all of these - extra libraries must also be shared libraries. If the LAMMPS - shared-library build fails with an error complaining about this, see - the :doc:`Build\_basics ` doc page. - -Build LAMMPS as a shared library using CMake --------------------------------------------- - -When using CMake the following two options are necessary to generate the LAMMPS -shared library: - - -.. parsed-literal:: - - -D BUILD_LIB=on # enable building LAMMPS as a library - -D BUILD_SHARED_LIBS=on # enable building of LAMMPS shared library (both options are needed!) - -What this does is create a liblammps.so which contains the majority of LAMMPS -code. The generated lmp binary also dynamically links to this library. This -means that either this liblammps.so file has to be in the same directory, a system -library path (e.g. /usr/lib64/) or in the LD\_LIBRARY\_PATH. - -If you want to use the shared library with Python the recommended way is to create a virtualenv and use it as -CMAKE\_INSTALL\_PREFIX. - - -.. parsed-literal:: - - # create virtualenv - virtualenv --python=$(which python3) myenv3 - source myenv3/bin/activate - - # build library - mkdir build - cd build - cmake -D PKG_PYTHON=on -D BUILD_LIB=on -D BUILD_SHARED_LIBS=on -D CMAKE_INSTALL_PREFIX=$VIRTUAL_ENV ../cmake - make -j 4 - - # install into prefix - make install - -This will also install the Python module into your virtualenv. Since virtualenv -doesn't change your LD\_LIBRARY\_PATH, you still need to add its lib64 folder to -it, which contains the installed liblammps.so. - - -.. parsed-literal:: - - export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib64:$LD_LIBRARY_PATH - -Starting Python outside (!) of your build directory, but with the virtualenv -enabled and with the LD\_LIBRARY\_PATH set gives you access to LAMMPS via Python. - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/Run_options.rst b/doc/rst/Run_options.rst index 40fb8474d3..1e0091f057 100644 --- a/doc/rst/Run_options.rst +++ b/doc/rst/Run_options.rst @@ -142,12 +142,13 @@ are intended for computational work like running LAMMPS. By default Ng = 1 and Ns is not set. Depending on which flavor of MPI you are running, LAMMPS will look for -one of these 3 environment variables +one of these 4 environment variables .. parsed-literal:: SLURM_LOCALID (various MPI variants compiled with SLURM support) + MPT_LRANK (HPE MPI) MV2_COMM_WORLD_LOCAL_RANK (Mvapich) OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI) diff --git a/doc/rst/Speed_bench.rst b/doc/rst/Speed_bench.rst deleted file mode 100644 index 8de5ee5d07..0000000000 --- a/doc/rst/Speed_bench.rst +++ /dev/null @@ -1,82 +0,0 @@ -Benchmarks -========== - -Current LAMMPS performance is discussed on the `Benchmarks page `_ of the `LAMMPS website `_ -where timings and parallel efficiency are listed. The page has -several sections, which are briefly described below: - -* CPU performance on 5 standard problems, strong and weak scaling -* GPU and Xeon Phi performance on same and related problems -* Comparison of cost of interatomic potentials -* Performance of huge, billion-atom problems - -The 5 standard problems are as follow: - -#. LJ = atomic fluid, Lennard-Jones potential with 2.5 sigma cutoff (55 - neighbors per atom), NVE integration -#. Chain = bead-spring polymer melt of 100-mer chains, FENE bonds and LJ - pairwise interactions with a 2\^(1/6) sigma cutoff (5 neighbors per - atom), NVE integration -#. EAM = metallic solid, Cu EAM potential with 4.95 Angstrom cutoff (45 - neighbors per atom), NVE integration -#. Chute = granular chute flow, frictional history potential with 1.1 - sigma cutoff (7 neighbors per atom), NVE integration -#. Rhodo = rhodopsin protein in solvated lipid bilayer, CHARMM force - field with a 10 Angstrom LJ cutoff (440 neighbors per atom), - particle-particle particle-mesh (PPPM) for long-range Coulombics, NPT - integration - - -Input files for these 5 problems are provided in the bench directory -of the LAMMPS distribution. Each has 32,000 atoms and runs for 100 -timesteps. The size of the problem (number of atoms) can be varied -using command-line switches as described in the bench/README file. -This is an easy way to test performance and either strong or weak -scalability on your machine. - -The bench directory includes a few log.\* files that show performance -of these 5 problems on 1 or 4 cores of Linux desktop. The bench/FERMI -and bench/KEPLER dirs have input files and scripts and instructions -for running the same (or similar) problems using OpenMP or GPU or Xeon -Phi acceleration options. See the README files in those dirs and the -:doc:`Speed packages ` doc pages for instructions on how -to build LAMMPS and run on that kind of hardware. - -The bench/POTENTIALS directory has input files which correspond to the -table of results on the -`Potentials `_ section of -the Benchmarks web page. So you can also run those test problems on -your machine. - -The `billion-atom `_ section -of the Benchmarks web page has performance data for very large -benchmark runs of simple Lennard-Jones (LJ) models, which use the -bench/in.lj input script. - - ----------- - - -For all the benchmarks, a useful metric is the CPU cost per atom per -timestep. Since performance scales roughly linearly with problem size -and timesteps for all LAMMPS models (i.e. interatomic or coarse-grained -potentials), the run time of any problem using the same model (atom -style, force field, cutoff, etc) can then be estimated. - -Performance on a parallel machine can also be predicted from one-core -or one-node timings if the parallel efficiency can be estimated. The -communication bandwidth and latency of a particular parallel machine -affects the efficiency. On most machines LAMMPS will give a parallel -efficiency on these benchmarks above 50% so long as the number of -atoms/core is a few 100 or greater, and closer to 100% for large -numbers of atoms/core. This is for all-MPI mode with one MPI task per -core. For nodes with accelerator options or hardware (OpenMP, GPU, -Phi), you should first measure single node performance. Then you can -estimate parallel performance for multi-node runs using the same logic -as for all-MPI mode, except that now you will typically need many more -atoms/node to achieve good scalability. - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/Speed_kokkos.rst b/doc/rst/Speed_kokkos.rst index 4ee362b6dd..6d3828ee68 100644 --- a/doc/rst/Speed_kokkos.rst +++ b/doc/rst/Speed_kokkos.rst @@ -44,13 +44,13 @@ compatible with specific hardware. .. note:: - Kokkos with CUDA currently implicitly assumes that the MPI library - is CUDA-aware. This is not always the case, especially when using - pre-compiled MPI libraries provided by a Linux distribution. This is not - a problem when using only a single GPU with a single MPI rank. When - running with multiple MPI ranks, you may see segmentation faults without - CUDA-aware MPI support. These can be avoided by adding the flags :doc:`-pk kokkos cuda/aware off ` to the LAMMPS command line or by - using the command :doc:`package kokkos cuda/aware off ` in the + Kokkos with CUDA currently implicitly assumes that the MPI library + is CUDA-aware. This is not always the case, especially when using + pre-compiled MPI libraries provided by a Linux distribution. This is not + a problem when using only a single GPU with a single MPI rank. When + running with multiple MPI ranks, you may see segmentation faults without + CUDA-aware MPI support. These can be avoided by adding the flags :doc:`-pk kokkos cuda/aware off ` to the LAMMPS command line or by + using the command :doc:`package kokkos cuda/aware off ` in the input file. **Building LAMMPS with the KOKKOS package:** @@ -116,9 +116,9 @@ below. .. note:: - Use the "-pk kokkos" :doc:`command-line switch ` to - change the default :doc:`package kokkos ` options. See its doc - page for details and default settings. Experimenting with its options + Use the "-pk kokkos" :doc:`command-line switch ` to + change the default :doc:`package kokkos ` options. See its doc + page for details and default settings. Experimenting with its options can provide a speed-up for specific calculations. For example: @@ -200,14 +200,14 @@ threads/task as Nt. The product of these two values should be N, i.e. .. note:: - The default for the :doc:`package kokkos ` command when - running on KNL is to use "half" neighbor lists and set the Newton flag - to "on" for both pairwise and bonded interactions. This will typically - be best for many-body potentials. For simpler pair-wise potentials, it - may be faster to use a "full" neighbor list with Newton flag to "off". - Use the "-pk kokkos" :doc:`command-line switch ` to change - the default :doc:`package kokkos ` options. See its doc page for - details and default settings. Experimenting with its options can provide + The default for the :doc:`package kokkos ` command when + running on KNL is to use "half" neighbor lists and set the Newton flag + to "on" for both pairwise and bonded interactions. This will typically + be best for many-body potentials. For simpler pair-wise potentials, it + may be faster to use a "full" neighbor list with Newton flag to "off". + Use the "-pk kokkos" :doc:`command-line switch ` to change + the default :doc:`package kokkos ` options. See its doc page for + details and default settings. Experimenting with its options can provide a speed-up for specific calculations. For example: @@ -230,19 +230,19 @@ threads/task as Nt. The product of these two values should be N, i.e. **Running on GPUs:** -Use the "-k" :doc:`command-line switch ` to specify the -number of GPUs per node. Typically the -np setting of the mpirun command -should set the number of MPI tasks/node to be equal to the number of -physical GPUs on the node. You can assign multiple MPI tasks to the same -GPU with the KOKKOS package, but this is usually only faster if some -portions of the input script have not been ported to use Kokkos. In this -case, also packing/unpacking communication buffers on the host may give -speedup (see the KOKKOS :doc:`package ` command). Using CUDA MPS +Use the "-k" :doc:`command-line switch ` to specify the +number of GPUs per node. Typically the -np setting of the mpirun command +should set the number of MPI tasks/node to be equal to the number of +physical GPUs on the node. You can assign multiple MPI tasks to the same +GPU with the KOKKOS package, but this is usually only faster if some +portions of the input script have not been ported to use Kokkos. In this +case, also packing/unpacking communication buffers on the host may give +speedup (see the KOKKOS :doc:`package ` command). Using CUDA MPS is recommended in this scenario. -Using a CUDA-aware MPI library is highly recommended. CUDA-aware MPI use can be -avoided by using :doc:`-pk kokkos cuda/aware no `. As above for -multi-core CPUs (and no GPU), if N is the number of physical cores/node, +Using a CUDA-aware MPI library is highly recommended. CUDA-aware MPI use can be +avoided by using :doc:`-pk kokkos cuda/aware no `. As above for +multi-core CPUs (and no GPU), if N is the number of physical cores/node, then the number of MPI tasks/node should not exceed N. @@ -261,17 +261,17 @@ one or more nodes, each with two GPUs: .. note:: - The default for the :doc:`package kokkos ` command when - running on GPUs is to use "full" neighbor lists and set the Newton flag - to "off" for both pairwise and bonded interactions, along with threaded - communication. When running on Maxwell or Kepler GPUs, this will - typically be best. For Pascal GPUs, using "half" neighbor lists and - setting the Newton flag to "on" may be faster. For many pair styles, - setting the neighbor binsize equal to twice the CPU default value will - give speedup, which is the default when running on GPUs. Use the "-pk - kokkos" :doc:`command-line switch ` to change the default - :doc:`package kokkos ` options. See its doc page for details and - default settings. Experimenting with its options can provide a speed-up + The default for the :doc:`package kokkos ` command when + running on GPUs is to use "full" neighbor lists and set the Newton flag + to "off" for both pairwise and bonded interactions, along with threaded + communication. When running on Maxwell or Kepler GPUs, this will + typically be best. For Pascal GPUs, using "half" neighbor lists and + setting the Newton flag to "on" may be faster. For many pair styles, + setting the neighbor binsize equal to twice the CPU default value will + give speedup, which is the default when running on GPUs. Use the "-pk + kokkos" :doc:`command-line switch ` to change the default + :doc:`package kokkos ` options. See its doc page for details and + default settings. Experimenting with its options can provide a speed-up for specific calculations. For example: diff --git a/doc/rst/Tools.rst b/doc/rst/Tools.rst index 60baacfc7e..baee955201 100644 --- a/doc/rst/Tools.rst +++ b/doc/rst/Tools.rst @@ -62,15 +62,17 @@ Post-processing tools +--------------------------+----------------------------+------------------------+--------------------------+-------------------------------+-----------------------------+ | :ref:`lmp2arc ` | :ref:`lmp2cfg ` | :ref:`matlab ` | :ref:`phonon ` | :ref:`pymol\_asphere ` | :ref:`python ` | +--------------------------+----------------------------+------------------------+--------------------------+-------------------------------+-----------------------------+ -| :ref:`reax ` | :ref:`smd ` | :ref:`spin ` | :ref:`xmgrace ` | | | +| :ref:`reax ` | :ref:`replica ` | :ref:`smd ` | :ref:`spin ` | :ref:`xmgrace ` | | +--------------------------+----------------------------+------------------------+--------------------------+-------------------------------+-----------------------------+ Miscellaneous tools =================== -+--------------------------+----------------------+-------------------+--------------------+------------------+ -| :ref:`doxygen ` | :ref:`emacs ` | :ref:`i-pi ` | :ref:`kate ` | :ref:`vim ` | -+--------------------------+----------------------+-------------------+--------------------+------------------+ ++--------------------------+----------------------+-------------------+--------------------+---------------------------------------+ +| :ref:`doxygen ` | :ref:`emacs ` | :ref:`i-pi ` | :ref:`kate ` | :ref:`singularity ` | ++--------------------------+----------------------+-------------------+--------------------+---------------------------------------+ +| :ref:`vim ` | | | | | ++--------------------------+----------------------+-------------------+--------------------+---------------------------------------+ ---------- @@ -618,6 +620,26 @@ README for more info on Pizza.py and how to use these scripts. ---------- +.. _replica: + +replica tool +-------------------------- + +The tools/replica directory contains the reorder\_remd\_traj python script which +can be used to reorder the replica trajectories (resulting from the use of the +temper command) according to temperature. This will produce discontinuous +trajectories with all frames at the same temperature in each trajectory. +Additional options can be used to calculate the canonical configurational +log-weight for each frame at each temperature using the pymbar package. See +the README.md file for further details. Try out the peptide example provided. + +This tool was written by (and is maintained by) Tanmoy Sanyal, +while at the Shell lab at UC Santa Barbara. (tanmoy dot 7989 at gmail.com) + + +---------- + + .. _reax\_tool: reax tool @@ -661,19 +683,33 @@ spin tool -------------------- The spin sub-directory contains a C file interpolate.c which can -be compiled and used to perform a cubic polynomial interpolation of +be compiled and used to perform a cubic polynomial interpolation of the MEP following a GNEB calculation. See the README file in tools/spin/interpolate\_gneb for more details. This tool was written by the SPIN package author, Julien -Tranchida at Sandia National Labs (jtranch at sandia.gov, and by Aleksei +Tranchida at Sandia National Labs (jtranch at sandia.gov, and by Aleksei Ivanov, at University of Iceland (ali5 at hi.is). ---------- +.. _singularity\_tool: + +singularity tool +---------------------------------------- + +The singularity sub-directory contains container definitions files +that can be used to build container images for building and testing +LAMMPS on specific OS variants using the `Singularity `_ +container software. Contributions for additional variants are welcome. + + +---------- + + .. _vim: vim tool diff --git a/doc/rst/angle_hybrid.rst b/doc/rst/angle_hybrid.rst deleted file mode 100644 index e31df56e72..0000000000 --- a/doc/rst/angle_hybrid.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. index:: angle\_style hybrid - -angle\_style hybrid command -=========================== - -Syntax -"""""" - - -.. parsed-literal:: - - angle_style hybrid style1 style2 ... - -* style1,style2 = list of one or more angle styles - -Examples -"""""""" - - -.. parsed-literal:: - - angle_style hybrid harmonic cosine - angle_coeff 1 harmonic 80.0 30.0 - angle_coeff 2\* cosine 50.0 - -Description -""""""""""" - -The *hybrid* style enables the use of multiple angle styles in one -simulation. An angle style is assigned to each angle type. For -example, angles in a polymer flow (of angle type 1) could be computed -with a *harmonic* potential and angles in the wall boundary (of angle -type 2) could be computed with a *cosine* potential. The assignment -of angle type to style is made via the :doc:`angle\_coeff ` -command or in the data file. - -In the angle\_coeff commands, the name of an angle style must be added -after the angle type, with the remaining coefficients being those -appropriate to that style. In the example above, the 2 angle\_coeff -commands set angles of angle type 1 to be computed with a *harmonic* -potential with coefficients 80.0, 30.0 for K, theta0. All other angle -types (2-N) are computed with a *cosine* potential with coefficient -50.0 for K. - -If angle coefficients are specified in the data file read via the -:doc:`read\_data ` command, then the same rule applies. -E.g. "harmonic" or "cosine", must be added after the angle type, for each -line in the "Angle Coeffs" section, e.g. - - -.. parsed-literal:: - - Angle Coeffs - - 1 harmonic 80.0 30.0 - 2 cosine 50.0 - ... - -If *class2* is one of the angle hybrid styles, the same rule holds for -specifying additional BondBond (and BondAngle) coefficients either via -the input script or in the data file. I.e. *class2* must be added to -each line after the angle type. For lines in the BondBond (or -BondAngle) section of the data file for angle types that are not -*class2*\ , you must use an angle style of *skip* as a placeholder, e.g. - - -.. parsed-literal:: - - BondBond Coeffs - - 1 skip - 2 class2 3.6512 1.0119 1.0119 - ... - -Note that it is not necessary to use the angle style *skip* in the -input script, since BondBond (or BondAngle) coefficients need not be -specified at all for angle types that are not *class2*\ . - -An angle style of *none* with no additional coefficients can be used -in place of an angle style, either in a input script angle\_coeff -command or in the data file, if you desire to turn off interactions -for specific angle types. - - ----------- - - -Restrictions -"""""""""""" - - -This angle style can only be used if LAMMPS was built with the -MOLECULE package. See the :doc:`Build package ` doc page -for more info. - -Unlike other angle styles, the hybrid angle style does not store angle -coefficient info for individual sub-styles in a :doc:`binary restart files `. Thus when restarting a simulation from a restart -file, you need to re-specify angle\_coeff commands. - -Related commands -"""""""""""""""" - -:doc:`angle\_coeff ` - -**Default:** none - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/comm_modify.rst b/doc/rst/comm_modify.rst index 395a1b2603..9375bd60c9 100644 --- a/doc/rst/comm_modify.rst +++ b/doc/rst/comm_modify.rst @@ -50,11 +50,12 @@ processors and stored as properties of ghost atoms. .. note:: These options apply to the currently defined comm style. When - you specify a :doc:`comm\_style ` command, all communication - settings are restored to their default values, including those + you specify a :doc:`comm\_style ` or + :doc:`read\_restart ` command, all communication settings + are restored to their default or stored values, including those previously reset by a comm\_modify command. Thus if your input script - specifies a comm\_style command, you should use the comm\_modify command - after it. + specifies a comm\_style or read\_restart command, you should use the + comm\_modify command after it. The *mode* keyword determines whether a single or multiple cutoff distances are used to determine which atoms to communicate. diff --git a/doc/rst/commands_list.rst b/doc/rst/commands_list.rst index c0bdcbfb18..2eaa78d59c 100644 --- a/doc/rst/commands_list.rst +++ b/doc/rst/commands_list.rst @@ -108,6 +108,7 @@ Commands thermo thermo_modify thermo_style + third_order timer timestep uncompute diff --git a/doc/rst/compute_angle.rst b/doc/rst/compute_angle.rst deleted file mode 100644 index 2b025ea217..0000000000 --- a/doc/rst/compute_angle.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. index:: compute angle - -compute angle command -===================== - -Syntax -"""""" - - -.. parsed-literal:: - - compute ID group-ID angle - -* ID, group-ID are documented in :doc:`compute ` command -* angle = style name of this compute command - -Examples -"""""""" - - -.. parsed-literal:: - - compute 1 all angle - -Description -""""""""""" - -Define a computation that extracts the angle energy calculated by each -of the angle sub-styles used in the "angle\_style -hybrid" angle\_hybrid.html command. These values are made accessible -for output or further processing by other commands. The group -specified for this command is ignored. - -This compute is useful when using :doc:`angle\_style hybrid ` if you want to know the portion of the total -energy contributed by one or more of the hybrid sub-styles. - -**Output info:** - -This compute calculates a global vector of length N where N is the -number of sub\_styles defined by the :doc:`angle\_style hybrid ` command, which can be accessed by indices -1-N. These values can be used by any command that uses global scalar -or vector values from a compute as input. See the :doc:`Howto output ` doc page for an overview of LAMMPS output -options. - -The vector values are "extensive" and will be in energy -:doc:`units `. - -Restrictions -"""""""""""" - none - -Related commands -"""""""""""""""" - -:doc:`compute pe `, :doc:`compute pair ` - -**Default:** none - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/compute_bond_local.rst b/doc/rst/compute_bond_local.rst index 20bcfa08ba..1bca2ff439 100644 --- a/doc/rst/compute_bond_local.rst +++ b/doc/rst/compute_bond_local.rst @@ -14,7 +14,7 @@ Syntax * ID, group-ID are documented in :doc:`compute ` command * bond/local = style name of this compute command * one or more values may be appended -* value = *dist* or *engpot* or *force* or *engvib* or *engrot* or *engtrans* or *omega* or *velvib* or *v\_name* +* value = *dist* or *engpot* or *force* or *fx* or *fy* or *fz* or *engvib* or *engrot* or *engtrans* or *omega* or *velvib* or *v\_name* .. parsed-literal:: @@ -22,6 +22,7 @@ Syntax *engpot* = bond potential energy *force* = bond force + *fx*\ ,\ *fy*\ ,\ *fz* = components of bond force *engvib* = bond kinetic energy of vibration *engrot* = bond kinetic energy of rotation *engtrans* = bond kinetic energy of translation @@ -51,6 +52,8 @@ Examples compute 1 all bond/local engpot compute 1 all bond/local dist engpot force + compute 1 all bond/local dist fx fy fz + compute 1 all angle/local dist v_distsq set dist d Description @@ -73,6 +76,9 @@ based on the current separation of the pair of atoms in the bond. The value *force* is the magnitude of the force acting between the pair of atoms in the bond. +The values *fx*\ , *fy*\ , and *fz* are the xyz components of +*force* between the pair of atoms in the bond. + The remaining properties are all computed for motion of the two atoms relative to the center of mass (COM) velocity of the 2 atoms in the bond. diff --git a/doc/rst/compute_chunk_spread_atom.rst b/doc/rst/compute_chunk_spread_atom.rst index 88bf005c2e..7106c6ce0a 100644 --- a/doc/rst/compute_chunk_spread_atom.rst +++ b/doc/rst/compute_chunk_spread_atom.rst @@ -38,9 +38,16 @@ Description """"""""""" Define a calculation that "spreads" one or more per-chunk values to -each atom in the chunk. This can be useful for creating a :doc:`dump file ` where each atom lists info about the chunk it is in, -e.g. for post-processing purposes. It can also be used in :doc:`atom-style variables ` that need info about the chunk each atom is -in. Examples are given below. +each atom in the chunk. This can be useful in several scenarios: + +* For creating a :doc:`dump file ` where each atom lists info about + the chunk it is in, e.g. for post-processing purposes. +* To access chunk value in :doc:`atom-style variables ` that + need info about the chunk each atom is in. +* To use the :doc:`fix ave/chunk ` command to spatially + average per-chunk values calculated by a per-chunk compute. + +Examples are given below. In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom ` command, which assigns each atom to a single chunk (or no chunk). The ID for this command is specified @@ -171,6 +178,33 @@ in the 32000 atom system: ---------- +Here is an example for using one set of chunks, defined for molecules, +to compute the dipole moment vector for each chunk. E.g. for water +molecules. Then spreading those values to each atom in each chunk. +Then defining a second set of chunks based on spatial bins. And +finally, using the :doc:`fix ave/chunk ` command to +calculate an average dipole moment vector per spatial bin. + + +.. parsed-literal:: + + compute cmol all chunk/atom molecule + compute dipole all dipole/chunk cmol + compute spread all chunk/spread/atom cmol c_dipole[1] c_dipole[2] c_dipole[3] + compute cspatial all chunk/atom bin/1d z lower 0.1 units reduced + fix ave all ave/chunk 100 10 1000 cspatial c_spread[\*] + +Note that the :doc:`fix ave/chunk ` command requires +per-atom values as input. That is why the compute chunk/spread/atom +command is used to assign per-chunk values to each atom in the chunk. +If a molecule straddles bin boundaries, each of its atoms contributes +in a weighted manner to the average dipole moment of the spatial bin +it is in. + + +---------- + + **Output info:** This compute calculates a per-atom vector or array, which can be diff --git a/doc/rst/compute_gyration_shape.rst b/doc/rst/compute_gyration_shape.rst index 9090916ea9..68c16f2511 100644 --- a/doc/rst/compute_gyration_shape.rst +++ b/doc/rst/compute_gyration_shape.rst @@ -28,7 +28,7 @@ Description Define a computation that calculates the eigenvalues of the gyration tensor of a group of atoms and three shape parameters. The computation includes all effects -due to atoms passing thru periodic boundaries. +due to atoms passing through periodic boundaries. The three computed shape parameters are the asphericity, b, the acylindricity, c, and the relative shape anisotropy, k: @@ -97,6 +97,12 @@ Related commands **(Theodorou)** Theodorou, Suter, Macromolecules, 18, 1206 (1985). +.. _Mattice: + + + +**(Mattice)** Mattice, Suter, Conformational Theory of Large Molecules, Wiley, New York, 1994. + .. _lws: http://lammps.sandia.gov .. _ld: Manual.html diff --git a/doc/rst/compute_hma.rst b/doc/rst/compute_hma.rst index 48b741bb9b..d8e7a6b31a 100644 --- a/doc/rst/compute_hma.rst +++ b/doc/rst/compute_hma.rst @@ -40,7 +40,7 @@ Description Define a computation that calculates the properties of a solid (potential energy, pressure or heat capacity), using the harmonically-mapped averaging -(HMA) method. +(HMA) method. This command yields much higher precision than the equivalent compute commands (:doc:`compute pe `, :doc:`compute pressure `, etc.) commands during a canonical simulation of an atomic crystal. Specifically, @@ -58,7 +58,7 @@ restricted to simulations in the NVT ensemble. While this compute may be used with any potential in LAMMPS, it will provide inaccurate results for potentials that do not go to 0 at the truncation distance; :doc:`pair\_lj\_smooth\_linear ` and Ewald summation should -work fine, while :doc:`pair\_lj ` will perform poorly unless +work fine, while :doc:`pair\_lj ` will perform poorly unless the potential is shifted (via :doc:`pair\_modify ` shift) or the cutoff is large. Furthermore, computation of the heat capacity with this compute is restricted to those that implement the single\_hessian method in Pair. Implementing single\_hessian in additional pair styles is simple. @@ -70,8 +70,8 @@ the list of pair styles that currently implement pair\_hessian: In this method, the analytically known harmonic behavior of a crystal is removed from the traditional ensemble -averages, which leads to an accurate and precise measurement of the anharmonic contributions without contamination -by noise produced by the already-known harmonic behavior. +averages, which leads to an accurate and precise measurement of the anharmonic contributions without contamination +by noise produced by the already-known harmonic behavior. A detailed description of this method can be found in (:ref:`Moustafa `). The potential energy is computed by the formula: @@ -81,8 +81,8 @@ A detailed description of this method can be found in (:ref:`Moustafa ` command) while the atoms are still at their lattice sites (before equilibration). -The temp-ID specified with compute hma command should be same as the fix-ID of Nose-Hoover (:doc:`fix nvt `) or -Berendsen (:doc:`fix temp/berendsen `) thermostat used for the simulation. While using this command, Langevin thermostat -(:doc:`fix langevin `) +The temp-ID specified with compute hma command should be same as the fix-ID of Nose-Hoover (:doc:`fix nvt `) or +Berendsen (:doc:`fix temp/berendsen `) thermostat used for the simulation. While using this command, Langevin thermostat +(:doc:`fix langevin `) should be avoided as its extra forces interfere with the HMA implementation. .. note:: - Compute hma command should be used right after the energy minimization, when the atoms are at their lattice sites. + Compute hma command should be used right after the energy minimization, when the atoms are at their lattice sites. The simulation should not be started before this command has been used in the input script. The following example illustrates the placement of this command in the input script: @@ -145,8 +145,8 @@ The following example illustrates the placement of this command in the input scr .. parsed-literal:: - min_style cg - minimize 1e-35 1e-15 50000 500000 + min_style cg + minimize 1e-35 1e-15 50000 500000 compute 1 all hma thermostatid u fix thermostatid all nvt temp 600.0 600.0 100.0 @@ -200,7 +200,7 @@ this compute. -**(Moustafa)** Sabry G. Moustafa, Andrew J. Schultz, and David A. Kofke, *Very fast averaging of thermal properties of crystals by molecular simulation*\ , +**(Moustafa)** Sabry G. Moustafa, Andrew J. Schultz, and David A. Kofke, *Very fast averaging of thermal properties of crystals by molecular simulation*\ , `Phys. Rev. E [92], 043303 (2015) `_ diff --git a/doc/rst/compute_orientorder_atom.rst b/doc/rst/compute_orientorder_atom.rst index 7193660a22..b7a1442a62 100644 --- a/doc/rst/compute_orientorder_atom.rst +++ b/doc/rst/compute_orientorder_atom.rst @@ -21,6 +21,8 @@ Syntax *cutoff* value = distance cutoff *nnn* value = number of nearest neighbors *degrees* values = nlvalues, l1, l2,... + *wl* value = yes or no + *wl/hat* value = yes or no *components* value = ldegree @@ -33,7 +35,8 @@ Examples compute 1 all orientorder/atom compute 1 all orientorder/atom degrees 5 4 6 8 10 12 nnn NULL cutoff 1.5 - compute 1 all orientorder/atom degrees 4 6 components 6 nnn NULL cutoff 3.0 + compute 1 all orientorder/atom wl/hat yes + compute 1 all orientorder/atom components 6 Description """"""""""" @@ -56,7 +59,7 @@ neighbors of the central atom. The angles theta and phi are the standard spherical polar angles defining the direction of the bond vector *rij*\ . The second equation defines *Ql*\ , which is a -rotationally invariant scalar quantity obtained by summing +rotationally invariant non-negative amplitude obtained by summing over all the components of degree *l*\ . The optional keyword *cutoff* defines the distance cutoff @@ -71,14 +74,27 @@ specified distance cutoff are used. The optional keyword *degrees* defines the list of order parameters to be computed. The first argument *nlvalues* is the number of order -parameters. This is followed by that number of integers giving the +parameters. This is followed by that number of non-negative integers giving the degree of each order parameter. Because *Q*\ 2 and all odd-degree order parameters are zero for atoms in cubic crystals (see :ref:`Steinhardt `), the default order parameters are *Q*\ 4, *Q*\ 6, *Q*\ 8, *Q*\ 10, and *Q*\ 12. For the FCC crystal with *nnn* =12, *Q*\ 4 = sqrt(7/3)/8 = 0.19094.... The numerical values of all order parameters up to *Q*\ 12 for a range of commonly encountered -high-symmetry structures are given in Table I of :ref:`Mickel et al. `. +high-symmetry structures are given in Table I of :ref:`Mickel et al. `, and these can be reproduced with this compute + +The optional keyword *wl* will output the third-order invariants *Wl* +(see Eq. 1.4 in :ref:`Steinhardt `) for the same degrees as +for the *Ql* parameters. For the FCC crystal with *nnn* =12, +*W*\ 4 = -sqrt(14/143).(49/4096)/Pi\^1.5 = -0.0006722136... + +The optional keyword *wl/hat* will output the normalized third-order +invariants *Wlhat* (see Eq. 2.2 in :ref:`Steinhardt `) +for the same degrees as for the *Ql* parameters. For the FCC crystal +with *nnn* =12, *W*\ 4hat = -7/3\*sqrt(2/429) = -0.159317...The numerical +values of *Wlhat* for a range of commonly encountered high-symmetry +structures are given in Table I of :ref:`Steinhardt `, and these +can be reproduced with this keyword. The optional keyword *components* will output the components of the normalized complex vector *Ybar\_lm* of degree *ldegree*\ , which must be @@ -89,7 +105,7 @@ particles, as discussed in :ref:`ten Wolde `. The value of *Ql* is set to zero for atoms not in the specified compute group, as well as for atoms that have less than -*nnn* neighbors within the distance cutoff. +*nnn* neighbors within the distance cutoff, unless *nnn* is NULL. The neighbor list needed to compute this quantity is constructed each time the calculation is performed (i.e. each time a snapshot of atoms @@ -117,6 +133,12 @@ This compute calculates a per-atom array with *nlvalues* columns, giving the *Ql* values for each atom, which are real numbers on the range 0 <= *Ql* <= 1. +If the keyword *wl* is set to yes, then the *Wl* values for each +atom will be added to the output array, which are real numbers. + +If the keyword *wl/hat* is set to yes, then the *Wl\_hat* +values for each atom will be added to the output array, which are real numbers. + If the keyword *components* is set, then the real and imaginary parts of each component of (normalized) *Ybar\_lm* will be added to the output array in the following order: Re(*Ybar\_-m*) Im(*Ybar\_-m*) @@ -141,7 +163,8 @@ Default """"""" The option defaults are *cutoff* = pair style cutoff, *nnn* = 12, -*degrees* = 5 4 6 8 10 12 i.e. *Q*\ 4, *Q*\ 6, *Q*\ 8, *Q*\ 10, and *Q*\ 12. +*degrees* = 5 4 6 8 10 12 i.e. *Q*\ 4, *Q*\ 6, *Q*\ 8, *Q*\ 10, and *Q*\ 12, +*wl* = no, *wl/hat* = no, and *components* off ---------- diff --git a/doc/rst/compute_pair_local.rst b/doc/rst/compute_pair_local.rst index 3eab51d2a4..4e61852f2c 100644 --- a/doc/rst/compute_pair_local.rst +++ b/doc/rst/compute_pair_local.rst @@ -76,6 +76,23 @@ which calculate the tangential force between two particles and return its components and magnitude acting on atom I for N = 1,2,3,4. See individual pair styles for details. +When using *pN* with pair style *hybrid*\ , the output will be the Nth +quantity from the sub-style that computes the pairwise interaction +(based on atom types). If that sub-style does not define a *pN*\ , +the output will be 0.0. The maximum allowed N is the maximum number +of quantities provided by any sub-style. + +When using *pN* with pair style *hybrid/overlay* the quantities +from all sub-styles that provide them are concatenated together +into one long list. For example, if there are 3 sub-styles and +2 of them have additional output (with 3 and 4 quantities, +respectively), then 7 values (\ *p1* up to *p7*\ ) are defined. +The values *p1* to *p3* refer to quantities defined by the first +of the two sub-styles. Values *p4* to *p7* refer to quantities +from the second of the two sub-styles. If the referenced *pN* +is not computed for the specific pairwise interaction (based on +atom types), then the output will be 0.0. + The value *dist* will be in distance :doc:`units `. The value *eng* will be in energy :doc:`units `. The values *force*\ , *fx*\ , *fy*\ , and *fz* will be in force :doc:`units `. The values *pN* @@ -140,7 +157,7 @@ options. The output for *dist* will be in distance :doc:`units `. The output for *eng* will be in energy :doc:`units `. The output for *force*\ , *fx*\ , *fy*\ , and *fz* will be in force :doc:`units `. -The outpur for *pN* will be in whatever units the pair style defines. +The output for *pN* will be in whatever units the pair style defines. Restrictions """""""""""" diff --git a/doc/rst/compute_smd_internal_energy.rst b/doc/rst/compute_smd_internal_energy.rst deleted file mode 100644 index b04494a415..0000000000 --- a/doc/rst/compute_smd_internal_energy.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. index:: compute smd/internal/energy - -compute smd/internal/energy command -=================================== - -Syntax -"""""" - - -.. parsed-literal:: - - compute ID group-ID smd/internal/energy - -* ID, group-ID are documented in :doc:`compute ` command -* smd/smd/internal/energy = style name of this compute command - -Examples -"""""""" - - -.. parsed-literal:: - - compute 1 all smd/internal/energy - -Description -""""""""""" - -Define a computation which outputs the per-particle enthalpy, i.e., -the sum of potential energy and heat. - -See `this PDF guide `_ to use Smooth -Mach Dynamics in LAMMPS. - -**Output Info:** - -This compute calculates a per-particle vector, which can be accessed -by any command that uses per-particle values from a compute as input. -See the :doc:`Howto output ` doc page for an overview of -LAMMPS output options. - -The per-particle vector values will be given in :doc:`units ` of energy. - -Restrictions -"""""""""""" - - -This compute is part of the USER-SMD package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` doc page for more info. This compute can -only be used for particles which interact via the updated Lagrangian -or total Lagrangian SPH pair styles. - -**Related Commands:** - -Default -""""""" - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/compute_smd_rho.rst b/doc/rst/compute_smd_rho.rst deleted file mode 100644 index f3c2e1cc47..0000000000 --- a/doc/rst/compute_smd_rho.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. index:: compute smd/rho - -compute smd/rho command -======================= - -Syntax -"""""" - - -.. parsed-literal:: - - compute ID group-ID smd/rho - -* ID, group-ID are documented in :doc:`compute ` command -* smd/rho = style name of this compute command - -Examples -"""""""" - - -.. parsed-literal:: - - compute 1 all smd/rho - -Description -""""""""""" - -Define a computation that calculates the per-particle mass density. -The mass density is the mass of a particle which is constant during -the course of a simulation, divided by its volume, which can change -due to mechanical deformation. - -See `this PDF guide `_ to use Smooth -Mach Dynamics in LAMMPS. - -**Output info:** - -This compute calculates a per-particle vector, which can be accessed -by any command that uses per-particle values from a compute as input. -See the :doc:`Howto output ` doc page for an overview of -LAMMPS output options. - -The per-particle values will be in :doc:`units ` of mass over volume. - -Restrictions -"""""""""""" - - -This compute is part of the USER-SMD package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` doc page for more info. - -Related commands -"""""""""""""""" - -:doc:`compute smd/vol ` - -**Default:** none - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/compute_sna_atom.rst b/doc/rst/compute_sna_atom.rst index 1b0abbe8a2..882fdbb0a0 100644 --- a/doc/rst/compute_sna_atom.rst +++ b/doc/rst/compute_sna_atom.rst @@ -221,7 +221,7 @@ described by the following piece of python code: .. note:: the *diagonal* keyword allowing other possible choices - for the number of bispectrum components was removed in 2019, + for the number of bispectrum components was removed in 2019, since all potentials use the value of 3, corresponding to the above set of bispectrum components. diff --git a/doc/rst/compute_spin.rst b/doc/rst/compute_spin.rst index 14f4b7ffa7..4dd3103d78 100644 --- a/doc/rst/compute_spin.rst +++ b/doc/rst/compute_spin.rst @@ -47,14 +47,14 @@ thermo\_style commands, for example: .. parsed-literal:: - compute out_mag all spin + compute out_mag all spin - variable mag_z equal c_out_mag[3] - variable mag_norm equal c_out_mag[4] - variable temp_mag equal c_out_mag[6] + variable mag_z equal c_out_mag[3] + variable mag_norm equal c_out_mag[4] + variable temp_mag equal c_out_mag[6] - thermo 10 - thermo_style custom step v_mag_z v_mag_norm v_temp_mag + thermo 10 + thermo_style custom step v_mag_z v_mag_norm v_temp_mag This series of commands evaluates the total magnetization along z, the norm of the total magnetization, and the magnetic temperature. Three variables are diff --git a/doc/rst/compute_temp_body.rst b/doc/rst/compute_temp_body.rst deleted file mode 100644 index e17227fe3e..0000000000 --- a/doc/rst/compute_temp_body.rst +++ /dev/null @@ -1,149 +0,0 @@ -.. index:: compute temp/body - -compute temp/body command -========================= - -Syntax -"""""" - - -.. parsed-literal:: - - compute ID group-ID temp/body keyword value ... - -* ID, group-ID are documented in :doc:`compute ` command -* temp/body = style name of this compute command -* zero or more keyword/value pairs may be appended -* keyword = *bias* or *dof* - - .. parsed-literal:: - - *bias* value = bias-ID - bias-ID = ID of a temperature compute that removes a velocity bias - *dof* value = *all* or *rotate* - all = compute temperature of translational and rotational degrees of freedom - rotate = compute temperature of just rotational degrees of freedom - - - -Examples -"""""""" - - -.. parsed-literal:: - - compute 1 all temp/body - compute myTemp mobile temp/body bias tempCOM - compute myTemp mobile temp/body dof rotate - -Description -""""""""""" - -Define a computation that calculates the temperature of a group of -body particles, including a contribution from both their -translational and rotational kinetic energy. This differs from the -usual :doc:`compute temp ` command, which assumes point -particles with only translational kinetic energy. - -Only body particles can be included in the group. For 3d particles, -each has 6 degrees of freedom (3 translational, 3 rotational). For 2d -body particles, each has 3 degrees of freedom (2 translational, 1 -rotational). - -.. note:: - - This choice for degrees of freedom (dof) assumes that all body - particles in your model will freely rotate, sampling all their - rotational dof. It is possible to use a combination of interaction - potentials and fixes that induce no torque or otherwise constrain some - of all of your particles so that this is not the case. Then there are - less dof and you should use the :doc:`compute\_modify extra ` command to adjust the dof accordingly. - -The translational kinetic energy is computed the same as is described -by the :doc:`compute temp ` command. The rotational -kinetic energy is computed as 1/2 I w\^2, where I is the inertia tensor -for the aspherical particle and w is its angular velocity, which is -computed from its angular momentum. - -A kinetic energy tensor, stored as a 6-element vector, is also -calculated by this compute. The formula for the components of the -tensor is the same as the above formula, except that v\^2 and w\^2 are -replaced by vx\*vy and wx\*wy for the xy component, and the appropriate -elements of the inertia tensor are used. The 6 components of the -vector are ordered xx, yy, zz, xy, xz, yz. - -The number of atoms contributing to the temperature is assumed to be -constant for the duration of the run; use the *dynamic* option of the -:doc:`compute\_modify ` command if this is not the case. - -This compute subtracts out translational degrees-of-freedom due to -fixes that constrain molecular motion, such as :doc:`fix shake ` and :doc:`fix rigid `. This means the -temperature of groups of atoms that include these constraints will be -computed correctly. If needed, the subtracted degrees-of-freedom can -be altered using the *extra* option of the -:doc:`compute\_modify ` command. - -See the :doc:`Howto thermostat ` doc page for a -discussion of different ways to compute temperature and perform -thermostatting. - - ----------- - - -The keyword/value option pairs are used in the following ways. - -For the *bias* keyword, *bias-ID* refers to the ID of a temperature -compute that removes a "bias" velocity from each atom. This allows -compute temp/sphere to compute its thermal temperature after the -translational kinetic energy components have been altered in a -prescribed way, e.g. to remove a flow velocity profile. Thermostats -that use this compute will work with this bias term. See the doc -pages for individual computes that calculate a temperature and the doc -pages for fixes that perform thermostatting for more details. - -For the *dof* keyword, a setting of *all* calculates a temperature -that includes both translational and rotational degrees of freedom. A -setting of *rotate* calculates a temperature that includes only -rotational degrees of freedom. - - ----------- - - -**Output info:** - -This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. -These values can be used by any command that uses global scalar or -vector values from a compute as input. See the :doc:`Howto output ` doc page for an overview of LAMMPS output -options. - -The scalar value calculated by this compute is "intensive". The -vector values are "extensive". - -The scalar value will be in temperature :doc:`units `. The -vector values will be in energy :doc:`units `. - -Restrictions -"""""""""""" - - -This compute is part of the BODY package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` doc page for more info. - -This compute requires that atoms store angular momentum and a -quaternion as defined by the :doc:`atom\_style body ` -command. - -Related commands -"""""""""""""""" - -:doc:`compute temp ` - -**Default:** none - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/compute_temp_chunk.rst b/doc/rst/compute_temp_chunk.rst deleted file mode 100644 index cc9e70a0c5..0000000000 --- a/doc/rst/compute_temp_chunk.rst +++ /dev/null @@ -1,260 +0,0 @@ -.. index:: compute temp/chunk - -compute temp/chunk command -========================== - -Syntax -"""""" - - -.. parsed-literal:: - - compute ID group-ID temp/chunk chunkID value1 value2 ... keyword value ... - -* ID, group-ID are documented in :doc:`compute ` command -* temp/chunk = style name of this compute command -* chunkID = ID of :doc:`compute chunk/atom ` command -* zero or more values can be listed as value1,value2,etc -* value = *temp* or *kecom* or *internal* - - .. parsed-literal:: - - temp = temperature of each chunk - kecom = kinetic energy of each chunk based on velocity of center of mass - internal = internal kinetic energy of each chunk - -* zero or more keyword/value pairs may be appended -* keyword = *com* or *bias* or *adof* or *cdof* - - .. parsed-literal:: - - *com* value = *yes* or *no* - yes = subtract center-of-mass velocity from each chunk before calculating temperature - no = do not subtract center-of-mass velocity - *bias* value = bias-ID - bias-ID = ID of a temperature compute that removes a velocity bias - *adof* value = dof_per_atom - dof_per_atom = define this many degrees-of-freedom per atom - *cdof* value = dof_per_chunk - dof_per_chunk = define this many degrees-of-freedom per chunk - - - -Examples -"""""""" - - -.. parsed-literal:: - - compute 1 fluid temp/chunk molchunk - compute 1 fluid temp/chunk molchunk temp internal - compute 1 fluid temp/chunk molchunk bias tpartial adof 2.0 - -Description -""""""""""" - -Define a computation that calculates the temperature of a group of -atoms that are also in chunks, after optionally subtracting out the -center-of-mass velocity of each chunk. By specifying optional values, -it can also calculate the per-chunk temperature or energies of the -multiple chunks of atoms. - -In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom ` command, which assigns each atom -to a single chunk (or no chunk). The ID for this command is specified -as chunkID. For example, a single chunk could be the atoms in a -molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom ` and :doc:`Howto chunk ` -doc pages for details of how chunks can be defined and examples of how -they can be used to measure properties of a system. - -The temperature is calculated by the formula KE = DOF/2 k T, where KE = -total kinetic energy of all atoms assigned to chunks (sum of 1/2 m -v\^2), DOF = the total number of degrees of freedom for those atoms, k -= Boltzmann constant, and T = temperature. - -The DOF is calculated as N\*adof + Nchunk\*cdof, where N = number of -atoms contributing to the KE, adof = degrees of freedom per atom, and -cdof = degrees of freedom per chunk. By default adof = 2 or 3 = -dimensionality of system, as set via the :doc:`dimension ` -command, and cdof = 0.0. This gives the usual formula for -temperature. - -A kinetic energy tensor, stored as a 6-element vector, is also -calculated by this compute for use in the computation of a pressure -tensor. The formula for the components of the tensor is the same as -the above formula, except that v\^2 is replaced by vx\*vy for the xy -component, etc. The 6 components of the vector are ordered xx, yy, -zz, xy, xz, yz. - -Note that the number of atoms contributing to the temperature is -calculated each time the temperature is evaluated since it is assumed -the atoms may be dynamically assigned to chunks. Thus there is no -need to use the *dynamic* option of the -:doc:`compute\_modify ` command for this compute style. - -If any optional values are specified, then per-chunk quantities are -also calculated and stored in a global array, as described below. - -The *temp* value calculates the temperature for each chunk by the -formula KE = DOF/2 k T, where KE = total kinetic energy of the chunk -of atoms (sum of 1/2 m v\^2), DOF = the total number of degrees of -freedom for all atoms in the chunk, k = Boltzmann constant, and T = -temperature. - -The DOF in this case is calculated as N\*adof + cdof, where N = number -of atoms in the chunk, adof = degrees of freedom per atom, and cdof = -degrees of freedom per chunk. By default adof = 2 or 3 = -dimensionality of system, as set via the :doc:`dimension ` -command, and cdof = 0.0. This gives the usual formula for -temperature. - -The *kecom* value calculates the kinetic energy of each chunk as if -all its atoms were moving with the velocity of the center-of-mass of -the chunk. - -The *internal* value calculates the internal kinetic energy of each -chunk. The interal KE is summed over the atoms in the chunk using an -internal "thermal" velocity for each atom, which is its velocity minus -the center-of-mass velocity of the chunk. - - ----------- - - -Note that currently the global and per-chunk temperatures calculated -by this compute only include translational degrees of freedom for each -atom. No rotational degrees of freedom are included for finite-size -particles. Also no degrees of freedom are subtracted for any velocity -bias or constraints that are applied, such as :doc:`compute temp/partial `, or :doc:`fix shake ` -or :doc:`fix rigid `. This is because those degrees of -freedom (e.g. a constrained bond) could apply to sets of atoms that -are both included and excluded from a specific chunk, and hence the -concept is somewhat ill-defined. In some cases, you can use the -*adof* and *cdof* keywords to adjust the calculated degrees of freedom -appropriately, as explained below. - -Note that the per-chunk temperature calculated by this compute and the -:doc:`fix ave/chunk temp ` command can be different. -This compute calculates the temperature for each chunk for a single -snapshot. Fix ave/chunk can do that but can also time average those -values over many snapshots, or it can compute a temperature as if the -atoms in the chunk on different timesteps were collected together as -one set of atoms to calculate their temperature. This compute allows -the center-of-mass velocity of each chunk to be subtracted before -calculating the temperature; fix ave/chunk does not. - -.. note:: - - Only atoms in the specified group contribute to the calculations - performed by this compute. The :doc:`compute chunk/atom ` command defines its own group; - atoms will have a chunk ID = 0 if they are not in that group, - signifying they are not assigned to a chunk, and will thus also not - contribute to this calculation. You can specify the "all" group for - this command if you simply want to include atoms with non-zero chunk - IDs. - -The simplest way to output the per-chunk results of the compute -temp/chunk calculation to a file is to use the :doc:`fix ave/time ` command, for example: - - -.. parsed-literal:: - - compute cc1 all chunk/atom molecule - compute myChunk all temp/chunk cc1 temp - fix 1 all ave/time 100 1 100 c_myChunk file tmp.out mode vector - - ----------- - - -The keyword/value option pairs are used in the following ways. - -The *com* keyword can be used with a value of *yes* to subtract the -velocity of the center-of-mass for each chunk from the velocity of the -atoms in that chunk, before calculating either the global or per-chunk -temperature. This can be useful if the atoms are streaming or -otherwise moving collectively, and you wish to calculate only the -thermal temperature. - -For the *bias* keyword, *bias-ID* refers to the ID of a temperature -compute that removes a "bias" velocity from each atom. This also -allows calculation of the global or per-chunk temperature using only -the thermal temperature of atoms in each chunk after the translational -kinetic energy components have been altered in a prescribed way, -e.g. to remove a velocity profile. It also applies to the calculation -of the other per-chunk values, such as *kecom* or *internal*\ , which -involve the center-of-mass velocity of each chunk, which is calculated -after the velocity bias is removed from each atom. Note that the -temperature compute will apply its bias globally to the entire system, -not on a per-chunk basis. - -The *adof* and *cdof* keywords define the values used in the degree of -freedom (DOF) formulas used for the global or per-chunk temperature, -as described above. They can be used to calculate a more appropriate -temperature for some kinds of chunks. Here are 3 examples: - -If spatially binned chunks contain some number of water molecules and -:doc:`fix shake ` is used to make each molecule rigid, then -you could calculate a temperature with 6 degrees of freedom (DOF) (3 -translational, 3 rotational) per molecule by setting *adof* to 2.0. - -If :doc:`compute temp/partial ` is used with the -*bias* keyword to only allow the x component of velocity to contribute -to the temperature, then *adof* = 1.0 would be appropriate. - -If each chunk consists of a large molecule, with some number of its -bonds constrained by :doc:`fix shake ` or the entire molecule -by :doc:`fix rigid/small `, *adof* = 0.0 and *cdof* could be -set to the remaining degrees of freedom for the entire molecule -(entire chunk in this case), e.g. 6 for 3d, or 3 for 2d, for a rigid -molecule. - - ----------- - - -**Output info:** - -This compute calculates a global scalar (the temperature) and a global -vector of length 6 (KE tensor), which can be accessed by indices 1-6. -These values can be used by any command that uses global scalar or -vector values from a compute as input. See the :doc:`Howto output ` doc page for an overview of LAMMPS output -options. - -This compute also optionally calculates a global array, if one or more -of the optional values are specified. The number of rows in the array -= the number of chunks *Nchunk* as calculated by the specified -:doc:`compute chunk/atom ` command. The number of -columns is the number of specified values (1 or more). These values -can be accessed by any command that uses global array values from a -compute as input. Again, see the :doc:`Howto output ` doc -page for an overview of LAMMPS output options. - -The scalar value calculated by this compute is "intensive". The -vector values are "extensive". The array values are "intensive". - -The scalar value will be in temperature :doc:`units `. The -vector values will be in energy :doc:`units `. The array values -will be in temperature :doc:`units ` for the *temp* value, and in -energy :doc:`units ` for the *kecom* and *internal* values. - -Restrictions -"""""""""""" - - -The *com* and *bias* keywords cannot be used together. - -Related commands -"""""""""""""""" - -:doc:`compute temp `, :doc:`fix ave/chunk temp ` - -Default -""""""" - -The option defaults are com no, no bias, adof = dimensionality of the -system (2 or 3), and cdof = 0.0. - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/create_bonds.rst b/doc/rst/create_bonds.rst index c98b107224..185c1ebfd7 100644 --- a/doc/rst/create_bonds.rst +++ b/doc/rst/create_bonds.rst @@ -26,11 +26,14 @@ Syntax btype = bond type of new bond batom1,batom2 = atom IDs for two atoms in bond *single/angle* args = atype aatom1 aatom2 aatom3 - atype = bond type of new angle + atype = angle type of new angle aatom1,aatom2,aatom3 = atom IDs for three atoms in angle *single/dihedral* args = dtype datom1 datom2 datom3 datom4 - dtype = bond type of new dihedral + dtype = dihedral type of new dihedral datom1,datom2,datom3,datom4 = atom IDs for four atoms in dihedral + *single/improper* args = itype iatom1 iatom2 iatom3 iatom4 + itype = improper type of new improper + iatom1,iatom2,iatom3,iatom4 = atom IDs for four atoms in improper * zero or more keyword/value pairs may be appended * keyword = *special* @@ -51,53 +54,56 @@ Examples create_bonds many surf solvent 3 2.0 2.4 create_bonds single/bond 1 1 2 create_bonds single/angle 5 52 98 107 special no + create_bonds single/dihedral 2 4 19 27 101 + create_bonds single/improper 3 23 26 31 57 Description """"""""""" Create bonds between pairs of atoms that meet a specified distance -criteria. Or create a single bond, angle, or dihedral between 2, 3, +criteria. Or create a single bond, angle, dihedral or improper between 2, 3, or 4 specified atoms. -The new bond (angle, dihedral) interactions will then be computed -during a simulation by the bond (angle, dihedral) potential defined by +The new bond (angle, dihedral, improper) interactions will then be computed +during a simulation by the bond (angle, dihedral, improper) potential defined by the :doc:`bond\_style `, :doc:`bond\_coeff `, :doc:`angle\_style `, :doc:`angle\_coeff `, :doc:`dihedral\_style `, -:doc:`dihedral\_coeff ` commands. +:doc:`dihedral\_coeff `, :doc:`improper\_style `, +:doc:`improper\_coeff ` commands. The *many* style is useful for adding bonds to a system, e.g. between nearest neighbors in a lattice of atoms, without having to enumerate all the bonds in the data file read by the :doc:`read\_data ` command. -The *single* styles are useful for adding bonds, angles, dihedrals +The *single* styles are useful for adding bonds, angles, dihedrals, impropers to a system incrementally, then continuing a simulation. -Note that this command does not auto-create any angle or dihedral +Note that this command does not auto-create any angle, dihedral or improper interactions when a bond is added. Nor does it auto-create any bonds -when an angle or dihedral is added. Or auto-create any angles when a -dihedral is added. Thus the flexibility of this command is limited. +when an angle, dihedral or improper is added. Or auto-create any angles when a +dihedral or improper is added. Thus the flexibility of this command is limited. It can be used several times to create different types of bond at different distances. But it cannot typically auto-create all the -bonds or angles or dihedral that would normally be defined in a data -file for a complex system of molecules. +bonds or angles or dihedrals or impropers that would normally be defined in a +data file for a complex system of molecules. .. note:: - If the system has no bonds (angles, dihedrals) to begin with, or - if more bonds per atom are being added than currently exist, then you + If the system has no bonds (angles, dihedrals, impropers) to begin with, + or if more bonds per atom are being added than currently exist, then you must insure that the number of bond types and the maximum number of bonds per atom are set to large enough values. And similarly for - angles and dihedrals. Otherwise an error may occur when too many - bonds (angles, dihedrals) are added to an atom. If the + angles, dihedrals and impropers. Otherwise an error may occur when too many + bonds (angles, dihedrals, impropers) are added to an atom. If the :doc:`read\_data ` command is used to define the system, these parameters can be set via the "bond types" and "extra bond per atom" fields in the header section of the data file. If the :doc:`create\_box ` command is used to define the system, these 2 parameters can be set via its optional "bond/types" and - "extra/bond/per/atom" arguments. And similarly for angles and - dihedrals. See the doc pages for these 2 commands for details. + "extra/bond/per/atom" arguments. And similarly for angles, dihedrals and + impropers. See the doc pages for these 2 commands for details. ---------- @@ -156,20 +162,27 @@ ordered linearly within the angle; the central atom is *aatom2*\ . *Atype* must be a value between 1 and the number of angle types defined. -The *single/dihedral* style creates a single dihedral of type *btype* -between two atoms with IDs *batom1* and *batom2*\ . The ordering of the -atoms is the same as in the *Dihedrals* section of a data file read by -the :doc:`read\_data ` command. I.e. the 4 atoms are ordered -linearly within the dihedral. *Dtype* must be a value between 1 and +The *single/dihedral* style creates a single dihedral of type *dtype* +between four atoms with IDs *datom1*\ , *datom2*\ , *datom3*\ , and *datom4*\ . The +ordering of the atoms is the same as in the *Dihedrals* section of a data file +read by the :doc:`read\_data ` command. I.e. the 4 atoms are ordered +linearly within the dihedral. *dtype* must be a value between 1 and the number of dihedral types defined. +The *single/improper* style creates a single improper of type *itype* +between four atoms with IDs *iatom1*\ , *iatom2*\ , *iatom3*\ , and *iatom4*\ . The +ordering of the atoms is the same as in the *Impropers* section of a data file +read by the :doc:`read\_data ` command. I.e. the 4 atoms are ordered +linearly within the improper. *itype* must be a value between 1 and +the number of improper types defined. + ---------- The keyword *special* controls whether an internal list of special -bonds is created after one or more bonds, or a single angle or -dihedral is added to the system. +bonds is created after one or more bonds, or a single angle, dihedral or +improper is added to the system. The default value is *yes*\ . A value of *no* cannot be used with the *many* style. @@ -182,19 +195,19 @@ see the :doc:`special\_bonds ` command for details. Thus if you are adding a few bonds or a large list of angles all at the same time, by using this command repeatedly, it is more efficient to only trigger the internal list to be created once, after the last -bond (or angle, or dihedral) is added: +bond (or angle, or dihedral, or improper) is added: .. parsed-literal:: create_bonds single/bond 5 52 98 special no - create_bonds single/bond 5 73 74 special no + create_bonds single/bond 5 73 74 special no ... create_bonds single/bond 5 17 386 special no create_bonds single/bond 4 112 183 special yes Note that you MUST insure the internal list is re-built after the last -bond (angle, dihedral) is added, before performing a simulation. +bond (angle, dihedral, improper) is added, before performing a simulation. Otherwise pairwise interactions will not be properly excluded or weighted. LAMMPS does NOT check that you have done this correctly. diff --git a/doc/rst/dihedral_class2.rst b/doc/rst/dihedral_class2.rst deleted file mode 100644 index f8f6a01bc4..0000000000 --- a/doc/rst/dihedral_class2.rst +++ /dev/null @@ -1,202 +0,0 @@ -.. index:: dihedral\_style class2 - -dihedral\_style class2 command -============================== - -dihedral\_style class2/omp command -================================== - -dihedral\_style class2/kk command -================================= - -Syntax -"""""" - - -.. parsed-literal:: - - dihedral_style class2 - -Examples -"""""""" - - -.. parsed-literal:: - - dihedral_style class2 - dihedral_coeff 1 100 75 100 70 80 60 - dihedral_coeff \* mbt 3.5945 0.1704 -0.5490 1.5228 - dihedral_coeff \* ebt 0.3417 0.3264 -0.9036 0.1368 0.0 -0.8080 1.0119 1.1010 - dihedral_coeff 2 at 0.0 -0.1850 -0.7963 -2.0220 0.0 -0.3991 110.2453 105.1270 - dihedral_coeff \* aat -13.5271 110.2453 105.1270 - dihedral_coeff \* bb13 0.0 1.0119 1.1010 - -Description -""""""""""" - -The *class2* dihedral style uses the potential - -.. image:: Eqs/dihedral_class2.jpg - :align: center - -where Ed is the dihedral term, Embt is a middle-bond-torsion term, -Eebt is an end-bond-torsion term, Eat is an angle-torsion term, Eaat -is an angle-angle-torsion term, and Ebb13 is a bond-bond-13 term. - -Theta1 and theta2 are equilibrium angles and r1 r2 r3 are equilibrium -bond lengths. - -See :ref:`(Sun) ` for a description of the COMPASS class2 force field. - -Coefficients for the Ed, Embt, Eebt, Eat, Eaat, and Ebb13 formulas -must be defined for each dihedral type via the -:doc:`dihedral\_coeff ` command as in the example above, -or in the data file or restart files read by the -:doc:`read\_data ` or :doc:`read\_restart ` -commands. - -These are the 6 coefficients for the Ed formula: - -* K1 (energy) -* phi1 (degrees) -* K2 (energy) -* phi2 (degrees) -* K3 (energy) -* phi3 (degrees) - -For the Embt formula, each line in a -:doc:`dihedral\_coeff ` command in the input script lists -5 coefficients, the first of which is "mbt" to indicate they are -MiddleBondTorsion coefficients. In a data file, these coefficients -should be listed under a "MiddleBondTorsion Coeffs" heading and you -must leave out the "mbt", i.e. only list 4 coefficients after the -dihedral type. - -* mbt -* A1 (energy/distance) -* A2 (energy/distance) -* A3 (energy/distance) -* r2 (distance) - -For the Eebt formula, each line in a -:doc:`dihedral\_coeff ` command in the input script lists -9 coefficients, the first of which is "ebt" to indicate they are -EndBondTorsion coefficients. In a data file, these coefficients -should be listed under a "EndBondTorsion Coeffs" heading and you must -leave out the "ebt", i.e. only list 8 coefficients after the dihedral -type. - -* ebt -* B1 (energy/distance) -* B2 (energy/distance) -* B3 (energy/distance) -* C1 (energy/distance) -* C2 (energy/distance) -* C3 (energy/distance) -* r1 (distance) -* r3 (distance) - -For the Eat formula, each line in a -:doc:`dihedral\_coeff ` command in the input script lists -9 coefficients, the first of which is "at" to indicate they are -AngleTorsion coefficients. In a data file, these coefficients should -be listed under a "AngleTorsion Coeffs" heading and you must leave out -the "at", i.e. only list 8 coefficients after the dihedral type. - -* at -* D1 (energy/radian) -* D2 (energy/radian) -* D3 (energy/radian) -* E1 (energy/radian) -* E2 (energy/radian) -* E3 (energy/radian) -* theta1 (degrees) -* theta2 (degrees) - -Theta1 and theta2 are specified in degrees, but LAMMPS converts them -to radians internally; hence the units of D and E are in -energy/radian. - -For the Eaat formula, each line in a -:doc:`dihedral\_coeff ` command in the input script lists -4 coefficients, the first of which is "aat" to indicate they are -AngleAngleTorsion coefficients. In a data file, these coefficients -should be listed under a "AngleAngleTorsion Coeffs" heading and you -must leave out the "aat", i.e. only list 3 coefficients after the -dihedral type. - -* aat -* M (energy/radian\^2) -* theta1 (degrees) -* theta2 (degrees) - -Theta1 and theta2 are specified in degrees, but LAMMPS converts them -to radians internally; hence the units of M are in energy/radian\^2. - -For the Ebb13 formula, each line in a -:doc:`dihedral\_coeff ` command in the input script lists -4 coefficients, the first of which is "bb13" to indicate they are -BondBond13 coefficients. In a data file, these coefficients should be -listed under a "BondBond13 Coeffs" heading and you must leave out the -"bb13", i.e. only list 3 coefficients after the dihedral type. - -* bb13 -* N (energy/distance\^2) -* r1 (distance) -* r3 (distance) - - ----------- - - -Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are -functionally the same as the corresponding style without the suffix. -They have been optimized to run faster, depending on your available -hardware, as discussed on the :doc:`Speed packages ` doc -page. The accelerated styles take the same arguments and should -produce the same results, except for round-off and precision issues. - -These accelerated styles are part of the GPU, USER-INTEL, KOKKOS, -USER-OMP and OPT packages, respectively. They are only enabled if -LAMMPS was built with those packages. See the :doc:`Build package ` doc page for more info. - -You can specify the accelerated styles explicitly in your input script -by including their suffix, or you can use the :doc:`-suffix command-line switch ` when you invoke LAMMPS, or you can use the -:doc:`suffix ` command in your input script. - -See the :doc:`Speed packages ` doc page for more -instructions on how to use the accelerated styles effectively. - - ----------- - - -Restrictions -"""""""""""" - - -This dihedral style can only be used if LAMMPS was built with the -CLASS2 package. See the :doc:`Build package ` doc -page for more info. - -Related commands -"""""""""""""""" - -:doc:`dihedral\_coeff ` - -**Default:** none - - ----------- - - -.. _dihedral-Sun: - - - -**(Sun)** Sun, J Phys Chem B 102, 7338-7364 (1998). - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/dihedral_harmonic.rst b/doc/rst/dihedral_harmonic.rst index cd25fe2df1..bdcfbf38ae 100644 --- a/doc/rst/dihedral_harmonic.rst +++ b/doc/rst/dihedral_harmonic.rst @@ -6,6 +6,9 @@ dihedral\_style harmonic command dihedral\_style harmonic/intel command ====================================== +dihedral\_style harmonic/kk command +=================================== + dihedral\_style harmonic/omp command ==================================== diff --git a/doc/rst/dihedral_spherical.rst b/doc/rst/dihedral_spherical.rst deleted file mode 100644 index 4c59e7297f..0000000000 --- a/doc/rst/dihedral_spherical.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. index:: dihedral\_style spherical - -dihedral\_style spherical command -================================= - -Syntax -"""""" - - -.. parsed-literal:: - - dihedral_style spherical - -Examples -"""""""" - - -.. parsed-literal:: - - dihedral_coeff 1 1 286.1 1 124 1 1 90.0 0 1 90.0 0 - dihedral_coeff 1 3 69.3 1 93.9 1 1 90 0 1 90 0 & - 49.1 0 0.00 0 1 74.4 1 0 0.00 0 & - 25.2 0 0.00 0 0 0.00 0 1 48.1 1 - -Description -""""""""""" - -The *spherical* dihedral style uses the potential: - -.. image:: JPG/dihedral_spherical_angles.jpg - :align: center - -.. image:: Eqs/dihedral_spherical.jpg - :align: center - -For this dihedral style, the energy can be any function that combines the -4-body dihedral-angle (phi) and the two 3-body bond-angles (theta1, theta2). -For this reason, there is usually no need to define 3-body "angle" forces -separately for the atoms participating in these interactions. -It is probably more efficient to incorporate 3-body angle forces into -the dihedral interaction even if it requires adding additional terms to -the expansion (as was done in the second example). A careful choice of -parameters can prevent singularities that occur with traditional -force-fields whenever theta1 or theta2 approach 0 or 180 degrees. - -The last example above corresponds to an interaction with a single energy -minima located near phi=93.9, theta1=74.4, theta2=48.1 degrees, and it remains -numerically stable at all angles (phi, theta1, theta2). In this example, -the coefficients 49.1, and 25.2 can be physically interpreted as the -harmonic spring constants for theta1 and theta2 around their minima. -The coefficient 69.3 is the harmonic spring constant for phi after -division by sin(74.4)\*sin(48.1) (the minima positions for theta1 and theta2). - -The following coefficients must be defined for each dihedral type via the -:doc:`dihedral\_coeff ` command as in the example above, or in -the Dihedral Coeffs section of a data file read by the -:doc:`read\_data ` command: - -* n (integer >= 1) -* C1 (energy) -* K1 (typically an integer) -* a1 (degrees) -* u1 (typically 0.0 or 1.0) -* L1 (typically an integer) -* b1 (degrees, typically 0.0 or 90.0) -* v1 (typically 0.0 or 1.0) -* M1 (typically an integer) -* c1 (degrees, typically 0.0 or 90.0) -* w1 (typically 0.0 or 1.0) -* [...] -* Cn (energy) -* Kn (typically an integer) -* an (degrees) -* un (typically 0.0 or 1.0) -* Ln (typically an integer) -* bn (degrees, typically 0.0 or 90.0) -* vn (typically 0.0 or 1.0) -* Mn (typically an integer) -* cn (degrees, typically 0.0 or 90.0) -* wn (typically 0.0 or 1.0) - - ----------- - - -Restrictions -"""""""""""" - - -This dihedral style can only be used if LAMMPS was built with the -USER\_MISC package. See the :doc:`Build package ` doc -page for more info. - -Related commands -"""""""""""""""" - -:doc:`dihedral\_coeff ` - -**Default:** none - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/dump.rst b/doc/rst/dump.rst index 3546e7ce86..e07100bb19 100644 --- a/doc/rst/dump.rst +++ b/doc/rst/dump.rst @@ -34,7 +34,8 @@ Syntax * ID = user-assigned name for the dump * group-ID = ID of the group of atoms to be dumped -* style = *atom* or *atom/gz* or *atom/mpiio* or *cfg* or *cfg/gz* or *cfg/mpiio* or *custom* or *custom/gz* or *custom/mpiio* or *dcd* or *h5md* or *image* or *local* or *molfile* or *movie* or *netcdf* or *netcdf/mpiio* or *vtk* or *xtc* or *xyz* or *xyz/gz* or *xyz/mpiio* +* style = *atom* or *atom/gz* or *atom/mpiio* or *cfg* or *cfg/gz* or + *cfg/mpiio* or *custom* or *custom/gz* or *custom/mpiio* or *dcd* or *h5md* or *image* or *local* or *local/gz* or *molfile* or *movie* or *netcdf* or *netcdf/mpiio* or *vtk* or *xtc* or *xyz* or *xyz/gz* or *xyz/mpiio* * N = dump every this many timesteps * file = name of file to write dump info to * args = list of arguments for a particular style diff --git a/doc/rst/dump_modify.rst b/doc/rst/dump_modify.rst index 93833f9aaf..1aa09c6092 100644 --- a/doc/rst/dump_modify.rst +++ b/doc/rst/dump_modify.rst @@ -14,7 +14,7 @@ Syntax * dump-ID = ID of dump to modify * one or more keyword/value pairs may be appended * these keywords apply to various dump styles -* keyword = *append* or *at* or *buffer* or *delay* or *element* or *every* or *fileper* or *first* or *flush* or *format* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *precision* or *region* or *scale* or *sort* or *thresh* or *unwrap* +* keyword = *append* or *at* or *buffer* or *delay* or *element* or *every* or *fileper* or *first* or *flush* or *format* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap* .. parsed-literal:: @@ -32,10 +32,10 @@ Syntax *fileper* arg = Np Np = write one file for every this many processors *first* arg = *yes* or *no* + *flush* arg = *yes* or *no* *format* args = *line* string, *int* string, *float* string, M string, or *none* string = C-style format string M = integer from 1 to N, where N = # of per-atom quantities being output - *flush* arg = *yes* or *no* *image* arg = *yes* or *no* *label* arg = string string = character string (e.g. BONDS) to use in header of dump local file @@ -50,18 +50,20 @@ Syntax *refresh* arg = c_ID = compute ID that supports a refresh operation *scale* arg = *yes* or *no* *sfactor* arg = coordinate scaling factor (> 0.0) - *thermo* arg = *yes* or *no* - *tfactor* arg = time scaling factor (> 0.0) *sort* arg = *off* or *id* or N or -N off = no sorting of per-atom lines within a snapshot id = sort per-atom lines by atom ID N = sort per-atom lines in ascending order by the Nth column -N = sort per-atom lines in descending order by the Nth column + *tfactor* arg = time scaling factor (> 0.0) + *thermo* arg = *yes* or *no* + *time* arg = *yes* or *no* *thresh* args = attribute operator value attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style operator = "<" or "<=" or ">" or ">=" or "==" or "!=" or "\|\^" value = numeric value to compare to, or LAST these 3 args can be replaced by the word "none" to turn off thresholding + *units* arg = *yes* or *no* *unwrap* arg = *yes* or *no* * these keywords apply only to the *image* and *movie* :doc:`styles ` @@ -716,6 +718,47 @@ threshold criterion is met. Otherwise it is not met. ---------- +The *time* keyword only applies to the dump *atom*\ , *custom*\ , and +*local* styles (and their COMPRESS package versions *atom/gz*\ , +*custom/gz* and *local/gz*\ ). If set to *yes*\ , each frame will will +contain two extra lines before the "ITEM: TIMESTEP" entry: + + +.. parsed-literal:: + + ITEM: TIME + \ + +This will output the current elapsed simulation time in current +time units equivalent to the :doc:`thermo keyword ` *time*\ . +This is to simplify post-processing of trajectories using a variable time +step, e.g. when using :doc:`fix dt/reset `. +The default setting is *no*\ . + + +---------- + + +The *units* keyword only applies to the dump *atom*\ , *custom*\ , and +*local* styles (and their COMPRESS package versions *atom/gz*\ , +*custom/gz* and *local/gz*\ ). If set to *yes*\ , each individual dump +file will contain two extra lines at the very beginning with: + + +.. parsed-literal:: + + ITEM: UNITS + \ + +This will output the current selected :doc:`units ` style +to the dump file and thus allows visualization and post-processing +tools to determine the choice of units of the data in the dump file. +The default setting is *no*\ . + + +---------- + + The *unwrap* keyword only applies to the dump *dcd* and *xtc* styles. If set to *yes*\ , coordinates will be written "unwrapped" by the image flags for each atom. Unwrapped means that if the atom has passed through @@ -1050,6 +1093,7 @@ The option defaults are * sort = off for dump styles *atom*\ , *custom*\ , *cfg*\ , and *local* * sort = id for dump styles *dcd*\ , *xtc*\ , and *xyz* * thresh = none +* units = no * unwrap = no * acolor = \* red/green/blue/yellow/aqua/cyan diff --git a/doc/rst/dump_molfile.rst b/doc/rst/dump_molfile.rst deleted file mode 100644 index 4c03def9b7..0000000000 --- a/doc/rst/dump_molfile.rst +++ /dev/null @@ -1,145 +0,0 @@ -.. index:: dump molfile - -dump molfile command -==================== - -Syntax -"""""" - - -.. parsed-literal:: - - dump ID group-ID molfile N file format path - -* ID = user-assigned name for the dump -* group-ID = ID of the group of atoms to be imaged -* molfile = style of dump command (other styles *atom* or *cfg* or *dcd* or *xtc* or *xyz* or *local* or *custom* are discussed on the :doc:`dump ` doc page) -* N = dump every this many timesteps -* file = name of file to write to -* format = file format to be used -* path = file path with plugins (optional) - - -Examples -"""""""" - - -.. parsed-literal:: - - dump mf1 all molfile 10 melt1.xml hoomd - dump mf2 all molfile 10 melt2-\*.pdb pdb . - dump mf3 all molfile 50 melt3.xyz xyz .:/home/akohlmey/vmd/plugins/LINUX/molfile - -Description -""""""""""" - -Dump a snapshot of atom coordinates and selected additional quantities -to one or more files every N timesteps in one of several formats. -Only information for atoms in the specified group is dumped. This -specific dump style uses molfile plugins that are bundled with the -`VMD `_ molecular visualization and -analysis program. - -Unless the filename contains a \* character, the output will be written -to one single file with the specified format. Otherwise there will be -one file per snapshot and the \* will be replaced by the time step number -when the snapshot is written. - -.. note:: - - Because periodic boundary conditions are enforced only on - timesteps when neighbor lists are rebuilt, the coordinates of an atom - written to a dump file may be slightly outside the simulation box. - -The molfile plugin API has a few restrictions that have to be honored -by this dump style: the number of atoms must not change, the atoms -must be sorted, outside of the coordinates no change in atom properties -(like type, mass, charge) will be recorded. - - ----------- - - -The *format* keyword determines what format is used to write out the -dump. For this to work, LAMMPS must be able to find and load a -compatible molfile plugin that supports this format. Settings made via -the :doc:`dump\_modify ` command can alter per atom properties -like element names. - -The *path* keyword determines which in directories. This is a "path" -like other search paths, i.e. it can contain multiple directories -separated by a colon (or semi-colon on windows). This keyword is -optional and default to ".", the current directory. - -The *unwrap* option of the :doc:`dump\_modify ` command allows -coordinates to be written "unwrapped" by the image flags for each atom. -Unwrapped means that if the atom has passed through a periodic boundary -one or more times, the value is printed for what the coordinate would be -if it had not been wrapped back into the periodic box. Note that these -coordinates may thus be far outside the box size stored with the -snapshot. - - ----------- - - -Dumps are performed on timesteps that are a multiple of N (including -timestep 0) and on the last timestep of a minimization if the -minimization converges. Note that this means a dump will not be -performed on the initial timestep after the dump command is invoked, -if the current timestep is not a multiple of N. This behavior can be -changed via the :doc:`dump\_modify first ` command, which can -be useful if the dump command is invoked after a minimization ended on -an arbitrary timestep. N can be changed between runs by using the -:doc:`dump\_modify every ` command. The :doc:`dump\_modify every ` command also allows a variable to be used to -determine the sequence of timesteps on which dump files are written. - - ----------- - - -Restrictions -"""""""""""" - - -The *molfile* dump style is part of the USER-MOLFILE package. It is -only enabled if LAMMPS was built with that package. See the :doc:`Build package ` doc page for more info. - -Molfile plugins provide a consistent programming interface to read and -write file formats commonly used in molecular simulations. The -USER-MOLFILE package only provides the interface code, not the plugins. -These can be obtained from a VMD installation which has to match the -platform that you are using to compile LAMMPS for. By adding plugins -to VMD, support for new file formats can be added to LAMMPS (or VMD -or other programs that use them) without having to re-compile the -application itself. The plugins are installed in the directory: -/plugins//molfile - -.. note:: - - while the programming interface (API) to the plugins is backward - compatible, the binary interface (ABI) has been changing over time, so - it is necessary to compile this package with the plugin header files - from VMD that match the binary plugins. These header files in the - directory: /plugins/include For convenience, the package ships - with a set of header files that are compatible with VMD 1.9 and 1.9.1 - (June 2012) - - ----------- - - -Related commands -"""""""""""""""" - -:doc:`dump `, :doc:`dump\_modify `, :doc:`undump ` - -Default -""""""" - -The default path is ".". All other properties have to be specified. - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/dynamical_matrix.rst b/doc/rst/dynamical_matrix.rst index 00d26c738f..0d4ccf7589 100644 --- a/doc/rst/dynamical_matrix.rst +++ b/doc/rst/dynamical_matrix.rst @@ -38,16 +38,33 @@ Examples Description """"""""""" -Calculate the dynamical matrix of the selected group. +Calculate the dynamical matrix by finite difference of the selected group, + +.. image:: JPG/dynamical_matrix_dynmat.jpg + :align: center + +where D is the dynamical matrix and Phi is the force constant matrix defined by + +.. image:: JPG/dynamical_matrix_force_constant.jpg + :align: center + +The output for the dynamical matrix is printed three elements at a time. The +three elements are the three beta elements for a respective i/alpha/j combination. +Each line is printed in order of j increasing first, alpha second, and i last. + +If the style eskm is selected, the dynamical matrix will be in units of inverse squared +femtoseconds. These units will then conveniently leave frequencies in THz, where +frequencies, represented as omega, can be calculated from + +:c, image(Eqs/dynamical\_matrix\_phonons.jpg) Restrictions """""""""""" -The command collects the entire dynamical matrix a single MPI rank, -so the memory requirements can be very significant for large systems. - -This command assumes a periodic system. +The command collects an array of nine times the number of atoms in a group +on every single MPI rank, so the memory requirements can be very significant +for large systems. This command is part of the USER-PHONON package. It is only enabled if LAMMPS was built with that package. See the :doc:`Build package ` doc page for more info. diff --git a/doc/rst/fix.rst b/doc/rst/fix.rst index 01d3eca7c1..a9ec639b33 100644 --- a/doc/rst/fix.rst +++ b/doc/rst/fix.rst @@ -198,7 +198,7 @@ accelerated styles exist. * :doc:`box/relax ` - relax box size during energy minimization * :doc:`client/md ` - MD client for client/server simulations * :doc:`cmap ` - enables CMAP cross-terms of the CHARMM force field -* :doc:`colvars ` - interface to the collective variables “Colvars” library +* :doc:`colvars ` - interface to the collective variables "Colvars" library * :doc:`controller ` - apply control loop feedback mechanism * :doc:`deform ` - change the simulation box size/shape * :doc:`deposit ` - add new atoms above a surface @@ -231,7 +231,7 @@ accelerated styles exist. * :doc:`heat ` - add/subtract momentum-conserving heat * :doc:`hyper/global ` - global hyperdynamics * :doc:`hyper/local ` - local hyperdynamics -* :doc:`imd ` - implements the “Interactive MD” (IMD) protocol +* :doc:`imd ` - implements the "Interactive MD" (IMD) protocol * :doc:`indent ` - impose force due to an indenter * :doc:`ipi ` - enable LAMMPS to run as a client for i-PI path-integral simulations * :doc:`langevin ` - Langevin temperature control diff --git a/doc/rst/fix_ave_atom.rst b/doc/rst/fix_ave_atom.rst deleted file mode 100644 index 2886eb8f4e..0000000000 --- a/doc/rst/fix_ave_atom.rst +++ /dev/null @@ -1,194 +0,0 @@ -.. index:: fix ave/atom - -fix ave/atom command -==================== - -Syntax -"""""" - - -.. parsed-literal:: - - fix ID group-ID ave/atom Nevery Nrepeat Nfreq value1 value2 ... - -* ID, group-ID are documented in :doc:`fix ` command -* ave/atom = style name of this fix command -* Nevery = use input values every this many timesteps -* Nrepeat = # of times to use input values for calculating averages -* Nfreq = calculate averages every this many timesteps - one or more input values can be listed -* value = x, y, z, vx, vy, vz, fx, fy, fz, c\_ID, c\_ID[i], f\_ID, f\_ID[i], v\_name - - .. parsed-literal:: - - x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (position, velocity, force component) - c_ID = per-atom vector calculated by a compute with ID - c_ID[I] = Ith column of per-atom array calculated by a compute with ID, I can include wildcard (see below) - f_ID = per-atom vector calculated by a fix with ID - f_ID[I] = Ith column of per-atom array calculated by a fix with ID, I can include wildcard (see below) - v_name = per-atom vector calculated by an atom-style variable with name - - - -Examples -"""""""" - - -.. parsed-literal:: - - fix 1 all ave/atom 1 100 100 vx vy vz - fix 1 all ave/atom 10 20 1000 c_my_stress[1] - fix 1 all ave/atom 10 20 1000 c_my_stress[\*] - -Description -""""""""""" - -Use one or more per-atom vectors as inputs every few timesteps, and -average them atom by atom over longer timescales. The resulting -per-atom averages can be used by other :doc:`output commands ` such as the :doc:`fix ave/chunk ` or :doc:`dump custom ` commands. - -The group specified with the command means only atoms within the group -have their averages computed. Results are set to 0.0 for atoms not in -the group. - -Each input value can be an atom attribute (position, velocity, force -component) or can be the result of a :doc:`compute ` or -:doc:`fix ` or the evaluation of an atom-style -:doc:`variable `. In the latter cases, the compute, fix, or -variable must produce a per-atom vector, not a global quantity or -local quantity. If you wish to time-average global quantities from a -compute, fix, or variable, then see the :doc:`fix ave/time ` command. - -Each per-atom value of each input vector is averaged independently. - -:doc:`Computes ` that produce per-atom vectors or arrays are -those which have the word *atom* in their style name. See the doc -pages for individual :doc:`fixes ` to determine which ones produce -per-atom vectors or arrays. :doc:`Variables ` of style *atom* -are the only ones that can be used with this fix since they produce -per-atom vectors. - -Note that for values from a compute or fix, the bracketed index I can -be specified using a wildcard asterisk with the index to effectively -specify multiple values. This takes the form "\*" or "\*n" or "n\*" or -"m\*n". If N = the size of the vector (for *mode* = scalar) or the -number of columns in the array (for *mode* = vector), then an asterisk -with no numeric values means all indices from 1 to N. A leading -asterisk means all indices from 1 to n (inclusive). A trailing -asterisk means all indices from n to N (inclusive). A middle asterisk -means all indices from m to n (inclusive). - -Using a wildcard is the same as if the individual columns of the array -had been listed one by one. E.g. these 2 fix ave/atom commands are -equivalent, since the :doc:`compute stress/atom ` -command creates a per-atom array with 6 columns: - - -.. parsed-literal:: - - compute my_stress all stress/atom NULL - fix 1 all ave/atom 10 20 1000 c_my_stress[\*] - fix 1 all ave/atom 10 20 1000 c_my_stress[1] c_my_stress[1] & - c_my_stress[3] c_my_stress[4] & - c_my_stress[5] c_my_stress[6] - - ----------- - - -The *Nevery*\ , *Nrepeat*\ , and *Nfreq* arguments specify on what -timesteps the input values will be used in order to contribute to the -average. The final averaged quantities are generated on timesteps -that are a multiple of *Nfreq*\ . The average is over *Nrepeat* -quantities, computed in the preceding portion of the simulation every -*Nevery* timesteps. *Nfreq* must be a multiple of *Nevery* and -*Nevery* must be non-zero even if *Nrepeat* is 1. Also, the timesteps -contributing to the average value cannot overlap, -i.e. Nrepeat\*Nevery can not exceed Nfreq. - -For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on -timesteps 90,92,94,96,98,100 will be used to compute the final average -on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on -timestep 200, etc. - - ----------- - - -The atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are -self-explanatory. Note that other atom attributes can be used as -inputs to this fix by using the :doc:`compute property/atom ` command and then specifying -an input value from that compute. - -.. note:: - - The x,y,z attributes are values that are re-wrapped inside the - periodic box whenever an atom crosses a periodic boundary. Thus if - you time average an atom that spends half its time on either side of - the periodic box, you will get a value in the middle of the box. If - this is not what you want, consider averaging unwrapped coordinates, - which can be provided by the :doc:`compute property/atom ` command via its xu,yu,zu - attributes. - -If a value begins with "c\_", a compute ID must follow which has been -previously defined in the input script. If no bracketed term is -appended, the per-atom vector calculated by the compute is used. If a -bracketed term containing an index I is appended, the Ith column of -the per-atom array calculated by the compute is used. Users can also -write code for their own compute styles and :doc:`add them to LAMMPS `. See the discussion above for how I can -be specified with a wildcard asterisk to effectively specify multiple -values. - -If a value begins with "f\_", a fix ID must follow which has been -previously defined in the input script. If no bracketed term is -appended, the per-atom vector calculated by the fix is used. If a -bracketed term containing an index I is appended, the Ith column of -the per-atom array calculated by the fix is used. Note that some -fixes only produce their values on certain timesteps, which must be -compatible with *Nevery*\ , else an error will result. Users can also -write code for their own fix styles and :doc:`add them to LAMMPS `. See the discussion above for how I can be -specified with a wildcard asterisk to effectively specify multiple -values. - -If a value begins with "v\_", a variable name must follow which has -been previously defined in the input script as an :doc:`atom-style variable ` Variables of style *atom* can reference -thermodynamic keywords, or invoke other computes, fixes, or variables -when they are evaluated, so this is a very general means of generating -per-atom quantities to time average. - - ----------- - - -**Restart, fix\_modify, output, run start/stop, minimize info:** - -No information about this fix is written to :doc:`binary restart files `. None of the :doc:`fix\_modify ` options -are relevant to this fix. No global scalar or vector quantities are -stored by this fix for access by various :doc:`output commands `. - -This fix produces a per-atom vector or array which can be accessed by -various :doc:`output commands `. A vector is produced if -only a single quantity is averaged by this fix. If two or more -quantities are averaged, then an array of values is produced. The -per-atom values can only be accessed on timesteps that are multiples -of *Nfreq* since that is when averaging is performed. - -No parameter of this fix can be used with the *start/stop* keywords of -the :doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. - -Restrictions -"""""""""""" - none - -Related commands -"""""""""""""""" - -:doc:`compute `, :doc:`fix ave/histo `, :doc:`fix ave/chunk `, :doc:`fix ave/time `, -:doc:`variable `, - -**Default:** none - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/fix_bond_create.rst b/doc/rst/fix_bond_create.rst deleted file mode 100644 index 9a11558e83..0000000000 --- a/doc/rst/fix_bond_create.rst +++ /dev/null @@ -1,265 +0,0 @@ -.. index:: fix bond/create - -fix bond/create command -======================= - -Syntax -"""""" - - -.. parsed-literal:: - - fix ID group-ID bond/create Nevery itype jtype Rmin bondtype keyword values ... - -* ID, group-ID are documented in :doc:`fix ` command -* bond/create = style name of this fix command -* Nevery = attempt bond creation every this many steps -* itype,jtype = atoms of itype can bond to atoms of jtype -* Rmin = 2 atoms separated by less than Rmin can bond (distance units) -* bondtype = type of created bonds -* zero or more keyword/value pairs may be appended to args -* keyword = *iparam* or *jparam* or *prob* or *atype* or *dtype* or *itype* - - .. parsed-literal:: - - *iparam* values = maxbond, newtype - maxbond = max # of bonds of bondtype the itype atom can have - newtype = change the itype atom to this type when maxbonds exist - *jparam* values = maxbond, newtype - maxbond = max # of bonds of bondtype the jtype atom can have - newtype = change the jtype atom to this type when maxbonds exist - *prob* values = fraction seed - fraction = create a bond with this probability if otherwise eligible - seed = random number seed (positive integer) - *atype* value = angletype - angletype = type of created angles - *dtype* value = dihedraltype - dihedraltype = type of created dihedrals - *itype* value = impropertype - impropertype = type of created impropers - - - -Examples -"""""""" - - -.. parsed-literal:: - - fix 5 all bond/create 10 1 2 0.8 1 - fix 5 all bond/create 1 3 3 0.8 1 prob 0.5 85784 iparam 2 3 - fix 5 all bond/create 1 3 3 0.8 1 prob 0.5 85784 iparam 2 3 atype 1 dtype 2 - -Description -""""""""""" - -Create bonds between pairs of atoms as a simulation runs according to -specified criteria. This can be used to model cross-linking of -polymers, the formation of a percolation network, etc. In this -context, a bond means an interaction between a pair of atoms computed -by the :doc:`bond\_style ` command. Once the bond is created -it will be permanently in place. Optionally, the creation of a bond -can also create angle, dihedral, and improper interactions that bond -is part of. See the discussion of the *atype*\ , *dtype*\ , and *itype* -keywords below. - -This is different than a :doc:`pairwise ` bond-order -potential such as Tersoff or AIREBO which infers bonds and many-body -interactions based on the current geometry of a small cluster of atoms -and effectively creates and destroys bonds and higher-order many-body -interactions from timestep to timestep as atoms move. - -A check for possible new bonds is performed every *Nevery* timesteps. -If two atoms I,J are within a distance *Rmin* of each other, if I is -of atom type *itype*\ , if J is of atom type *jtype*\ , if both I and J -are in the specified fix group, if a bond does not already exist -between I and J, and if both I and J meet their respective *maxbond* -requirement (explained below), then I,J is labeled as a "possible" -bond pair. - -If several atoms are close to an atom, it may have multiple possible -bond partners. Every atom checks its list of possible bond partners -and labels the closest such partner as its "sole" bond partner. After -this is done, if atom I has atom J as its sole partner, and atom J has -atom I as its sole partner, then the I,J bond is "eligible" to be -formed. - -Note that these rules mean an atom will only be part of at most one -created bond on a given timestep. It also means that if atom I -chooses atom J as its sole partner, but atom J chooses atom K is its -sole partner (due to Rjk < Rij), then this means atom I will not form -a bond on this timestep, even if it has other possible bond partners. - -It is permissible to have *itype* = *jtype*\ . *Rmin* must be <= the -pairwise cutoff distance between *itype* and *jtype* atoms, as defined -by the :doc:`pair\_style ` command. - -The *iparam* and *jparam* keywords can be used to limit the bonding -functionality of the participating atoms. Each atom keeps track of -how many bonds of *bondtype* it already has. If atom I of -itype already has *maxbond* bonds (as set by the *iparam* -keyword), then it will not form any more. Likewise for atom J. If -*maxbond* is set to 0, then there is no limit on the number of bonds -that can be formed with that atom. - -The *newtype* value for *iparam* and *jparam* can be used to change -the atom type of atom I or J when it reaches *maxbond* number of bonds -of type *bondtype*\ . This means it can now interact in a pairwise -fashion with other atoms in a different way by specifying different -:doc:`pair\_coeff ` coefficients. If you do not wish the -atom type to change, simply specify *newtype* as *itype* or *jtype*\ . - -The *prob* keyword can also effect whether an eligible bond is -actually created. The *fraction* setting must be a value between 0.0 -and 1.0. A uniform random number between 0.0 and 1.0 is generated and -the eligible bond is only created if the random number < fraction. - -Any bond that is created is assigned a bond type of *bondtype* - -When a bond is created, data structures within LAMMPS that store bond -topology are updated to reflect the creation. If the bond is part of -new 3-body (angle) or 4-body (dihedral, improper) interactions, you -can choose to create new angles, dihedrals, impropers as well, using -the *atype*\ , *dtype*\ , and *itype* keywords. All of these changes -typically affect pairwise interactions between atoms that are now part -of new bonds, angles, etc. - -.. note:: - - One data structure that is not updated when a bond breaks are - the molecule IDs stored by each atom. Even though two molecules - become one molecule due to the created bond, all atoms in the new - molecule retain their original molecule IDs. - -If the *atype* keyword is used and if an angle potential is defined -via the :doc:`angle\_style ` command, then any new 3-body -interactions inferred by the creation of a bond will create new angles -of type *angletype*\ , with parameters assigned by the corresponding -:doc:`angle\_coeff ` command. Likewise, the *dtype* and -*itype* keywords will create new dihedrals and impropers of type -*dihedraltype* and *impropertype*\ . - -.. note:: - - To create a new bond, the internal LAMMPS data structures that - store this information must have space for it. When LAMMPS is - initialized from a data file, the list of bonds is scanned and the - maximum number of bonds per atom is tallied. If some atom will - acquire more bonds than this limit as this fix operates, then the - "extra bond per atom" parameter must be set to allow for it. Ditto - for "extra angle per atom", "extra dihedral per atom", and "extra - improper per atom" if angles, dihedrals, or impropers are being added - when bonds are created. See the :doc:`read\_data ` or - :doc:`create\_box ` command for more details. Note that a - data file with no atoms can be used if you wish to add non-bonded - atoms via the :doc:`create atoms ` command, e.g. for a - percolation simulation. - -.. note:: - - LAMMPS stores and maintains a data structure with a list of the - 1st, 2nd, and 3rd neighbors of each atom (within the bond topology of - the system) for use in weighting pairwise interactions for bonded - atoms. Note that adding a single bond always adds a new 1st neighbor - but may also induce \*many\* new 2nd and 3rd neighbors, depending on the - molecular topology of your system. The "extra special per atom" - parameter must typically be set to allow for the new maximum total - size (1st + 2nd + 3rd neighbors) of this per-atom list. There are 2 - ways to do this. See the :doc:`read\_data ` or - :doc:`create\_box ` commands for details. - -.. note:: - - Even if you do not use the *atype*\ , *dtype*\ , or *itype* - keywords, the list of topological neighbors is updated for atoms - affected by the new bond. This in turn affects which neighbors are - considered for pairwise interactions, using the weighting rules set by - the :doc:`special\_bonds ` command. Consider a new bond - created between atoms I,J. If J has a bonded neighbor K, then K - becomes a 2nd neighbor of I. Even if the *atype* keyword is not used - to create angle I-J-K, the pairwise interaction between I and K will - be potentially turned off or weighted by the 1-3 weighting specified - by the :doc:`special\_bonds ` command. This is the case - even if the "angle yes" option was used with that command. The same - is true for 3rd neighbors (1-4 interactions), the *dtype* keyword, and - the "dihedral yes" option used with the - :doc:`special\_bonds ` command. - -Note that even if your simulation starts with no bonds, you must -define a :doc:`bond\_style ` and use the -:doc:`bond\_coeff ` command to specify coefficients for the -*bondtype*\ . Similarly, if new atom types are specified by the -*iparam* or *jparam* keywords, they must be within the range of atom -types allowed by the simulation and pairwise coefficients must be -specified for the new types. - -Computationally, each timestep this fix operates, it loops over -neighbor lists and computes distances between pairs of atoms in the -list. It also communicates between neighboring processors to -coordinate which bonds are created. Moreover, if any bonds are -created, neighbor lists must be immediately updated on the same -timestep. This is to insure that any pairwise interactions that -should be turned "off" due to a bond creation, because they are now -excluded by the presence of the bond and the settings of the -:doc:`special\_bonds ` command, will be immediately -recognized. All of these operations increase the cost of a timestep. -Thus you should be cautious about invoking this fix too frequently. - -You can dump out snapshots of the current bond topology via the :doc:`dump local ` command. - -.. note:: - - Creating a bond typically alters the energy of a system. You - should be careful not to choose bond creation criteria that induce a - dramatic change in energy. For example, if you define a very stiff - harmonic bond and create it when 2 atoms are separated by a distance - far from the equilibrium bond length, then the 2 atoms will oscillate - dramatically when the bond is formed. More generally, you may need to - thermostat your system to compensate for energy changes resulting from - created bonds (and angles, dihedrals, impropers). - - ----------- - - -**Restart, fix\_modify, output, run start/stop, minimize info:** - -No information about this fix is written to :doc:`binary restart files `. None of the :doc:`fix\_modify ` options -are relevant to this fix. - -This fix computes two statistics which it stores in a global vector of -length 2, which can be accessed by various :doc:`output commands `. The vector values calculated by this fix -are "intensive". - -These are the 2 quantities: - -* (1) # of bonds created on the most recent creation timestep -* (2) cumulative # of bonds created - -No parameter of this fix can be used with the *start/stop* keywords of -the :doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. - -Restrictions -"""""""""""" - - -This fix is part of the MC package. It is only enabled if LAMMPS was -built with that package. See the :doc:`Build package ` -doc page for more info. - -Related commands -"""""""""""""""" - -:doc:`fix bond/break `, :doc:`fix bond/react `, :doc:`fix bond/swap `, -:doc:`dump local `, :doc:`special\_bonds ` - -Default -""""""" - -The option defaults are iparam = (0,itype), jparam = (0,jtype), and -prob = 1.0. - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/fix_bond_react.rst b/doc/rst/fix_bond_react.rst index ef37c515e3..ab63aa232c 100644 --- a/doc/rst/fix_bond_react.rst +++ b/doc/rst/fix_bond_react.rst @@ -202,20 +202,27 @@ reacting atoms. Some atoms in the pre-reacted template that are not reacting may have missing topology with respect to the simulation. For example, the -pre-reacted template may contain an atom that would connect to the -rest of a long polymer chain. These are referred to as edge atoms, and -are also specified in the map file. When the pre-reaction template -contains edge atoms, not all atoms, bonds, charges, etc. specified in -the reaction templates will be updated. Specifically, topology that -involves only atoms that are 'too near' to template edges will not be -updated. The definition of 'too near the edge' depends on which -interactions are defined in the simulation. If the simulation has -defined dihedrals, atoms within two bonds of edge atoms are considered -'too near the edge.' If the simulation defines angles, but not -dihedrals, atoms within one bond of edge atoms are considered 'too -near the edge.' If just bonds are defined, only edge atoms are +pre-reacted template may contain an atom that, in the simulation, is +currently connected to the rest of a long polymer chain. These are +referred to as edge atoms, and are also specified in the map file. All +pre-reaction template atoms should be linked to a bonding atom, via at +least one path that does not involve edge atoms. When the pre-reaction +template contains edge atoms, not all atoms, bonds, charges, etc. +specified in the reaction templates will be updated. Specifically, +topology that involves only atoms that are 'too near' to template +edges will not be updated. The definition of 'too near the edge' +depends on which interactions are defined in the simulation. If the +simulation has defined dihedrals, atoms within two bonds of edge atoms +are considered 'too near the edge.' If the simulation defines angles, +but not dihedrals, atoms within one bond of edge atoms are considered +'too near the edge.' If just bonds are defined, only edge atoms are considered 'too near the edge.' +.. note:: + + Small molecules, i.e. ones that have all their atoms contained + within the reaction templates, never have edge atoms. + Note that some care must be taken when a building a molecule template for a given simulation. All atom types in the pre-reacted template must be the same as those of a potential reaction site in the @@ -285,7 +292,7 @@ either 'none' or 'charges.' Further details are provided in the discussion of the 'update\_edges' keyword. The fourth optional section begins with the keyword 'Constraints' and lists additional criteria that must be satisfied in order for the reaction to occur. Currently, -there is one type of constraint available, as discussed below. +there are three types of constraints available, as discussed below. A sample map file is given below: @@ -326,8 +333,8 @@ A sample map file is given below: Any number of additional constraints may be specified in the -Constraints section of the map file. Currently there is one type of -additional constraint, of type 'distance', whose syntax is as follows: +Constraints section of the map file. The constraint of type 'distance' +has syntax as follows: .. parsed-literal:: @@ -336,10 +343,47 @@ additional constraint, of type 'distance', whose syntax is as follows: where 'distance' is the required keyword, *ID1* and *ID2* are pre-reaction atom IDs, and these two atoms must be separated by a -distance between *rmin* and *rmax* for the reaction to occur. This +distance between *rmin* and *rmax* for the reaction to occur. + +The constraint of type 'angle' has the following syntax: + + +.. parsed-literal:: + + angle *ID1* *ID2* *ID3* *amin* *amax* + +where 'angle' is the required keyword, *ID1*\ , *ID2* and *ID3* are +pre-reaction atom IDs, and these three atoms must form an angle +between *amin* and *amax* for the reaction to occur (where *ID2* is +the central atom). Angles must be specified in degrees. This constraint can be used to enforce a certain orientation between reacting molecules. +The constraint of type 'arrhenius' imposes an additional reaction +probability according to the temperature-dependent Arrhenius equation: + +.. image:: Eqs/fix_bond_react.jpg + :align: center + +The Arrhenius constraint has the following syntax: + + +.. parsed-literal:: + + arrhenius *A* *n* *E_a* *seed* + +where 'arrhenius' is the required keyword, *A* is the pre-exponential +factor, *n* is the exponent of the temperature dependence, *E\_a* is +the activation energy (:doc:`units ` of energy), and *seed* is a +random number seed. The temperature is defined as the instantaneous +temperature averaged over all atoms in the reaction site, and is +calculated in the same manner as for example +:doc:`compute\_temp\_chunk `. Currently, there are no +options for additional temperature averaging or velocity-biased +temperature calculations. A uniform random number between 0 and 1 is +generated using *seed*\ ; if this number is less than the result of the +Arrhenius equation above, the reaction is permitted to occur. + Once a reaction site has been successfully identified, data structures within LAMMPS that store bond topology are updated to reflect the post-reacted molecule template. All force fields with fixed bonds, @@ -420,7 +464,7 @@ all currently-reacting atoms: Computationally, each timestep this fix operates, it loops over neighbor lists (for bond-forming reactions) and computes distances between pairs of atoms in the list. It also communicates between -neighboring processors to coordinate which bonds are created and/or +neighboring processors to coordinate which bonds are created and/or removed. All of these operations increase the cost of a timestep. Thus you should be cautious about invoking this fix too frequently. @@ -433,9 +477,10 @@ local command. **Restart, fix\_modify, output, run start/stop, minimize info:** -No information about this fix is written to :doc:`binary restart files `, aside from internally-created per-atom -properties. None of the :doc:`fix\_modify ` options are -relevant to this fix. +Cumulative reaction counts for each reaction are written to :doc:`binary restart files `. These values are associated with the +reaction name (react-ID). Additionally, internally-created per-atom +properties are stored to allow for smooth restarts. None of the +:doc:`fix\_modify ` options are relevant to this fix. This fix computes one statistic for each *react* argument that it stores in a global vector, of length 'number of react arguments', that @@ -446,8 +491,8 @@ These is 1 quantity for each react argument: * (1) cumulative # of reactions occurred -No parameter of this fix can be used with the *start/stop* keywords of -the :doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. +No parameter of this fix can be used with the *start/stop* keywords +of the :doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. When fix bond/react is 'unfixed,' all internally-created groups are deleted. Therefore, fix bond/react can only be unfixed after unfixing @@ -458,18 +503,22 @@ Restrictions This fix is part of the USER-MISC package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` doc page for more info. +LAMMPS was built with that package. See the +:doc:`Build package ` doc page for more info. Related commands """""""""""""""" -:doc:`fix bond/create `, :doc:`fix bond/break `, :doc:`fix bond/swap `, +:doc:`fix bond/create `, +:doc:`fix bond/break `, +:doc:`fix bond/swap `, :doc:`dump local `, :doc:`special\_bonds ` Default """"""" -The option defaults are stabilization = no, prob = 1.0, stabilize\_steps = 60, update\_edges = none +The option defaults are stabilization = no, prob = 1.0, stabilize\_steps = 60, +update\_edges = none ---------- diff --git a/doc/rst/fix_langevin.rst b/doc/rst/fix_langevin.rst index 49e7013ee2..d6f52084f5 100644 --- a/doc/rst/fix_langevin.rst +++ b/doc/rst/fix_langevin.rst @@ -28,9 +28,10 @@ Syntax *angmom* value = *no* or factor *no* = do not thermostat rotational degrees of freedom via the angular momentum factor = do thermostat rotational degrees of freedom via the angular momentum and apply numeric scale factor as discussed below - *gjf* value = *no* or *yes* + *gjf* value = *no* or *vfull* or *vhalf* *no* = use standard formulation - *yes* = use Gronbech-Jensen/Farago formulation + *vfull* = use Gronbech-Jensen/Farago formulation + *vhalf* = use 2GJ formulation *omega* value = *no* or *yes* *no* = do not thermostat rotational degrees of freedom via the angular velocity *yes* = do thermostat rotational degrees of freedom via the angular velocity @@ -231,6 +232,12 @@ the particles. As described below, this energy can then be printed out or added to the potential energy of the system to monitor energy conservation. +.. note:: + + this accumulated energy does NOT include kinetic energy removed + by the *zero* flag. LAMMPS will print a warning when both options are + active. + The keyword *zero* can be used to eliminate drift due to the thermostat. Because the random forces on different atoms are independent, they do not sum exactly to zero. As a result, this fix @@ -245,29 +252,24 @@ The keyword *gjf* can be used to run the :ref:`Gronbech-Jensen/Farago `; this velocity +is shown to be systematically lower than the target temperature by a small +amount, which grows quadratically with the timestep. +The *gjf* option *vhalf* outputs the 2GJ half-step velocity given in +:ref:`Gronbech Jensen/Gronbech-Jensen <2Gronbech-Jensen>`; for linear systems, +this velocity is shown to not have any statistical errors for any stable time step. +An overview of statistically correct Boltzmann and Maxwell-Boltzmann +sampling of true on-site and true half-step velocities is given in +:ref:`Gronbech-Jensen <1Gronbech-Jensen>`. +Regardless of the choice of output velocity, the sampling of the configurational +distribution of atom positions is the same, and linearly consistent with the target temperature. -As an example of using the *gjf* keyword, for molecules containing C-H -bonds, configurational properties generated with dt = 2.5 fs and tdamp -= 100 fs are indistinguishable from dt = 0.5 fs. Because the velocity -distribution systematically decreases with increasing timestep, the -method should not be used to generate properties that depend on the -velocity distribution, such as the velocity auto-correlation function -(VACF). In this example, the velocity distribution at dt = 2.5fs -generates an average temperature of 220 K, instead of 300 K. - ---------- @@ -327,7 +329,10 @@ This fix is not invoked during :doc:`energy minimization `. Restrictions """""""""""" - none + + +For *gjf* do not choose damp=dt/2. *gjf* is not compatible +with run\_style respa. Related commands """""""""""""""" @@ -361,8 +366,19 @@ types, tally = no, zero = no, gjf = no. **(Gronbech-Jensen)** Gronbech-Jensen and Farago, Mol Phys, 111, 983 -(2013); Gronbech-Jensen, Hayre, and Farago, Comp Phys Comm, -185, 524 (2014) +(2013); Gronbech-Jensen, Hayre, and Farago, Comp Phys Comm, 185, 524 (2014) + +.. _2Gronbech-Jensen: + + + +**(Gronbech-Jensen)** Gronbech Jensen and Gronbech-Jensen, Mol Phys, 117, 2511 (2019) + +.. _1Gronbech-Jensen: + + + +**(Gronbech-Jensen)** Gronbech-Jensen, Mol Phys (2019); https://doi.org/10.1080/00268976.2019.1662506 .. _lws: http://lammps.sandia.gov diff --git a/doc/rst/fix_langevin_spin.rst b/doc/rst/fix_langevin_spin.rst index d49bd96c1e..2902c8fb24 100644 --- a/doc/rst/fix_langevin_spin.rst +++ b/doc/rst/fix_langevin_spin.rst @@ -58,7 +58,7 @@ As an example: fix 1 all precession/spin zeeman 0.01 0.0 0.0 1.0 fix 2 all langevin/spin 300.0 0.01 21 - fix 3 all nve/spin lattice yes + fix 3 all nve/spin lattice moving is correct, but defining a force/spin command after the langevin/spin command would give an error message. diff --git a/doc/rst/fix_mvv_dpd.rst b/doc/rst/fix_mvv_dpd.rst deleted file mode 100644 index 9c9471fd71..0000000000 --- a/doc/rst/fix_mvv_dpd.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. index:: fix mvv/dpd - -fix mvv/dpd command -=================== - -fix mvv/edpd command -==================== - -fix mvv/tdpd command -==================== - -Syntax -"""""" - - -.. parsed-literal:: - - fix ID group-ID mvv/dpd lambda - - fix ID group-ID mvv/edpd lambda - - fix ID group-ID mvv/tdpd lambda - -* ID, group-ID are documented in :doc:`fix ` command -* mvv/dpd, mvv/edpd, mvv/tdpd = style name of this fix command -* lambda = (optional) relaxation parameter (unitless) - -Examples -"""""""" - - -.. parsed-literal:: - - fix 1 all mvv/dpd - fix 1 all mvv/dpd 0.5 - fix 1 all mvv/edpd - fix 1 all mvv/edpd 0.5 - fix 1 all mvv/tdpd - fix 1 all mvv/tdpd 0.5 - -Description -""""""""""" - -Perform time integration using the modified velocity-Verlet (MVV) -algorithm to update position and velocity (fix mvv/dpd), or position, -velocity and temperature (fix mvv/edpd), or position, velocity and -concentration (fix mvv/tdpd) for particles in the group each timestep. - -The modified velocity-Verlet (MVV) algorithm aims to improve the -stability of the time integrator by using an extrapolated version of -the velocity for the force evaluation: - -.. image:: Eqs/fix_mvv_dpd.jpg - :align: center - -where the parameter λ depends on the -specific choice of DPD parameters, and needs to be tuned on a -case-by-case basis. Specification of a *lambda* value is optional. -If specified, the setting must be from 0.0 to 1.0. If not specified, -a default value of 0.5 is used, which effectively reproduces the -standard velocity-Verlet (VV) scheme. For more details, see -:ref:`Groot `. - -Fix *mvv/dpd* updates the position and velocity of each atom. It can -be used with the :doc:`pair\_style mdpd ` command or other -pair styles such as :doc:`pair dpd `. - -Fix *mvv/edpd* updates the per-atom temperature, in addition to -position and velocity, and must be used with the :doc:`pair\_style edpd ` command. - -Fix *mvv/tdpd* updates the per-atom chemical concentration, in -addition to position and velocity, and must be used with the -:doc:`pair\_style tdpd ` command. - - ----------- - - -**Restart, fix\_modify, output, run start/stop, minimize info:** - -No information about this fix is written to :doc:`binary restart files `. None of the :doc:`fix\_modify ` options -are relevant to this fix. No global or per-atom quantities are stored -by this fix for access by various :doc:`output commands `. -No parameter of this fix can be used with the *start/stop* keywords of -the :doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. - -Restrictions -"""""""""""" - - -This fix is part of the USER-MESO package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` doc page for more info. - -Related commands -"""""""""""""""" - -:doc:`pair\_style mdpd `, :doc:`pair\_style edpd `, -:doc:`pair\_style tdpd ` - -Default -""""""" - -The default value for the optional *lambda* parameter is 0.5. - - ----------- - - -.. _Groot2: - - - -**(Groot)** Groot and Warren, J Chem Phys, 107: 4423-4435 (1997). DOI: -10.1063/1.474784 - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/fix_neb_spin.rst b/doc/rst/fix_neb_spin.rst index 0e52a0f3c1..5b316f0009 100644 --- a/doc/rst/fix_neb_spin.rst +++ b/doc/rst/fix_neb_spin.rst @@ -28,18 +28,18 @@ Description """"""""""" Add nudging forces to spins in the group for a multi-replica -simulation run via the :doc:`neb/spin ` command to perform a -geodesic nudged elastic band (GNEB) calculation for finding the +simulation run via the :doc:`neb/spin ` command to perform a +geodesic nudged elastic band (GNEB) calculation for finding the transition state. -Hi-level explanations of GNEB are given with the -:doc:`neb/spin ` command and on the -:doc:`Howto replica ` doc page. -The fix neb/spin command must be used with the "neb/spin" command and -defines how inter-replica nudging forces are computed. A GNEB -calculation is divided in two stages. In the first stage n replicas -are relaxed toward a MEP until convergence. In the second stage, the -climbing image scheme is enabled, so that the replica having the highest -energy relaxes toward the saddle point (i.e. the point of highest energy +Hi-level explanations of GNEB are given with the +:doc:`neb/spin ` command and on the +:doc:`Howto replica ` doc page. +The fix neb/spin command must be used with the "neb/spin" command and +defines how inter-replica nudging forces are computed. A GNEB +calculation is divided in two stages. In the first stage n replicas +are relaxed toward a MEP until convergence. In the second stage, the +climbing image scheme is enabled, so that the replica having the highest +energy relaxes toward the saddle point (i.e. the point of highest energy along the MEP), and a second relaxation is performed. The nudging forces are calculated as explained in diff --git a/doc/rst/fix_nve_spin.rst b/doc/rst/fix_nve_spin.rst index 99be270bfb..5f1b1a648f 100644 --- a/doc/rst/fix_nve_spin.rst +++ b/doc/rst/fix_nve_spin.rst @@ -17,7 +17,9 @@ Syntax .. parsed-literal:: - *lattice* value = *no* or *yes* + *lattice* value = *moving* or *frozen* + moving = integrate both spin and atomic degress of freedom + frozen = integrate spins on a fixed lattice @@ -27,8 +29,8 @@ Examples .. parsed-literal:: - fix 3 all nve/spin lattice yes - fix 1 all nve/spin lattice no + fix 3 all nve/spin lattice moving + fix 1 all nve/spin lattice frozen Description """"""""""" @@ -36,9 +38,11 @@ Description Perform a symplectic integration for the spin or spin-lattice system. The *lattice* keyword defines if the spins are integrated on a lattice -of fixed atoms (lattice = no), or if atoms are moving (lattice = yes). - -By default (lattice = yes), a spin-lattice integration is performed. +of fixed atoms (lattice = frozen), or if atoms are moving +(lattice = moving). +The first case corresponds to a spin dynamics calculation, and +the second to a spin-lattice calculation. +By default a spin-lattice integration is performed (lattice = moving). The *nve/spin* fix applies a Suzuki-Trotter decomposition to the equations of motion of the spin lattice system, following the scheme: @@ -80,7 +84,10 @@ Related commands :doc:`atom\_style spin `, :doc:`fix nve ` -**Default:** none +Default +""""""" + +The option default is lattice = moving. ---------- diff --git a/doc/rst/fix_precession_spin.rst b/doc/rst/fix_precession_spin.rst index 0d8f356e61..f2b99fa4a2 100644 --- a/doc/rst/fix_precession_spin.rst +++ b/doc/rst/fix_precession_spin.rst @@ -27,7 +27,7 @@ Syntax .. parsed-literal:: - *cubic* args = K1 K2c n1x n1y n1x n2x n2y n2z n3x n3y n3z + *cubic* args = K1 K2c n1x n1y n1x n2x n2y n2z n3x n3y n3z K1 and K2c = intensity of the magnetic anisotropy (in eV) n1x to n3z = three direction vectors of the cubic anisotropy @@ -74,20 +74,20 @@ possible easy axis for the magnetic spins in the defined group: .. image:: Eqs/fix_spin_cubic.jpg :align: center -with K1 and K2c (in eV) the intensity coefficients and +with K1 and K2c (in eV) the intensity coefficients and n1, n2 and n3 defining the three anisotropic directions -defined by the command (from n1x to n3z). -For n1 = (100), n2 = (010), and n3 = (001), K1 < 0 defines an +defined by the command (from n1x to n3z). +For n1 = (100), n2 = (010), and n3 = (001), K1 < 0 defines an iron type anisotropy (easy axis along the (001)-type cube edges), and K1 > 0 defines a nickel type anisotropy (easy axis -along the (111)-type cube diagonals). +along the (111)-type cube diagonals). K2\^c > 0 also defines easy axis along the (111)-type cube diagonals. See chapter 2 of :ref:`(Skomski) ` for more details on cubic anisotropies. In all cases, the choice of (x y z) only imposes the vector -directions for the forces. Only the direction of the vector is +directions for the forces. Only the direction of the vector is important; it's length is ignored (the entered vectors are normalized). diff --git a/doc/rst/fix_setforce.rst b/doc/rst/fix_setforce.rst index 1dcd80b9bb..a01fb7dc00 100644 --- a/doc/rst/fix_setforce.rst +++ b/doc/rst/fix_setforce.rst @@ -81,15 +81,15 @@ to it. ---------- -Style *spin* suffix sets the components of the magnetic precession -vectors instead of the mechanical forces. This also erases all -previously computed magnetic precession vectors on the atom, though +Style *spin* suffix sets the components of the magnetic precession +vectors instead of the mechanical forces. This also erases all +previously computed magnetic precession vectors on the atom, though additional magnetic fixes could add new forces. -This command can be used to freeze the magnetic moment of certain +This command can be used to freeze the magnetic moment of certain atoms in the simulation by zeroing their precession vector. -All options defined above remain valid, they just apply to the magnetic +All options defined above remain valid, they just apply to the magnetic precession vectors instead of the forces. diff --git a/doc/rst/fix_spring_self.rst b/doc/rst/fix_spring_self.rst deleted file mode 100644 index d061c96eba..0000000000 --- a/doc/rst/fix_spring_self.rst +++ /dev/null @@ -1,96 +0,0 @@ -.. index:: fix spring/self - -fix spring/self command -======================= - -Syntax -"""""" - - -.. parsed-literal:: - - fix ID group-ID spring/self K dir - -* ID, group-ID are documented in :doc:`fix ` command -* spring/self = style name of this fix command -* K = spring constant (force/distance units) -* dir = xyz, xy, xz, yz, x, y, or z (optional, default: xyz) - -Examples -"""""""" - - -.. parsed-literal:: - - fix tether boundary-atoms spring/self 10.0 - fix zrest move spring/self 10.0 z - -Description -""""""""""" - -Apply a spring force independently to each atom in the group to tether -it to its initial position. The initial position for each atom is its -location at the time the fix command was issued. At each timestep, -the magnitude of the force on each atom is -Kr, where r is the -displacement of the atom from its current position to its initial -position. The distance r correctly takes into account any crossings -of periodic boundary by the atom since it was in its initial -position. - -With the (optional) dir flag, one can select in which direction the -spring force is applied. By default, the restraint is applied in all -directions, but it can be limited to the xy-, xz-, yz-plane and the -x-, y-, or z-direction, thus restraining the atoms to a line or a -plane, respectively. - -**Restart, fix\_modify, output, run start/stop, minimize info:** - -This fix writes the original coordinates of tethered atoms to :doc:`binary restart files `, so that the spring effect will be the -same in a restarted simulation. See the -:doc:`read\_restart ` command for info on how to re-specify -a fix in an input script that reads a restart file, so that the -operation of the fix continues in an uninterrupted fashion. - -The :doc:`fix\_modify ` *energy* option is supported by this -fix to add the energy stored in the per-atom springs to the system's -potential energy as part of :doc:`thermodynamic output `. - -The :doc:`fix\_modify ` *respa* option is supported by -this fix. This allows to set at which level of the :doc:`r-RESPA ` -integrator the fix is adding its forces. Default is the outermost level. - -This fix computes a global scalar which can be accessed by various -:doc:`output commands `. The scalar is an energy which is -the sum of the spring energy for each atom, where the per-atom energy -is 0.5 \* K \* r\^2. The scalar value calculated by this fix is -"extensive". - -No parameter of this fix can be used with the *start/stop* keywords of -the :doc:`run ` command. - -The forces due to this fix are imposed during an energy minimization, -invoked by the :doc:`minimize ` command. - -.. note:: - - If you want the per-atom spring energy to be included in the - total potential energy of the system (the quantity being minimized), - you MUST enable the :doc:`fix\_modify ` *energy* option for - this fix. - -Restrictions -"""""""""""" - none - -Related commands -"""""""""""""""" - -:doc:`fix drag `, :doc:`fix spring `, -:doc:`fix smd `, :doc:`fix spring/rg ` - -**Default:** none - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/fix_wall.rst b/doc/rst/fix_wall.rst deleted file mode 100644 index b31ee4a663..0000000000 --- a/doc/rst/fix_wall.rst +++ /dev/null @@ -1,415 +0,0 @@ -.. index:: fix wall/lj93 - -fix wall/lj93 command -===================== - -fix wall/lj93/kk command -======================== - -fix wall/lj126 command -====================== - -fix wall/lj1043 command -======================= - -fix wall/colloid command -======================== - -fix wall/harmonic command -========================= - -fix wall/morse command -====================== - -Syntax -"""""" - - -.. parsed-literal:: - - fix ID group-ID style face args ... keyword value ... - -* ID, group-ID are documented in :doc:`fix ` command -* style = *wall/lj93* or *wall/lj126* or *wall/lj1043* or *wall/colloid* or *wall/harmonic* or *wall/morse* -* one or more face/arg pairs may be appended -* face = *xlo* or *xhi* or *ylo* or *yhi* or *zlo* or *zhi* -* args for styles *lj93* or *lj126* or *lj1043* or *colloid* or *harmonic* - - .. parsed-literal:: - - args = coord epsilon sigma cutoff - coord = position of wall = EDGE or constant or variable - EDGE = current lo or hi edge of simulation box - constant = number like 0.0 or -30.0 (distance units) - variable = :doc:`equal-style variable ` like v_x or v_wiggle - epsilon = strength factor for wall-particle interaction (energy or energy/distance\^2 units) - epsilon can be a variable (see below) - sigma = size factor for wall-particle interaction (distance units) - sigma can be a variable (see below) - cutoff = distance from wall at which wall-particle interaction is cut off (distance units) - -* args for style *morse* - - .. parsed-literal:: - - args = coord D_0 alpha r_0 cutoff - coord = position of wall = EDGE or constant or variable - EDGE = current lo or hi edge of simulation box - constant = number like 0.0 or -30.0 (distance units) - variable = :doc:`equal-style variable ` like v_x or v_wiggle - D_0 = depth of the potential (energy units) - D_0 can be a variable (see below) - alpha = width factor for wall-particle interaction (1/distance units) - alpha can be a variable (see below) - r_0 = distance of the potential minimum from the face of region (distance units) - r_0 can be a variable (see below) - cutoff = distance from wall at which wall-particle interaction is cut off (distance units) - -* zero or more keyword/value pairs may be appended -* keyword = *units* or *fld* - - .. parsed-literal:: - - *units* value = *lattice* or *box* - *lattice* = the wall position is defined in lattice units - *box* = the wall position is defined in simulation box units - *fld* value = *yes* or *no* - *yes* = invoke the wall constraint to be compatible with implicit FLD - *no* = invoke the wall constraint in the normal way - *pbc* value = *yes* or *no* - *yes* = allow periodic boundary in a wall dimension - *no* = require non-perioidic boundaries in any wall dimension - - - -Examples -"""""""" - - -.. parsed-literal:: - - fix wallhi all wall/lj93 xlo -1.0 1.0 1.0 2.5 units box - fix wallhi all wall/lj93 xhi EDGE 1.0 1.0 2.5 - fix wallhi all wall/morse xhi EDGE 1.0 1.0 1.0 2.5 units box - fix wallhi all wall/lj126 v_wiggle 23.2 1.0 1.0 2.5 - fix zwalls all wall/colloid zlo 0.0 1.0 1.0 0.858 zhi 40.0 1.0 1.0 0.858 - -Description -""""""""""" - -Bound the simulation domain on one or more of its faces with a flat -wall that interacts with the atoms in the group by generating a force -on the atom in a direction perpendicular to the wall. The energy of -wall-particle interactions depends on the style. - -For style *wall/lj93*\ , the energy E is given by the 9/3 potential: - -.. image:: Eqs/fix_wall_lj93.jpg - :align: center - -For style *wall/lj126*\ , the energy E is given by the 12/6 potential: - -.. image:: Eqs/pair_lj.jpg - :align: center - -For style *wall/lj1043*\ , the energy E is given by the 10/4/3 potential: - -.. image:: Eqs/fix_wall_lj1043.jpg - :align: center - -For style *wall/colloid*\ , the energy E is given by an integrated form -of the :doc:`pair\_style colloid ` potential: - -.. image:: Eqs/fix_wall_colloid.jpg - :align: center - -For style *wall/harmonic*\ , the energy E is given by a harmonic spring -potential: - -.. image:: Eqs/fix_wall_harmonic.jpg - :align: center - -For style *wall/morse*\ , the energy E is given by a Morse potential: - -.. image:: Eqs/pair_morse.jpg - :align: center - -In all cases, *r* is the distance from the particle to the wall at -position *coord*\ , and Rc is the *cutoff* distance at which the -particle and wall no longer interact. The energy of the wall -potential is shifted so that the wall-particle interaction energy is -0.0 at the cutoff distance. - -Up to 6 walls or faces can be specified in a single command: *xlo*\ , -*xhi*\ , *ylo*\ , *yhi*\ , *zlo*\ , *zhi*\ . A *lo* face interacts with -particles near the lower side of the simulation box in that dimension. -A *hi* face interacts with particles near the upper side of the -simulation box in that dimension. - -The position of each wall can be specified in one of 3 ways: as the -EDGE of the simulation box, as a constant value, or as a variable. If -EDGE is used, then the corresponding boundary of the current -simulation box is used. If a numeric constant is specified then the -wall is placed at that position in the appropriate dimension (x, y, or -z). In both the EDGE and constant cases, the wall will never move. -If the wall position is a variable, it should be specified as v\_name, -where name is an :doc:`equal-style variable ` name. In this -case the variable is evaluated each timestep and the result becomes -the current position of the reflecting wall. Equal-style variables -can specify formulas with various mathematical functions, and include -:doc:`thermo\_style ` command keywords for the simulation -box parameters and timestep and elapsed time. Thus it is easy to -specify a time-dependent wall position. See examples below. - -For the *wall/lj93* and *wall/lj126* and *wall/lj1043* styles, -*epsilon* and *sigma* are the usual Lennard-Jones parameters, which -determine the strength and size of the particle as it interacts with -the wall. Epsilon has energy units. Note that this *epsilon* and -*sigma* may be different than any *epsilon* or *sigma* values defined -for a pair style that computes particle-particle interactions. - -The *wall/lj93* interaction is derived by integrating over a 3d -half-lattice of Lennard-Jones 12/6 particles. The *wall/lj126* -interaction is effectively a harder, more repulsive wall interaction. -The *wall/lj1043* interaction is yet a different form of wall -interaction, described in Magda et al in :ref:`(Magda) `. - -For the *wall/colloid* style, *R* is the radius of the colloid -particle, *D* is the distance from the surface of the colloid particle -to the wall (r-R), and *sigma* is the size of a constituent LJ -particle inside the colloid particle and wall. Note that the cutoff -distance Rc in this case is the distance from the colloid particle -center to the wall. The prefactor *epsilon* can be thought of as an -effective Hamaker constant with energy units for the strength of the -colloid-wall interaction. More specifically, the *epsilon* pre-factor -= 4 \* pi\^2 \* rho\_wall \* rho\_colloid \* epsilon \* sigma\^6, where epsilon -and sigma are the LJ parameters for the constituent LJ -particles. Rho\_wall and rho\_colloid are the number density of the -constituent particles, in the wall and colloid respectively, in units -of 1/volume. - -The *wall/colloid* interaction is derived by integrating over -constituent LJ particles of size *sigma* within the colloid particle -and a 3d half-lattice of Lennard-Jones 12/6 particles of size *sigma* -in the wall. As mentioned in the preceding paragraph, the density of -particles in the wall and colloid can be different, as specified by -the *epsilon* pre-factor. - -For the *wall/harmonic* style, *epsilon* is effectively the spring -constant K, and has units (energy/distance\^2). The input parameter -*sigma* is ignored. The minimum energy position of the harmonic -spring is at the *cutoff*\ . This is a repulsive-only spring since the -interaction is truncated at the *cutoff* - -For the *wall/morse* style, the three parameters are in this order: -*D\_0* the depth of the potential, *alpha* the width parameter, and -*r\_0* the location of the minimum. *D\_0* has energy units, *alpha* -inverse distance units, and *r\_0* distance units. - -For any wall, the *epsilon* and/or *sigma* and/or *alpha* parameter can -be specified -as an :doc:`equal-style variable `, in which case it should be -specified as v\_name, where name is the variable name. As with a -variable wall position, the variable is evaluated each timestep and -the result becomes the current epsilon or sigma of the wall. -Equal-style variables can specify formulas with various mathematical -functions, and include :doc:`thermo\_style ` command -keywords for the simulation box parameters and timestep and elapsed -time. Thus it is easy to specify a time-dependent wall interaction. - -.. note:: - - For all of the styles, you must insure that r is always > 0 for - all particles in the group, or LAMMPS will generate an error. This - means you cannot start your simulation with particles at the wall - position *coord* (r = 0) or with particles on the wrong side of the - wall (r < 0). For the *wall/lj93* and *wall/lj126* styles, the energy - of the wall/particle interaction (and hence the force on the particle) - blows up as r -> 0. The *wall/colloid* style is even more - restrictive, since the energy blows up as D = r-R -> 0. This means - the finite-size particles of radius R must be a distance larger than R - from the wall position *coord*\ . The *harmonic* style is a softer - potential and does not blow up as r -> 0, but you must use a large - enough *epsilon* that particles always reamin on the correct side of - the wall (r > 0). - -The *units* keyword determines the meaning of the distance units used -to define a wall position, but only when a numeric constant or -variable is used. It is not relevant when EDGE is used to specify a -face position. In the variable case, the variable is assumed to -produce a value compatible with the *units* setting you specify. - -A *box* value selects standard distance units as defined by the -:doc:`units ` command, e.g. Angstroms for units = real or metal. -A *lattice* value means the distance units are in lattice spacings. -The :doc:`lattice ` command must have been previously used to -define the lattice spacings. - -The *fld* keyword can be used with a *yes* setting to invoke the wall -constraint before pairwise interactions are computed. This allows an -implicit FLD model using :doc:`pair\_style lubricateU ` -to include the wall force in its calculations. If the setting is -*no*\ , wall forces are imposed after pairwise interactions, in the -usual manner. - -The *pbc* keyword can be used with a *yes* setting to allow walls to -be specified in a periodic dimension. See the -:doc:`boundary ` command for options on simulation box -boundaries. The default for *pbc* is *no*\ , which means the system -must be non-periodic when using a wall. But you may wish to use a -periodic box. E.g. to allow some particles to interact with the wall -via the fix group-ID, and others to pass through it and wrap around a -periodic box. In this case you should insure that the wall if -sufficiently far enough away from the box boundary. If you do not, -then particles may interact with both the wall and with periodic -images on the other side of the box, which is probably not what you -want. - - ----------- - - -Here are examples of variable definitions that move the wall position -in a time-dependent fashion using equal-style -:doc:`variables `. The wall interaction parameters (epsilon, -sigma) could be varied with additional variable definitions. - - -.. parsed-literal:: - - variable ramp equal ramp(0,10) - fix 1 all wall xlo v_ramp 1.0 1.0 2.5 - - variable linear equal vdisplace(0,20) - fix 1 all wall xlo v_linear 1.0 1.0 2.5 - - variable wiggle equal swiggle(0.0,5.0,3.0) - fix 1 all wall xlo v_wiggle 1.0 1.0 2.5 - - variable wiggle equal cwiggle(0.0,5.0,3.0) - fix 1 all wall xlo v_wiggle 1.0 1.0 2.5 - -The ramp(lo,hi) function adjusts the wall position linearly from lo to -hi over the course of a run. The vdisplace(c0,velocity) function does -something similar using the equation position = c0 + velocity\*delta, -where delta is the elapsed time. - -The swiggle(c0,A,period) function causes the wall position to -oscillate sinusoidally according to this equation, where omega = 2 PI -/ period: - - -.. parsed-literal:: - - position = c0 + A sin(omega\*delta) - -The cwiggle(c0,A,period) function causes the wall position to -oscillate sinusoidally according to this equation, which will have an -initial wall velocity of 0.0, and thus may impose a gentler -perturbation on the particles: - - -.. parsed-literal:: - - position = c0 + A (1 - cos(omega\*delta)) - - ----------- - - -**Restart, fix\_modify, output, run start/stop, minimize info:** - -No information about this fix is written to :doc:`binary restart files `. - -The :doc:`fix\_modify ` *energy* option is supported by this -fix to add the energy of interaction between atoms and each wall to -the system's potential energy as part of :doc:`thermodynamic output `. - -The :doc:`fix\_modify ` *virial* option is supported by this -fix to add the contribution due to the interaction between -atoms and each wall to the system's virial as part of :doc:`thermodynamic output `. The default is *virial no* - -The :doc:`fix\_modify ` *respa* option is supported by this -fix. This allows to set at which level of the :doc:`r-RESPA ` -integrator the fix is adding its forces. Default is the outermost level. - -This fix computes a global scalar energy and a global vector of -forces, which can be accessed by various :doc:`output commands `. Note that the scalar energy is the sum -of interactions with all defined walls. If you want the energy on a -per-wall basis, you need to use multiple fix wall commands. The -length of the vector is equal to the number of walls defined by the -fix. Each vector value is the normal force on a specific wall. Note -that an outward force on a wall will be a negative value for *lo* -walls and a positive value for *hi* walls. The scalar and vector -values calculated by this fix are "extensive". - -No parameter of this fix can be used with the *start/stop* keywords of -the :doc:`run ` command. - -The forces due to this fix are imposed during an energy minimization, -invoked by the :doc:`minimize ` command. - -.. note:: - - If you want the atom/wall interaction energy to be included in - the total potential energy of the system (the quantity being - minimized), you MUST enable the :doc:`fix\_modify ` *energy* - option for this fix. - - ----------- - - -Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are -functionally the same as the corresponding style without the suffix. -They have been optimized to run faster, depending on your available -hardware, as discussed on the :doc:`Speed packages ` doc -page. The accelerated styles take the same arguments and should -produce the same results, except for round-off and precision issues. - -These accelerated styles are part of the GPU, USER-INTEL, KOKKOS, -USER-OMP and OPT packages, respectively. They are only enabled if -LAMMPS was built with those packages. See the :doc:`Build package ` doc page for more info. - -You can specify the accelerated styles explicitly in your input script -by including their suffix, or you can use the :doc:`-suffix command-line switch ` when you invoke LAMMPS, or you can use the -:doc:`suffix ` command in your input script. - -See the :doc:`Speed packages ` doc page for more -instructions on how to use the accelerated styles effectively. - - ----------- - - -Restrictions -"""""""""""" - none - -Related commands -"""""""""""""""" - -:doc:`fix wall/reflect `, -:doc:`fix wall/gran `, -:doc:`fix wall/region ` - -Default -""""""" - -The option defaults units = lattice, fld = no, and pbc = no. - - ----------- - - -.. _Magda: - - - -**(Magda)** Magda, Tirrell, Davis, J Chem Phys, 83, 1888-1901 (1985); -erratum in JCP 84, 2901 (1986). - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/improper_fourier.rst b/doc/rst/improper_fourier.rst index 46621b03c7..227b02d275 100644 --- a/doc/rst/improper_fourier.rst +++ b/doc/rst/improper_fourier.rst @@ -21,7 +21,7 @@ Examples .. parsed-literal:: improper_style fourier - improper_coeff 1 100.0 180.0 + improper_coeff 1 100.0 0.0 1.0 0.5 1 Description """"""""""" @@ -31,13 +31,13 @@ The *fourier* improper style uses the following potential: .. image:: Eqs/improper_fourier.jpg :align: center -where K is the force constant and omega is the angle between the IL -axis and the IJK plane: +where K is the force constant, C0, C1, C2 are dimensionless coefficients, +and omega is the angle between the IL axis and the IJK plane: .. image:: JPG/umbrella.jpg :align: center -If all parameter (see bellow) is not zero, the all the three possible angles will taken in account. +If all parameter (see below) is not zero, the all the three possible angles will taken in account. The following coefficients must be defined for each improper type via the :doc:`improper\_coeff ` command as in the example @@ -46,10 +46,10 @@ above, or in the data file or restart files read by the commands: * K (energy) -* C0 (real) -* C1 (real) -* C2 (real) -* all (integer >= 0) +* C0 (unitless) +* C1 (unitless) +* C2 (unitless) +* all (0 or 1, optional) ---------- diff --git a/doc/rst/kspace_style.rst b/doc/rst/kspace_style.rst index 0537f0cdf8..b5c649a885 100644 --- a/doc/rst/kspace_style.rst +++ b/doc/rst/kspace_style.rst @@ -131,10 +131,10 @@ used without a cutoff, i.e. they become full long-range potentials. The *ewald/disp* style can also be used with point-dipoles, see :ref:`(Toukmaji) `. -The *ewald/dipole* style adds long-range standard Ewald summations +The *ewald/dipole* style adds long-range standard Ewald summations for dipole-dipole interactions, see :ref:`(Toukmaji) `. -The *ewald/dipole/spin* style adds long-range standard Ewald +The *ewald/dipole/spin* style adds long-range standard Ewald summations for magnetic dipole-dipole interactions between magnetic spins. @@ -159,10 +159,10 @@ The optional *smallq* argument defines the cutoff for the absolute charge value which determines whether a particle is considered charged or not. Its default value is 1.0e-5. -The *pppm/dipole* style invokes a particle-particle particle-mesh solver +The *pppm/dipole* style invokes a particle-particle particle-mesh solver for dipole-dipole interactions, following the method of :ref:`(Cerda) `. -The *pppm/dipole/spin* style invokes a particle-particle particle-mesh solver +The *pppm/dipole/spin* style invokes a particle-particle particle-mesh solver for magnetic dipole-dipole interactions between magnetic spins. The *pppm/tip4p* style is identical to the *pppm* style except that it diff --git a/doc/rst/min_modify.rst b/doc/rst/min_modify.rst index 8ef9b238e3..6b25a1d32d 100644 --- a/doc/rst/min_modify.rst +++ b/doc/rst/min_modify.rst @@ -15,11 +15,15 @@ Syntax .. parsed-literal:: - keyword = *dmax* or *line* or *alpha_damp* or *discrete_factor* + keyword = *dmax* or *line* or *norm* or *alpha_damp* or *discrete_factor* *dmax* value = max max = maximum distance for line search to move (distance units) - *line* value = *backtrack* or *quadratic* or *forcezero* - backtrack,quadratic,forcezero = style of linesearch to use + *line* value = *backtrack* or *quadratic* or *forcezero* or *spin_cubic* or *spin_none* + backtrack,quadratic,forcezero,spin_cubic,spin_none = style of linesearch to use + *norm* value = *two* or *max* + two = Euclidean two-norm (length of 3N vector) + inf = max force component across all 3-vectors + max = max force norm across all 3-vectors *alpha_damp* value = damping damping = fictitious Gilbert damping for spin minimization (adim) *discrete_factor* value = factor @@ -77,20 +81,59 @@ difference of two large values (energy before and energy after) and that difference may be smaller than machine epsilon even if atoms could move in the gradient direction to reduce forces further. +The choice of a norm can be modified for the min styles *cg*\ , *sd*\ , +*quickmin*\ , *fire*\ , *spin*\ , *spin/cg* and *spin/lbfgs* using +the *norm* keyword. +The default *two* norm computes the 2-norm (Euclidean length) of the +global force vector: + +.. image:: Eqs/norm_two.jpg + :align: center + +The *max* norm computes the length of the 3-vector force +for each atom (2-norm), and takes the maximum value of those across +all atoms + +.. image:: Eqs/norm_max.jpg + :align: center + +The *inf* norm takes the maximum component across the forces of +all atoms in the system: + +.. image:: Eqs/norm_inf.jpg + :align: center + +For the min styles *spin*\ , *spin/cg* and *spin/lbfgs*\ , the force +norm is replaced by the spin-torque norm. + Keywords *alpha\_damp* and *discrete\_factor* only make sense when -a :doc:`min\_spin ` command is declared. +a :doc:`min\_spin ` command is declared. Keyword *alpha\_damp* defines an analog of a magnetic Gilbert damping. It defines a relaxation rate toward an equilibrium for -a given magnetic system. +a given magnetic system. Keyword *discrete\_factor* defines a discretization factor for the -adaptive timestep used in the *spin* minimization. +adaptive timestep used in the *spin* minimization. See :doc:`min\_spin ` for more information about those -quantities. -Default values are *alpha\_damp* = 1.0 and *discrete\_factor* = 10.0. +quantities. + +The choice of a line search algorithm for the *spin/cg* and +*spin/lbfgs* styles can be specified via the *line* keyword. +The *spin\_cubic* and *spin\_none* only make sense when one of those +two minimization styles is declared. +The *spin\_cubic* performs the line search based on a cubic interpolation +of the energy along the search direction. The *spin\_none* keyword +deactivates the line search procedure. +The *spin\_none* is a default value for *line* keyword for both *spin/lbfgs* +and *spin/cg*\ . Convergence of *spin/lbfgs* can be more robust if +*spin\_cubic* line search is used. Restrictions """""""""""" - none + + +For magnetic GNEB calculations, only *spin\_none* value for *line* keyword can be used +when styles *spin/cg* and *spin/lbfgs* are employed. +See :doc:`neb/spin ` for more explanation. Related commands """""""""""""""" @@ -100,7 +143,11 @@ Related commands Default """"""" -The option defaults are dmax = 0.1 and line = quadratic. +The option defaults are dmax = 0.1, line = quadratic and norm = two. + +For the *spin*\ , *spin/cg* and *spin/lbfgs* styles, the +option defaults are alpha\_damp = 1.0, discrete\_factor = 10.0, +line = spin\_none, and norm = euclidean. .. _lws: http://lammps.sandia.gov diff --git a/doc/rst/min_spin.rst b/doc/rst/min_spin.rst index a49cb3cdb4..1535a1067f 100644 --- a/doc/rst/min_spin.rst +++ b/doc/rst/min_spin.rst @@ -3,13 +3,21 @@ min\_style spin command ======================= +min\_style spin/cg command +========================== + +min\_style spin/lbfgs command +============================= + Syntax """""" .. parsed-literal:: - min_style spin + min_style spin + min_style spin/cg + min_style spin/lbfgs Examples """""""" @@ -17,7 +25,8 @@ Examples .. parsed-literal:: - min_style spin + min_style spin/lbfgs + min_modify line spin_cubic discrete_factor 10.0 Description """"""""""" @@ -33,12 +42,12 @@ timestep, according to: with lambda a damping coefficient (similar to a Gilbert damping). -Lambda can be defined by setting the *alpha\_damp* keyword with the +Lambda can be defined by setting the *alpha\_damp* keyword with the :doc:`min\_modify ` command. The minimization procedure solves this equation using an -adaptive timestep. The value of this timestep is defined -by the largest precession frequency that has to be solved in the +adaptive timestep. The value of this timestep is defined +by the largest precession frequency that has to be solved in the system: .. image:: Eqs/min_spin_timestep.jpg @@ -48,16 +57,47 @@ with *\|omega\|\_\ *max*\ * the norm of the largest precession frequency in the system (across all processes, and across all replicas if a spin/neb calculation is performed). -Kappa defines a discretization factor *discrete\_factor* for the -definition of this timestep. +Kappa defines a discretization factor *discrete\_factor* for the +definition of this timestep. *discrete\_factor* can be defined with the :doc:`min\_modify ` command. +Style *spin/cg* defines an orthogonal spin optimization +(OSO) combined to a conjugate gradient (CG) algorithm. +The :doc:`min\_modify ` command can be used to +couple the *spin/cg* to a line search procedure, and to modify the +discretization factor *discrete\_factor*. +By default, style *spin/cg* does not employ the line search procedure +and uses the adaptive time-step technique in the same way as style *spin*\ . + +Style *spin/lbfgs* defines an orthogonal spin optimization +(OSO) combined to a limited-memory Broyden-Fletcher-Goldfarb-Shanno +(L-BFGS) algorithm. +By default, style *spin/lbfgs* does not employ line search procedure. +If the line search procedure is not used then the discrete factor defines +the maximum root mean squared rotation angle of spins by equation *pi/(5\*Kappa)*. +The default value for Kappa is 10. +The *spin\_cubic* line search can improve the convergence of the +*spin/lbfgs* algorithm. + +The :doc:`min\_modify ` command can be used to +activate the line search procedure, and to modify the +discretization factor *discrete\_factor*. + +For more information about styles *spin/cg* and *spin/lbfgs*\ , +see their implementation reported in :ref:`(Ivanov) `. + .. note:: - The *spin* style replaces the force tolerance by a torque + All the *spin* styles replace the force tolerance by a torque tolerance. See :doc:`minimize ` for more explanation. +.. note:: + + The *spin/cg* and *spin/lbfgs* styles can be used + for magnetic NEB calculations only if the line search procedure + is deactivated. See :doc:`neb/spin ` for more explanation. + Restrictions """""""""""" @@ -68,14 +108,24 @@ freedom for a frozen lattice configuration. Related commands """""""""""""""" -:doc:`min\_style `, :doc:`minimize `, +:doc:`min\_style `, :doc:`minimize `, :doc:`min\_modify ` Default """"""" -The option defaults are *alpha\_damp* = 1.0 and *discrete\_factor* = -10.0. +The option defaults are *alpha\_damp* = 1.0, *discrete\_factor* = +10.0, *line* = spin\_none and *norm* = euclidean. + + +---------- + + +.. _Ivanov1: + + + +**(Ivanov)** Ivanov, Uzdin, Jonsson. arXiv preprint arXiv:1904.02669, (2019). .. _lws: http://lammps.sandia.gov diff --git a/doc/rst/min_style.rst b/doc/rst/min_style.rst index faf42a20e6..91accc7967 100644 --- a/doc/rst/min_style.rst +++ b/doc/rst/min_style.rst @@ -11,7 +11,7 @@ Syntax min_style style -* style = *cg* or *hftn* or *sd* or *quickmin* or *fire* or *spin* +* style = *cg* or *hftn* or *sd* or *quickmin* or *fire* or *spin* or *spin/cg* or *spin/lbfgs* Examples """""""" @@ -67,13 +67,27 @@ the velocity non-parallel to the current force vector. The velocity of each atom is initialized to 0.0 by this style, at the beginning of a minimization. -Style *spin* is a damped spin dynamics with an adaptive +Style *spin* is a damped spin dynamics with an adaptive timestep. -See the :doc:`min/spin ` doc page for more information. + +Style *spin/cg* uses an orthogonal spin optimization (OSO) +combined to a conjugate gradient (CG) approach to minimize spin +configurations. + +Style *spin/lbfgs* uses an orthogonal spin optimization (OSO) +combined to a limited-memory Broyden-Fletcher-Goldfarb-Shanno +(LBFGS) approach to minimize spin configurations. + +See the :doc:`min/spin ` doc page for more information +about the *spin*\ , *spin/cg* and *spin/lbfgs* styles. Either the *quickmin* and *fire* styles are useful in the context of nudged elastic band (NEB) calculations via the :doc:`neb ` command. +Either the *spin*\ , *spin/cg* and *spin/lbfgs* styles are useful +in the context of magnetic geodesic nudged elastic band (GNEB) calculations +via the :doc:`neb/spin ` command. + .. note:: The damped dynamic minimizers use whatever timestep you have @@ -83,9 +97,36 @@ nudged elastic band (NEB) calculations via the :doc:`neb ` command. .. note:: - The *quickmin*\ , *fire*\ , and *hftn* styles do not yet support the - use of the :doc:`fix box/relax ` command or minimizations - involving the electron radius in :doc:`eFF ` models. + The *quickmin*\ , *fire*\ , *hftn*\ , and *cg/kk* styles do not yet + support the use of the :doc:`fix box/relax ` command or + minimizations involving the electron radius in :doc:`eFF ` + models. + + +---------- + + +Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are +functionally the same as the corresponding style without the suffix. +They have been optimized to run faster, depending on your available +hardware, as discussed on the :doc:`Speed packages ` doc +page. The accelerated styles take the same arguments and should +produce the same results, except for round-off and precision issues. + +These accelerated styles are part of the GPU, USER-INTEL, KOKKOS, +USER-OMP and OPT packages, respectively. They are only enabled if +LAMMPS was built with those packages. See the :doc:`Build package ` doc page for more info. + +You can specify the accelerated styles explicitly in your input script +by including their suffix, or you can use the :doc:`-suffix command-line switch ` when you invoke LAMMPS, or you can use the +:doc:`suffix ` command in your input script. + +See the :doc:`Speed packages ` doc page for more +instructions on how to use the accelerated styles effectively. + + +---------- + Restrictions """""""""""" diff --git a/doc/rst/minimize.rst b/doc/rst/minimize.rst index 5365987b0c..668759401e 100644 --- a/doc/rst/minimize.rst +++ b/doc/rst/minimize.rst @@ -3,6 +3,9 @@ minimize command ================ +minimize/kk command +=================== + Syntax """""" @@ -112,12 +115,13 @@ The minimization procedure stops if any of several criteria are met: .. note:: - the :doc:`minimization style ` *spin* replaces + the :doc:`minimization style ` *spin*\ , + *spin/cg*\ , and *spin/lbfgs* replace the force tolerance *ftol* by a torque tolerance. - The minimization procedure stops if the 2-norm (length) of the - global torque vector (defined as the cross product between the - spins and their precession vectors omega) is less than *ftol*\ , - or if any of the other criteria are met. + The minimization procedure stops if the 2-norm (length) of the torque vector on atom + (defined as the cross product between the + atomic spin and its precession vectors omega) is less than *ftol*\ , + or if any of the other criteria are met. Torque have the same units as the energy. .. note:: @@ -277,6 +281,28 @@ that can be used include: ---------- +Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are +functionally the same as the corresponding style without the suffix. +They have been optimized to run faster, depending on your available +hardware, as discussed on the :doc:`Speed packages ` doc +page. The accelerated styles take the same arguments and should +produce the same results, except for round-off and precision issues. + +These accelerated styles are part of the GPU, USER-INTEL, KOKKOS, +USER-OMP and OPT packages, respectively. They are only enabled if +LAMMPS was built with those packages. See the :doc:`Build package ` doc page for more info. + +You can specify the accelerated styles explicitly in your input script +by including their suffix, or you can use the :doc:`-suffix command-line switch ` when you invoke LAMMPS, or you can use the +:doc:`suffix ` command in your input script. + +See the :doc:`Speed packages ` doc page for more +instructions on how to use the accelerated styles effectively. + + +---------- + + Restrictions """""""""""" diff --git a/doc/rst/neb_spin.rst b/doc/rst/neb_spin.rst index 7956c51d13..161348e97c 100644 --- a/doc/rst/neb_spin.rst +++ b/doc/rst/neb_spin.rst @@ -52,7 +52,7 @@ and last are the end points of the transition path. GNEB is a method for finding both the spin configurations and height of the energy barrier associated with a transition state, e.g. spins to perform a collective rotation from one energy basin to -another. +another. The implementation in LAMMPS follows the discussion in the following paper: :ref:`(BessarabA) `. @@ -67,34 +67,34 @@ doc page for further discussion. .. note:: - As explained below, a GNEB calculation performs a damped dynamics - minimization across all the replicas. The :doc:`spin ` - style minimizer has to be defined in your input script. + As explained below, a GNEB calculation performs a + minimization across all the replicas. One of the :doc:`spin ` + style minimizers has to be defined in your input script. When a GNEB calculation is performed, it is assumed that each replica is running the same system, though LAMMPS does not check for this. -I.e. the simulation domain, the number of magnetic atoms, the -interaction potentials, and the starting configuration when the neb +I.e. the simulation domain, the number of magnetic atoms, the +interaction potentials, and the starting configuration when the neb command is issued should be the same for every replica. In a GNEB calculation each replica is connected to other replicas by -inter-replica nudging forces. These forces are imposed by the :doc:`fix neb/spin ` command, which must be used in conjunction -with the neb command. +inter-replica nudging forces. These forces are imposed by the :doc:`fix neb/spin ` command, which must be used in conjunction +with the neb command. The group used to define the fix neb/spin command defines the -GNEB magnetic atoms which are the only ones that inter-replica springs -are applied to. +GNEB magnetic atoms which are the only ones that inter-replica springs +are applied to. If the group does not include all magnetic atoms, then non-GNEB -magnetic atoms have no inter-replica springs and the torques they feel -and their precession motion is computed in the usual way due only -to other magnetic atoms within their replica. -Conceptually, the non-GNEB atoms provide a background force field for -the GNEB atoms. -Their magnetic spins can be allowed to evolve during the GNEB +magnetic atoms have no inter-replica springs and the torques they feel +and their precession motion is computed in the usual way due only +to other magnetic atoms within their replica. +Conceptually, the non-GNEB atoms provide a background force field for +the GNEB atoms. +Their magnetic spins can be allowed to evolve during the GNEB minimization procedure. The initial spin configuration for each of the replicas can be specified in different manners via the *file-style* setting, as -discussed below. Only atomic spins whose initial coordinates should +discussed below. Only atomic spins whose initial coordinates should differ from the current configuration need to be specified. Conceptually, the initial and final configurations for the first @@ -115,25 +115,25 @@ closer to the MEP and read them in. For a *file-style* setting of *final*\ , a filename is specified which -contains atomic and spin coordinates for zero or more atoms, in the -format described below. -For each atom that appears in the file, the new coordinates are -assigned to that atom in the final replica. Each intermediate replica -also assigns a new spin to that atom in an interpolated manner. -This is done by using the current direction of the spin at the starting -point and the read-in direction as the final point. -The "angular distance" between them is calculated, and the new direction +contains atomic and spin coordinates for zero or more atoms, in the +format described below. +For each atom that appears in the file, the new coordinates are +assigned to that atom in the final replica. Each intermediate replica +also assigns a new spin to that atom in an interpolated manner. +This is done by using the current direction of the spin at the starting +point and the read-in direction as the final point. +The "angular distance" between them is calculated, and the new direction is assigned to be a fraction of the angular distance. .. note:: - The "angular distance" between the starting and final point is - evaluated in the geodesic sense, as described in + The "angular distance" between the starting and final point is + evaluated in the geodesic sense, as described in :ref:`(BessarabA) `. .. note:: - The angular interpolation between the starting and final point + The angular interpolation between the starting and final point is achieved using Rodrigues formula: .. image:: Eqs/neb_spin_rodrigues_formula.jpg @@ -145,7 +145,7 @@ omega\_i\^nu is a rotation angle defined as: .. image:: Eqs/neb_spin_angle.jpg :align: center -with nu the image number, Q the total number of images, and +with nu the image number, Q the total number of images, and omega\_i the total rotation between the initial and final spins. k\_i defines a rotation axis such as: @@ -155,16 +155,16 @@ k\_i defines a rotation axis such as: if the initial and final spins are not aligned. If the initial and final spins are aligned, then their cross product is null, and the expression above does not apply. -If they point toward the same direction, the intermediate images +If they point toward the same direction, the intermediate images conserve the same orientation. If the initial and final spins are aligned, but point toward opposite directions, an arbitrary rotation vector belonging to -the plane perpendicular to initial and final spins is chosen. +the plane perpendicular to initial and final spins is chosen. In this case, a warning message is displayed. For a *file-style* setting of *each*\ , a filename is specified which is -assumed to be unique to each replica. -See the :doc:`neb ` documentation page for more information about this +assumed to be unique to each replica. +See the :doc:`neb ` documentation page for more information about this option. For a *file-style* setting of *none*\ , no filename is specified. Each @@ -190,9 +190,10 @@ that a long calculation can be restarted if needed. A NEB calculation proceeds in two stages, each of which is a -minimization procedure, performed via damped dynamics. To enable -this, you must first define a damped spin dynamics -:doc:`min\_style `, using the *spin* style (see +minimization procedure. To enable +this, you must first define a +:doc:`min\_style `, using either the *spin*\ , +*spin/cg*\ , or *spin/lbfgs* style (see :doc:`min\_spin ` for more information). The other styles cannot be used, since they relax the lattice degrees of freedom instead of the spins. @@ -215,9 +216,9 @@ damped dynamics is like a single timestep in a dynamics replica and its normalized distance along the reaction path (reaction coordinate RD) will be printed to the screen and log file every *Nevery* timesteps. The RD is 0 and 1 for the first and last replica. -For intermediate replicas, it is the cumulative angular distance -(normalized by the total cumulative angular distance) between adjacent -replicas, where "distance" is defined as the length of the 3N-vector of +For intermediate replicas, it is the cumulative angular distance +(normalized by the total cumulative angular distance) between adjacent +replicas, where "distance" is defined as the length of the 3N-vector of the geodesic distances in spin coordinates, with N the number of GNEB spins involved (see equation (13) in :ref:`(BessarabA) `). These outputs allow you to monitor NEB's progress in @@ -227,11 +228,11 @@ of *Nevery*\ . In the first stage of GNEB, the set of replicas should converge toward a minimum energy path (MEP) of conformational states that transition over a barrier. The MEP for a transition is defined as a sequence of -3N-dimensional spin states, each of which has a potential energy -gradient parallel to the MEP itself. -The configuration of highest energy along a MEP corresponds to a saddle -point. The replica states will also be roughly equally spaced along -the MEP due to the inter-replica nudging force added by the +3N-dimensional spin states, each of which has a potential energy +gradient parallel to the MEP itself. +The configuration of highest energy along a MEP corresponds to a saddle +point. The replica states will also be roughly equally spaced along +the MEP due to the inter-replica nudging force added by the :doc:`fix neb ` command. In the second stage of GNEB, the replica with the highest energy is @@ -254,8 +255,8 @@ profile of the transition along the MEP. An atom map must be defined which it is not by default for :doc:`atom\_style atomic ` problems. The :doc:`atom\_modify map ` command can be used to do this. -An initial value can be defined for the timestep. Although, the *spin* -minimization algorithm is an adaptive timestep methodology, so that +An initial value can be defined for the timestep. Although, the *spin* +minimization algorithm is an adaptive timestep methodology, so that this timestep is likely to evolve during the calculation. The minimizers in LAMMPS operate on all spins in your system, even @@ -282,7 +283,7 @@ lines contain the following information: ... IDN gN yN zN sxN syN szN -The fields are the atom ID, the norm of the associated magnetic spin, +The fields are the atom ID, the norm of the associated magnetic spin, followed by the *x,y,z* coordinates and the *sx,sy,sz* spin coordinates. The lines can be listed in any order. Additional trailing information on the line is OK, such as a comment. @@ -316,22 +317,22 @@ reaction coordinate and potential energy of each replica. The "maximum torque per replica" is the two-norm of the 3N-length vector given by the cross product of a spin by its -precession vector omega, in each replica, maximized across replicas, +precession vector omega, in each replica, maximized across replicas, which is what the *ttol* setting is checking against. In this case, N is all the atoms in each replica. The "maximum torque per atom" is the maximum torque component of any atom in any replica. The potential -gradients are the two-norm of the 3N-length magnetic precession vector -solely due to the interaction potential i.e. without adding in -inter-replica forces, and projected along the path tangent (as detailed +gradients are the two-norm of the 3N-length magnetic precession vector +solely due to the interaction potential i.e. without adding in +inter-replica forces, and projected along the path tangent (as detailed in Appendix D of :ref:`(BessarabA) `). The "reaction coordinate" (RD) for each replica is the two-norm of the 3N-length vector of geodesic distances between its spins and the preceding -replica's spins (see equation (13) of :ref:`(BessarabA) `), added to -the RD of the preceding replica. The RD of the first replica RD1 = 0.0; -the RD of the final replica RDN = RDT, the total reaction coordinate. -The normalized RDs are divided by RDT, so that they form a monotonically -increasing sequence from zero to one. When computing RD, N only includes +replica's spins (see equation (13) of :ref:`(BessarabA) `), added to +the RD of the preceding replica. The RD of the first replica RD1 = 0.0; +the RD of the final replica RDN = RDT, the total reaction coordinate. +The normalized RDs are divided by RDT, so that they form a monotonically +increasing sequence from zero to one. When computing RD, N only includes the spins being operated on by the fix neb/spin command. The forward (reverse) energy barrier is the potential energy of the @@ -339,12 +340,12 @@ highest replica minus the energy of the first (last) replica. Supplementary information for all replicas can be printed out to the screen and master log.lammps file by adding the verbose keyword. This -information include the following. -The "GradVidottan" are the projections of the potential gradient for -the replica i on its tangent vector (as detailed in Appendix D of +information include the following. +The "GradVidottan" are the projections of the potential gradient for +the replica i on its tangent vector (as detailed in Appendix D of :ref:`(BessarabA) `). -The "DNi" are the non normalized geodesic distances (see equation (13) -of :ref:`(BessarabA) `), between a replica i and the next replica +The "DNi" are the non normalized geodesic distances (see equation (13) +of :ref:`(BessarabA) `), between a replica i and the next replica i+1. For the last replica, this distance is not defined and a "NAN" value is the corresponding output. @@ -372,7 +373,7 @@ restart the calculation from an intermediate point with altered parameters. A c file script in provided in the tool/spin/interpolate\_gneb -directory, that interpolates the MEP given the information provided +directory, that interpolates the MEP given the information provided by the verbose output option (as detailed in Appendix D of :ref:`(BessarabA) `). @@ -388,6 +389,9 @@ This command can only be used if LAMMPS was built with the SPIN package. See the :doc:`Build package ` doc page for more info. +For magnetic GNEB calculations, only *spin\_none* value for *line* keyword can be used +when styles *spin/cg* and *spin/lbfgs* are employed. + ---------- diff --git a/doc/rst/package.rst b/doc/rst/package.rst index 4bc2ef429c..804b2e126e 100644 --- a/doc/rst/package.rst +++ b/doc/rst/package.rst @@ -441,113 +441,113 @@ processes/threads used for LAMMPS. ---------- -The *kokkos* style invokes settings associated with the use of the +The *kokkos* style invokes settings associated with the use of the KOKKOS package. -All of the settings are optional keyword/value pairs. Each has a default +All of the settings are optional keyword/value pairs. Each has a default value as listed below. -The *neigh* keyword determines how neighbor lists are built. A value of -*half* uses a thread-safe variant of half-neighbor lists, the same as -used by most pair styles in LAMMPS, which is the default when running on +The *neigh* keyword determines how neighbor lists are built. A value of +*half* uses a thread-safe variant of half-neighbor lists, the same as +used by most pair styles in LAMMPS, which is the default when running on CPUs (i.e. the Kokkos CUDA back end is not enabled). -A value of *full* uses a full neighbor lists and is the default when -running on GPUs. This performs twice as much computation as the *half* -option, however that is often a win because it is thread-safe and -doesn't require atomic operations in the calculation of pair forces. For -that reason, *full* is the default setting for GPUs. However, when -running on CPUs, a *half* neighbor list is the default because it are -often faster, just as it is for non-accelerated pair styles. Similarly, -the *neigh/qeq* keyword determines how neighbor lists are built for :doc:`fix qeq/reax/kk `. If not explicitly set, the value of +A value of *full* uses a full neighbor lists and is the default when +running on GPUs. This performs twice as much computation as the *half* +option, however that is often a win because it is thread-safe and +doesn't require atomic operations in the calculation of pair forces. For +that reason, *full* is the default setting for GPUs. However, when +running on CPUs, a *half* neighbor list is the default because it are +often faster, just as it is for non-accelerated pair styles. Similarly, +the *neigh/qeq* keyword determines how neighbor lists are built for :doc:`fix qeq/reax/kk `. If not explicitly set, the value of *neigh/qeq* will match *neigh*\ . -If the *neigh/thread* keyword is set to *off*\ , then the KOKKOS package -threads only over atoms. However, for small systems, this may not expose -enough parallelism to keep a GPU busy. When this keyword is set to *on*\ , -the KOKKOS package threads over both atoms and neighbors of atoms. When -using *neigh/thread* *on*\ , a full neighbor list must also be used. Using -*neigh/thread* *on* may be slower for large systems, so this this option -is turned on by default only when there are 16K atoms or less owned by -an MPI rank and when using a full neighbor list. Not all KOKKOS-enabled -potentials support this keyword yet, and only thread over atoms. Many -simple pair-wise potentials such as Lennard-Jones do support threading +If the *neigh/thread* keyword is set to *off*\ , then the KOKKOS package +threads only over atoms. However, for small systems, this may not expose +enough parallelism to keep a GPU busy. When this keyword is set to *on*\ , +the KOKKOS package threads over both atoms and neighbors of atoms. When +using *neigh/thread* *on*\ , a full neighbor list must also be used. Using +*neigh/thread* *on* may be slower for large systems, so this this option +is turned on by default only when there are 16K atoms or less owned by +an MPI rank and when using a full neighbor list. Not all KOKKOS-enabled +potentials support this keyword yet, and only thread over atoms. Many +simple pair-wise potentials such as Lennard-Jones do support threading over both atoms and neighbors. -The *newton* keyword sets the Newton flags for pairwise and bonded -interactions to *off* or *on*\ , the same as the :doc:`newton ` -command allows. The default for GPUs is *off* because this will almost -always give better performance for the KOKKOS package. This means more -computation is done, but less communication. However, when running on -CPUs a value of *on* is the default since it can often be faster, just +The *newton* keyword sets the Newton flags for pairwise and bonded +interactions to *off* or *on*\ , the same as the :doc:`newton ` +command allows. The default for GPUs is *off* because this will almost +always give better performance for the KOKKOS package. This means more +computation is done, but less communication. However, when running on +CPUs a value of *on* is the default since it can often be faster, just as it is for non-accelerated pair styles -The *binsize* keyword sets the size of bins used to bin atoms in -neighbor list builds. The same value can be set by the :doc:`neigh\_modify binsize ` command. Making it an option in the package -kokkos command allows it to be set from the command line. The default -value for CPUs is 0.0, which means the LAMMPS default will be used, -which is bins = 1/2 the size of the pairwise cutoff + neighbor skin -distance. This is fine when neighbor lists are built on the CPU. For GPU -builds, a 2x larger binsize equal to the pairwise cutoff + neighbor skin -is often faster, which is the default. Note that if you use a -longer-than-usual pairwise cutoff, e.g. to allow for a smaller fraction -of KSpace work with a :doc:`long-range Coulombic solver ` -because the GPU is faster at performing pairwise interactions, then this -rule of thumb may give too large a binsize and the default should be +The *binsize* keyword sets the size of bins used to bin atoms in +neighbor list builds. The same value can be set by the :doc:`neigh\_modify binsize ` command. Making it an option in the package +kokkos command allows it to be set from the command line. The default +value for CPUs is 0.0, which means the LAMMPS default will be used, +which is bins = 1/2 the size of the pairwise cutoff + neighbor skin +distance. This is fine when neighbor lists are built on the CPU. For GPU +builds, a 2x larger binsize equal to the pairwise cutoff + neighbor skin +is often faster, which is the default. Note that if you use a +longer-than-usual pairwise cutoff, e.g. to allow for a smaller fraction +of KSpace work with a :doc:`long-range Coulombic solver ` +because the GPU is faster at performing pairwise interactions, then this +rule of thumb may give too large a binsize and the default should be overridden with a smaller value. -The *comm* and *comm/exchange* and *comm/forward* and *comm/reverse* -keywords determine whether the host or device performs the packing and -unpacking of data when communicating per-atom data between processors. -"Exchange" communication happens only on timesteps that neighbor lists -are rebuilt. The data is only for atoms that migrate to new processors. -"Forward" communication happens every timestep. "Reverse" communication -happens every timestep if the *newton* option is on. The data is for -atom coordinates and any other atom properties that needs to be updated +The *comm* and *comm/exchange* and *comm/forward* and *comm/reverse* +keywords determine whether the host or device performs the packing and +unpacking of data when communicating per-atom data between processors. +"Exchange" communication happens only on timesteps that neighbor lists +are rebuilt. The data is only for atoms that migrate to new processors. +"Forward" communication happens every timestep. "Reverse" communication +happens every timestep if the *newton* option is on. The data is for +atom coordinates and any other atom properties that needs to be updated for ghost atoms owned by each processor. -The *comm* keyword is simply a short-cut to set the same value for both +The *comm* keyword is simply a short-cut to set the same value for both the *comm/exchange* and *comm/forward* and *comm/reverse* keywords. -The value options for all 3 keywords are *no* or *host* or *device*\ . A -value of *no* means to use the standard non-KOKKOS method of -packing/unpacking data for the communication. A value of *host* means to -use the host, typically a multi-core CPU, and perform the -packing/unpacking in parallel with threads. A value of *device* means to -use the device, typically a GPU, to perform the packing/unpacking +The value options for all 3 keywords are *no* or *host* or *device*\ . A +value of *no* means to use the standard non-KOKKOS method of +packing/unpacking data for the communication. A value of *host* means to +use the host, typically a multi-core CPU, and perform the +packing/unpacking in parallel with threads. A value of *device* means to +use the device, typically a GPU, to perform the packing/unpacking operation. -The optimal choice for these keywords depends on the input script and -the hardware used. The *no* value is useful for verifying that the -Kokkos-based *host* and *device* values are working correctly. It is the +The optimal choice for these keywords depends on the input script and +the hardware used. The *no* value is useful for verifying that the +Kokkos-based *host* and *device* values are working correctly. It is the default when running on CPUs since it is usually the fastest. -When running on CPUs or Xeon Phi, the *host* and *device* values work -identically. When using GPUs, the *device* value is the default since it -will typically be optimal if all of your styles used in your input -script are supported by the KOKKOS package. In this case data can stay -on the GPU for many timesteps without being moved between the host and -GPU, if you use the *device* value. If your script uses styles (e.g. -fixes) which are not yet supported by the KOKKOS package, then data has -to be move between the host and device anyway, so it is typically faster -to let the host handle communication, by using the *host* value. Using -*host* instead of *no* will enable use of multiple threads to -pack/unpack communicated data. When running small systems on a GPU, -performing the exchange pack/unpack on the host CPU can give speedup +When running on CPUs or Xeon Phi, the *host* and *device* values work +identically. When using GPUs, the *device* value is the default since it +will typically be optimal if all of your styles used in your input +script are supported by the KOKKOS package. In this case data can stay +on the GPU for many timesteps without being moved between the host and +GPU, if you use the *device* value. If your script uses styles (e.g. +fixes) which are not yet supported by the KOKKOS package, then data has +to be move between the host and device anyway, so it is typically faster +to let the host handle communication, by using the *host* value. Using +*host* instead of *no* will enable use of multiple threads to +pack/unpack communicated data. When running small systems on a GPU, +performing the exchange pack/unpack on the host CPU can give speedup since it reduces the number of CUDA kernel launches. -The *cuda/aware* keyword chooses whether CUDA-aware MPI will be used. When -this keyword is set to *on*\ , buffers in GPU memory are passed directly -through MPI send/receive calls. This reduces overhead of first copying -the data to the host CPU. However CUDA-aware MPI is not supported on all -systems, which can lead to segmentation faults and would require using a -value of *off*\ . If LAMMPS can safely detect that CUDA-aware MPI is not -available (currently only possible with OpenMPI v2.0.0 or later), then -the *cuda/aware* keyword is automatically set to *off* by default. When -the *cuda/aware* keyword is set to *off* while any of the *comm* -keywords are set to *device*\ , the value for these *comm* keywords will -be automatically changed to *host*\ . This setting has no effect if not -running on GPUs. CUDA-aware MPI is available for OpenMPI 1.8 (or later +The *cuda/aware* keyword chooses whether CUDA-aware MPI will be used. When +this keyword is set to *on*\ , buffers in GPU memory are passed directly +through MPI send/receive calls. This reduces overhead of first copying +the data to the host CPU. However CUDA-aware MPI is not supported on all +systems, which can lead to segmentation faults and would require using a +value of *off*\ . If LAMMPS can safely detect that CUDA-aware MPI is not +available (currently only possible with OpenMPI v2.0.0 or later), then +the *cuda/aware* keyword is automatically set to *off* by default. When +the *cuda/aware* keyword is set to *off* while any of the *comm* +keywords are set to *device*\ , the value for these *comm* keywords will +be automatically changed to *host*\ . This setting has no effect if not +running on GPUs. CUDA-aware MPI is available for OpenMPI 1.8 (or later versions), Mvapich2 1.9 (or later) when the "MV2\_USE\_CUDA" environment variable is set to "1", CrayMPI, and IBM Spectrum MPI when the "-gpu" flag is used. @@ -665,16 +665,16 @@ Phi co-processor support. These settings are made automatically if the not used, you must invoke the package intel command in your input script or via the "-pk intel" :doc:`command-line switch `. -For the KOKKOS package, the option defaults for GPUs are neigh = full, -neigh/qeq = full, newton = off, binsize for GPUs = 2x LAMMPS default -value, comm = device, cuda/aware = on. When LAMMPS can safely detect -that CUDA-aware MPI is not available, the default value of cuda/aware -becomes "off". For CPUs or Xeon Phis, the option defaults are neigh = -half, neigh/qeq = half, newton = on, binsize = 0.0, and comm = no. The -option neigh/thread = on when there are 16K atoms or less on an MPI -rank, otherwise it is "off". These settings are made automatically by -the required "-k on" :doc:`command-line switch `. You can -change them by using the package kokkos command in your input script or +For the KOKKOS package, the option defaults for GPUs are neigh = full, +neigh/qeq = full, newton = off, binsize for GPUs = 2x LAMMPS default +value, comm = device, cuda/aware = on. When LAMMPS can safely detect +that CUDA-aware MPI is not available, the default value of cuda/aware +becomes "off". For CPUs or Xeon Phis, the option defaults are neigh = +half, neigh/qeq = half, newton = on, binsize = 0.0, and comm = no. The +option neigh/thread = on when there are 16K atoms or less on an MPI +rank, otherwise it is "off". These settings are made automatically by +the required "-k on" :doc:`command-line switch `. You can +change them by using the package kokkos command in your input script or via the :doc:`-pk kokkos command-line switch `. For the OMP package, the default is Nthreads = 0 and the option diff --git a/doc/rst/pair_e3b.rst b/doc/rst/pair_e3b.rst index 7887aca7fc..73afdd7f53 100644 --- a/doc/rst/pair_e3b.rst +++ b/doc/rst/pair_e3b.rst @@ -26,8 +26,8 @@ Syntax .. parsed-literal:: *preset* arg = *2011* or *2015* = which set of predefined parameters to use - 2011 = use the potential parameters from :ref:`(Tainter 2011) ` - 2015 = use the potential parameters from :ref:`(Tainter 2015) ` + 2011 = use the potential parameters from :ref:`(Tainter 2011) ` + 2015 = use the potential parameters from :ref:`(Tainter 2015) ` *Ea* arg = three-body energy for type A hydrogen bonding interactions (energy units) *Eb* arg = three-body energy for type B hydrogen bonding interactions (energy units) *Ec* arg = three-body energy for type C hydrogen bonding interactions (energy units) diff --git a/doc/rst/pair_granular.rst b/doc/rst/pair_granular.rst index c48f35ef62..d5f522462d 100644 --- a/doc/rst/pair_granular.rst +++ b/doc/rst/pair_granular.rst @@ -100,7 +100,7 @@ on particle *i* due to contact with particle *j* is given by: \begin{equation}\mathbf{F}_{ne, Hooke} = k_N \delta_{ij} \mathbf{n}\end{equation} -Where :math:`\delta = R_i + R_j - \|\mathbf{r}_{ij}\|` is the particle +Where :math:`\delta_{ij} = R_i + R_j - \|\mathbf{r}_{ij}\|` is the particle overlap, :math:`R_i, R_j` are the particle radii, :math:`\mathbf{r}_{ij} = \mathbf{r}_i - \mathbf{r}_j` is the vector separating the two particle centers (note the i-j ordering so that :math:`F_{ne}` is positive for repulsion), and :math:`\mathbf{n} = \frac{\mathbf{r}_{ij}}{\|\mathbf{r}_{ij}\|}`. Therefore, @@ -181,7 +181,7 @@ following general form: \begin{equation}\mathbf{F}_{n,damp} = -\eta_n \mathbf{v}_{n,rel}\end{equation} -Here, :math:`\mathbf{v}_{n,rel} = (\mathbf{v}_j - \mathbf{v}_i) \cdot \mathbf{n}` is the component of relative velocity along +Here, :math:`\mathbf{v}_{n,rel} = (\mathbf{v}_j - \mathbf{v}_i) \cdot \mathbf{n} \mathbf{n}` is the component of relative velocity along :math:`\mathbf{n}`. The optional *damping* keyword to the *pair\_coeff* command followed by @@ -312,15 +312,16 @@ the normal damping :math:`\eta_n` (see above): \begin{equation}\eta_t = -x_{\gamma,t} \eta_n\end{equation} -The normal damping prefactor :math:`\eta_n` is determined by the choice of -the *damping* keyword, as discussed above. Thus, the *damping* +The normal damping prefactor :math:`\eta_n` is determined by the choice +of the *damping* keyword, as discussed above. Thus, the *damping* keyword also affects the tangential damping. The parameter :math:`x_{\gamma,t}` is a scaling coefficient. Several works in the literature use :math:`x_{\gamma,t} = 1` (:ref:`Marshall `, :ref:`Tsuji et al `, :ref:`Silbert et al `). The relative tangential velocity at the point of contact is given by -:math:`\mathbf{v}_{t, rel} = \mathbf{v}_{t} - (R_i\Omega_i + R_j\Omega_j) \times \mathbf{n}`, where :math:`\mathbf{v}_{t} = \mathbf{v}_r - \mathbf{v}_r\cdot\mathbf{n}`, :math:`\mathbf{v}_r = \mathbf{v}_j - \mathbf{v}_i`. The direction of the applied force -is :math:`\mathbf{t} = \mathbf{v_{t,rel}}/\|\mathbf{v_{t,rel}}\|`. +:math:`\mathbf{v}_{t, rel} = \mathbf{v}_{t} - (R_i\Omega_i + R_j\Omega_j) \times \mathbf{n}`, where :math:`\mathbf{v}_{t} = \mathbf{v}_r - \mathbf{v}_r\cdot\mathbf{n}{n}`, +:math:`\mathbf{v}_r = \mathbf{v}_j - \mathbf{v}_i`. +The direction of the applied force is :math:`\mathbf{t} = \mathbf{v_{t,rel}}/\|\mathbf{v_{t,rel}}\|` . The normal force value :math:`F_{n0}` used to compute the critical force depends on the form of the contact model. For non-cohesive models @@ -428,7 +429,8 @@ option by an additional factor of *a*\ , the radius of the contact region. The t \begin{equation}\mathbf{F}_t = -min(\mu_t F_{n0}, \|-k_t a \mathbf{\xi} + \mathbf{F}_\mathrm{t,damp}\|) \mathbf{t}\end{equation} -Here, *a* is the radius of the contact region, given by :math:`a = \delta R` for all normal contact models, except for *jkr*\ , where it is given +Here, *a* is the radius of the contact region, given by :math:`a =\sqrt{R\delta}` +for all normal contact models, except for *jkr*\ , where it is given implicitly by :math:`\delta = a^2/R - 2\sqrt{\pi \gamma a/E}`, see discussion above. To match the Mindlin solution, one should set :math:`k_t = 8G`, where :math:`G` is the shear modulus, related to Young's modulus :math:`E` by :math:`G = E/(2(1+\nu))`, where :math:`\nu` is Poisson's ratio. This @@ -716,7 +718,7 @@ The single() function of these pair styles returns 0.0 for the energy of a pairwise interaction, since energy is not conserved in these dissipative potentials. It also returns only the normal component of the pairwise interaction force. However, the single() function also -calculates 10 extra pairwise quantities. The first 3 are the +calculates 12 extra pairwise quantities. The first 3 are the components of the tangential force between particles I and J, acting on particle I. The 4th is the magnitude of this tangential force. The next 3 (5-7) are the components of the rolling torque acting on diff --git a/doc/rst/pair_hybrid.rst b/doc/rst/pair_hybrid.rst deleted file mode 100644 index 3ee9c19428..0000000000 --- a/doc/rst/pair_hybrid.rst +++ /dev/null @@ -1,444 +0,0 @@ -.. index:: pair\_style hybrid - -pair\_style hybrid command -========================== - -pair\_style hybrid/kk command -============================= - -pair\_style hybrid/overlay command -================================== - -pair\_style hybrid/overlay/kk command -===================================== - -Syntax -"""""" - - -.. parsed-literal:: - - pair_style hybrid style1 args style2 args ... - pair_style hybrid/overlay style1 args style2 args ... - -* style1,style2 = list of one or more pair styles and their arguments - -Examples -"""""""" - - -.. parsed-literal:: - - pair_style hybrid lj/cut/coul/cut 10.0 eam lj/cut 5.0 - pair_coeff 1\*2 1\*2 eam niu3 - pair_coeff 3 3 lj/cut/coul/cut 1.0 1.0 - pair_coeff 1\*2 3 lj/cut 0.5 1.2 - - pair_style hybrid/overlay lj/cut 2.5 coul/long 2.0 - pair_coeff \* \* lj/cut 1.0 1.0 - pair_coeff \* \* coul/long - -Description -""""""""""" - -The *hybrid* and *hybrid/overlay* styles enable the use of multiple -pair styles in one simulation. With the *hybrid* style, exactly one -pair style is assigned to each pair of atom types. With the -*hybrid/overlay* style, one or more pair styles can be assigned to -each pair of atom types. The assignment of pair styles to type pairs -is made via the :doc:`pair\_coeff ` command. - -Here are two examples of hybrid simulations. The *hybrid* style could -be used for a simulation of a metal droplet on a LJ surface. The -metal atoms interact with each other via an *eam* potential, the -surface atoms interact with each other via a *lj/cut* potential, and -the metal/surface interaction is also computed via a *lj/cut* -potential. The *hybrid/overlay* style could be used as in the 2nd -example above, where multiple potentials are superposed in an additive -fashion to compute the interaction between atoms. In this example, -using *lj/cut* and *coul/long* together gives the same result as if -the *lj/cut/coul/long* potential were used by itself. In this case, -it would be more efficient to use the single combined potential, but -in general any combination of pair potentials can be used together in -to produce an interaction that is not encoded in any single pair\_style -file, e.g. adding Coulombic forces between granular particles. - -All pair styles that will be used are listed as "sub-styles" following -the *hybrid* or *hybrid/overlay* keyword, in any order. Each -sub-style's name is followed by its usual arguments, as illustrated in -the example above. See the doc pages of individual pair styles for a -listing and explanation of the appropriate arguments. - -Note that an individual pair style can be used multiple times as a -sub-style. For efficiency this should only be done if your model -requires it. E.g. if you have different regions of Si and C atoms and -wish to use a Tersoff potential for pure Si for one set of atoms, and -a Tersoff potential for pure C for the other set (presumably with some -3rd potential for Si-C interactions), then the sub-style *tersoff* -could be listed twice. But if you just want to use a Lennard-Jones or -other pairwise potential for several different atom type pairs in your -model, then you should just list the sub-style once and use the -pair\_coeff command to assign parameters for the different type pairs. - -.. note:: - - There is one exception to this option to list an individual - pair style multiple times: GPU-enabled pair styles in the GPU package. - This is because the GPU package currently assumes that only one - instance of a pair style is being used. - -In the pair\_coeff commands, the name of a pair style must be added -after the I,J type specification, with the remaining coefficients -being those appropriate to that style. If the pair style is used -multiple times in the pair\_style command, then an additional numeric -argument must also be specified which is a number from 1 to M where M -is the number of times the sub-style was listed in the pair style -command. The extra number indicates which instance of the sub-style -these coefficients apply to. - -For example, consider a simulation with 3 atom types: types 1 and 2 -are Ni atoms, type 3 are LJ atoms with charges. The following -commands would set up a hybrid simulation: - - -.. parsed-literal:: - - pair_style hybrid eam/alloy lj/cut/coul/cut 10.0 lj/cut 8.0 - pair_coeff \* \* eam/alloy nialhjea Ni Ni NULL - pair_coeff 3 3 lj/cut/coul/cut 1.0 1.0 - pair_coeff 1\*2 3 lj/cut 0.8 1.3 - -As an example of using the same pair style multiple times, consider a -simulation with 2 atom types. Type 1 is Si, type 2 is C. The -following commands would model the Si atoms with Tersoff, the C atoms -with Tersoff, and the cross-interactions with Lennard-Jones: - - -.. parsed-literal:: - - pair_style hybrid lj/cut 2.5 tersoff tersoff - pair_coeff \* \* tersoff 1 Si.tersoff Si NULL - pair_coeff \* \* tersoff 2 C.tersoff NULL C - pair_coeff 1 2 lj/cut 1.0 1.5 - -If pair coefficients are specified in the data file read via the -:doc:`read\_data ` command, then the same rule applies. -E.g. "eam/alloy" or "lj/cut" must be added after the atom type, for -each line in the "Pair Coeffs" section, e.g. - - -.. parsed-literal:: - - Pair Coeffs - - 1 lj/cut/coul/cut 1.0 1.0 - ... - -Note that the pair\_coeff command for some potentials such as -:doc:`pair\_style eam/alloy ` includes a mapping specification -of elements to all atom types, which in the hybrid case, can include -atom types not assigned to the *eam/alloy* potential. The NULL -keyword is used by many such potentials (eam/alloy, Tersoff, AIREBO, -etc), to denote an atom type that will be assigned to a different -sub-style. - -For the *hybrid* style, each atom type pair I,J is assigned to exactly -one sub-style. Just as with a simulation using a single pair style, -if you specify the same atom type pair in a second pair\_coeff command, -the previous assignment will be overwritten. - -For the *hybrid/overlay* style, each atom type pair I,J can be -assigned to one or more sub-styles. If you specify the same atom type -pair in a second pair\_coeff command with a new sub-style, then the -second sub-style is added to the list of potentials that will be -calculated for two interacting atoms of those types. If you specify -the same atom type pair in a second pair\_coeff command with a -sub-style that has already been defined for that pair of atoms, then -the new pair coefficients simply override the previous ones, as in the -normal usage of the pair\_coeff command. E.g. these two sets of -commands are the same: - - -.. parsed-literal:: - - pair_style lj/cut 2.5 - pair_coeff \* \* 1.0 1.0 - pair_coeff 2 2 1.5 0.8 - - pair_style hybrid/overlay lj/cut 2.5 - pair_coeff \* \* lj/cut 1.0 1.0 - pair_coeff 2 2 lj/cut 1.5 0.8 - -Coefficients must be defined for each pair of atoms types via the -:doc:`pair\_coeff ` command as described above, or in the -data file or restart files read by the :doc:`read\_data ` or -:doc:`read\_restart ` commands, or by mixing as described -below. - -For both the *hybrid* and *hybrid/overlay* styles, every atom type -pair I,J (where I <= J) must be assigned to at least one sub-style via -the :doc:`pair\_coeff ` command as in the examples above, or -in the data file read by the :doc:`read\_data `, or by mixing -as described below. - -If you want there to be no interactions between a particular pair of -atom types, you have 3 choices. You can assign the type pair to some -sub-style and use the :doc:`neigh\_modify exclude type ` -command. You can assign it to some sub-style and set the coefficients -so that there is effectively no interaction (e.g. epsilon = 0.0 in a -LJ potential). Or, for *hybrid* and *hybrid/overlay* simulations, you -can use this form of the pair\_coeff command in your input script: - - -.. parsed-literal:: - - pair_coeff 2 3 none - -or this form in the "Pair Coeffs" section of the data file: - - -.. parsed-literal:: - - 3 none - -If an assignment to *none* is made in a simulation with the -*hybrid/overlay* pair style, it wipes out all previous assignments of -that atom type pair to sub-styles. - -Note that you may need to use an :doc:`atom\_style ` hybrid -command in your input script, if atoms in the simulation will need -attributes from several atom styles, due to using multiple pair -potentials. - - ----------- - - -Different force fields (e.g. CHARMM vs AMBER) may have different rules -for applying weightings that change the strength of pairwise -interactions between pairs of atoms that are also 1-2, 1-3, and 1-4 -neighbors in the molecular bond topology, as normally set by the -:doc:`special\_bonds ` command. Different weights can be -assigned to different pair hybrid sub-styles via the :doc:`pair\_modify special ` command. This allows multiple force fields -to be used in a model of a hybrid system, however, there is no consistent -approach to determine parameters automatically for the interactions -between the two force fields, this is only recommended when particles -described by the different force fields do not mix. - -Here is an example for mixing CHARMM and AMBER: The global *amber* -setting sets the 1-4 interactions to non-zero scaling factors and -then overrides them with 0.0 only for CHARMM: - - -.. parsed-literal:: - - special_bonds amber - pair_hybrid lj/charmm/coul/long 8.0 10.0 lj/cut/coul/long 10.0 - pair_modify pair lj/charmm/coul/long special lj/coul 0.0 0.0 0.0 - -The this input achieves the same effect: - - -.. parsed-literal:: - - special_bonds 0.0 0.0 0.1 - pair_hybrid lj/charmm/coul/long 8.0 10.0 lj/cut/coul/long 10.0 - pair_modify pair lj/cut/coul/long special lj 0.0 0.0 0.5 - pair_modify pair lj/cut/coul/long special coul 0.0 0.0 0.83333333 - pair_modify pair lj/charmm/coul/long special lj/coul 0.0 0.0 0.0 - -Here is an example for mixing Tersoff with OPLS/AA based on -a data file that defines bonds for all atoms where for the -Tersoff part of the system the force constants for the bonded -interactions have been set to 0. Note the global settings are -effectively *lj/coul 0.0 0.0 0.5* as required for OPLS/AA: - - -.. parsed-literal:: - - special_bonds lj/coul 1e-20 1e-20 0.5 - pair_hybrid tersoff lj/cut/coul/long 12.0 - pair_modify pair tersoff special lj/coul 1.0 1.0 1.0 - -For use with the various :doc:`compute \*/tally ` -computes, the :doc:`pair\_modify compute/tally ` -command can be used to selectively turn off processing of -the compute tally styles, for example, if those pair styles -(e.g. many-body styles) do not support this feature. - -See the :doc:`pair\_modify ` doc page for details on -the specific syntax, requirements and restrictions. - - ----------- - - -The potential energy contribution to the overall system due to an -individual sub-style can be accessed and output via the :doc:`compute pair ` command. - - ----------- - - -.. note:: - - Several of the potentials defined via the pair\_style command in - LAMMPS are really many-body potentials, such as Tersoff, AIREBO, MEAM, - ReaxFF, etc. The way to think about using these potentials in a - hybrid setting is as follows. - -A subset of atom types is assigned to the many-body potential with a -single :doc:`pair\_coeff ` command, using "\* \*" to include -all types and the NULL keywords described above to exclude specific -types not assigned to that potential. If types 1,3,4 were assigned in -that way (but not type 2), this means that all many-body interactions -between all atoms of types 1,3,4 will be computed by that potential. -Pair\_style hybrid allows interactions between type pairs 2-2, 1-2, -2-3, 2-4 to be specified for computation by other pair styles. You -could even add a second interaction for 1-1 to be computed by another -pair style, assuming pair\_style hybrid/overlay is used. - -But you should not, as a general rule, attempt to exclude the -many-body interactions for some subset of the type pairs within the -set of 1,3,4 interactions, e.g. exclude 1-1 or 1-3 interactions. That -is not conceptually well-defined for many-body interactions, since the -potential will typically calculate energies and foces for small groups -of atoms, e.g. 3 or 4 atoms, using the neighbor lists of the atoms to -find the additional atoms in the group. It is typically non-physical -to think of excluding an interaction between a particular pair of -atoms when the potential computes 3-body or 4-body interactions. - -However, you can still use the pair\_coeff none setting or the -:doc:`neigh\_modify exclude ` command to exclude certain -type pairs from the neighbor list that will be passed to a many-body -sub-style. This will alter the calculations made by a many-body -potential, since it builds its list of 3-body, 4-body, etc -interactions from the pair list. You will need to think carefully as -to whether it produces a physically meaningful result for your model. - -For example, imagine you have two atom types in your model, type 1 for -atoms in one surface, and type 2 for atoms in the other, and you wish -to use a Tersoff potential to compute interactions within each -surface, but not between surfaces. Then either of these two command -sequences would implement that model: - - -.. parsed-literal:: - - pair_style hybrid tersoff - pair_coeff \* \* tersoff SiC.tersoff C C - pair_coeff 1 2 none - - pair_style tersoff - pair_coeff \* \* SiC.tersoff C C - neigh_modify exclude type 1 2 - -Either way, only neighbor lists with 1-1 or 2-2 interactions would be -passed to the Tersoff potential, which means it would compute no -3-body interactions containing both type 1 and 2 atoms. - -Here is another example, using hybrid/overlay, to use 2 many-body -potentials together, in an overlapping manner. Imagine you have CNT -(C atoms) on a Si surface. You want to use Tersoff for Si/Si and Si/C -interactions, and AIREBO for C/C interactions. Si atoms are type 1; C -atoms are type 2. Something like this will work: - - -.. parsed-literal:: - - pair_style hybrid/overlay tersoff airebo 3.0 - pair_coeff \* \* tersoff SiC.tersoff.custom Si C - pair_coeff \* \* airebo CH.airebo NULL C - -Note that to prevent the Tersoff potential from computing C/C -interactions, you would need to modify the SiC.tersoff file to turn -off C/C interaction, i.e. by setting the appropriate coefficients to -0.0. - - ----------- - - -Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are -functionally the same as the corresponding style without the suffix. -They have been optimized to run faster, depending on your available -hardware, as discussed on the :doc:`Speed packages ` doc -page. - -Since the *hybrid* and *hybrid/overlay* styles delegate computation to -the individual sub-styles, the suffix versions of the *hybrid* and -*hybrid/overlay* styles are used to propagate the corresponding suffix -to all sub-styles, if those versions exist. Otherwise the -non-accelerated version will be used. - -The individual accelerated sub-styles are part of the GPU, USER-OMP -and OPT packages, respectively. They are only enabled if LAMMPS was -built with those packages. See the :doc:`Build package ` -doc page for more info. - -You can specify the accelerated styles explicitly in your input script -by including their suffix, or you can use the :doc:`-suffix command-line switch ` when you invoke LAMMPS, or you can use the -:doc:`suffix ` command in your input script. - -See the :doc:`Speed packages ` doc page for more -instructions on how to use the accelerated styles effectively. - - ----------- - - -**Mixing, shift, table, tail correction, restart, rRESPA info**\ : - -Any pair potential settings made via the -:doc:`pair\_modify ` command are passed along to all -sub-styles of the hybrid potential. - -For atom type pairs I,J and I != J, if the sub-style assigned to I,I -and J,J is the same, and if the sub-style allows for mixing, then the -coefficients for I,J can be mixed. This means you do not have to -specify a pair\_coeff command for I,J since the I,J type pair will be -assigned automatically to the sub-style defined for both I,I and J,J -and its coefficients generated by the mixing rule used by that -sub-style. For the *hybrid/overlay* style, there is an additional -requirement that both the I,I and J,J pairs are assigned to a single -sub-style. See the "pair\_modify" command for details of mixing rules. -See the See the doc page for the sub-style to see if allows for -mixing. - -The hybrid pair styles supports the :doc:`pair\_modify ` -shift, table, and tail options for an I,J pair interaction, if the -associated sub-style supports it. - -For the hybrid pair styles, the list of sub-styles and their -respective settings are written to :doc:`binary restart files `, so a :doc:`pair\_style ` command does -not need to specified in an input script that reads a restart file. -However, the coefficient information is not stored in the restart -file. Thus, pair\_coeff commands need to be re-specified in the -restart input script. - -These pair styles support the use of the *inner*\ , *middle*\ , and -*outer* keywords of the :doc:`run\_style respa ` command, if -their sub-styles do. - -Restrictions -"""""""""""" - - -When using a long-range Coulombic solver (via the -:doc:`kspace\_style ` command) with a hybrid pair\_style, -one or more sub-styles will be of the "long" variety, -e.g. *lj/cut/coul/long* or *buck/coul/long*\ . You must insure that the -short-range Coulombic cutoff used by each of these long pair styles is -the same or else LAMMPS will generate an error. - -Related commands -"""""""""""""""" - -:doc:`pair\_coeff ` - -**Default:** none - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/pair_kolmogorov_crespi_full.rst b/doc/rst/pair_kolmogorov_crespi_full.rst index 1cc94e2b67..8fe76c6b71 100644 --- a/doc/rst/pair_kolmogorov_crespi_full.rst +++ b/doc/rst/pair_kolmogorov_crespi_full.rst @@ -50,8 +50,8 @@ can be found in pair style :doc:`ilp/graphene/hbn `. .. note:: This potential (ILP) is intended for interlayer interactions between two - different layers of graphene. To perform a realistic simulation, this potential - must be used in combination with intralayer potential, such as + different layers of graphene. To perform a realistic simulation, this potential + must be used in combination with intralayer potential, such as :doc:`AIREBO ` or :doc:`Tersoff ` potential. To keep the intralayer properties unaffected, the interlayer interaction within the same layers should be avoided. Hence, each atom has to have a layer diff --git a/doc/rst/pair_local_density.rst b/doc/rst/pair_local_density.rst new file mode 100644 index 0000000000..2a9d4068b7 --- /dev/null +++ b/doc/rst/pair_local_density.rst @@ -0,0 +1,253 @@ +.. index:: pair\_style local/density + +pair\_style local/density command +================================= + +Syntax +"""""" + + +.. parsed-literal:: + + pair_style style arg + +* style = *local/density* +* arg = name of file containing tabulated values of local density and the potential + +Examples +"""""""" + + +.. parsed-literal:: + + pair_style local/density benzene_water.localdensity.table + + pair_style hybrid/overlay table spline 500 local/density + pair_coeff \* \* local/density benzene_water.localdensity.table + +Description +""""""""""" + +The local density (LD) potential is a mean-field manybody potential, and, in some +sense,a generalization of embedded atom models (EAM). The name "local density +potential" arises from the fact that it assigns an energy to an atom depending +on the number of neighboring atoms of given type around it within a predefined +spherical volume (i.e., within a cutoff). The bottom-up coarse-graining (CG) +literature suggests that such potentials can be widely useful in capturing +effective multibody forces in a computationally efficient manner so as to +improve the quality of CG models of implicit solvation:ref:`(Sanyal1) ` and +phase-segregation in liquid mixtures:ref:`(Sanyal2) `, and provide guidelines +to determine the extent of manybody correlations present in a CG +model.:ref:`(Rosenberger) ` The LD potential in LAMMPS is primarily +intended to be used as a corrective potential over traditional pair potentials +in bottom-up CG models, i.e., as a hybrid pair style with +other explicit pair interaction terms (e.g., table spline, Lennard Jones, etc.). +Because the LD potential is not a pair potential per se, it is implemented +simply as a single auxiliary file with all specifications that will be read +upon initialization. + +.. note:: + + Thus when used as the only interaction in the system, there is no + corresponding pair\_coeff command and when used with other pair styles using the + hybrid/overlay option, the corresponding pair\_coeff command must be supplied + \* \* as placeholders for the atom types. + + +---------- + + +**System with a single CG atom type:** + +A system of a single atom type (e.g., LJ argon) with a single local density (LD) +potential would have an energy given by: + +.. image:: Eqs/pair_local_density_energy.jpg + :align: center + +where rho\_i is the LD at atom i and F(rho) is similar in spirit to the +embedding function used in EAM potentials. The LD at atom i is given by the sum + +.. image:: Eqs/pair_local_density_ld.jpg + :align: center + +where phi is an indicator function that is one at r=0 and zero beyond a cutoff +distance R2. The choice of the functional form of phi is somewhat arbitrary, +but the following piecewise cubic function has proven sufficiently general: +:ref:`(Sanyal1) `, :ref:`(Sanyal2) ` :ref:`(Rosenberger) ` + +.. image:: Eqs/pair_local_density_indicator_func.jpg + :align: center + +The constants *c* are chosen so that the indicator function smoothly +interpolates between 1 and 0 between the distances R1 and R2, which are +called the inner and outer cutoffs, respectively. Thus phi satisfies +phi(R1) = 1, phi(R2) = dphi/dr @ (r=R1) = dphi/dr @ (r=R2) = 0. The embedding +function F(rho) may or may not have a closed-form expression. To maintain +generality, it is practically represented with a spline-interpolated table +over a predetermined range of rho. Outside of that range it simply adopts zero +values at the endpoints. + +It can be shown that the total force between two atoms due to the LD potential +takes the form of a pair force, which motivates its designation as a LAMMPS +pair style. Please see :ref:`(Sanyal1) ` for details of the derivation. + + +---------- + + +**Systems with arbitrary numbers of atom types:** + +The potential is easily generalized to systems involving multiple atom types: + +.. image:: Eqs/pair_local_density_energy_multi.jpg + :align: center + +with the LD expressed as + +.. image:: Eqs/pair_local_density_ld_multi.jpg + :align: center + +where alpha gives the type of atom i, beta the type of atom j, and the +coefficients a and b filter for atom types as specified by the user. a is +called the central atom filter as it determines to which atoms the +potential applies; a\_alpha = 1 if the LD potential applies to atom type alpha +else zero. On the other hand, b is called the neighbor atom filter because it +specifies which atom types to use in the calculation of the LD; b\_beta = 1 if +atom type beta contributes to the LD and zero otherwise. + +.. note:: + + Note that the potentials need not be symmetric with respect to atom types, + which is the reason for two distinct sets of coefficients a and b. An atom type + may contribute to the LD but not the potential, or to the potential but not the + LD. Such decisions are made by the user and should (ideally) be motivated on + physical grounds for the problem at hand. + + +---------- + + +**General form for implementation in LAMMPS:** + +Of course, a system with many atom types may have many different possible LD +potentials, each with their own atom type filters, cutoffs, and embedding +functions. The most general form of this potential as implemented in the +pair\_style local/density is: + +.. image:: Eqs/pair_local_density_energy_implement.jpg + :align: center + +where, k is an index that spans the (arbitrary) number of applied LD potentials +N\_LD. Each LD is calculated as before with: + +.. image:: Eqs/pair_local_density_ld_implement.jpg + :align: center + +The superscript on the indicator function phi simply indicates that it is +associated with specific values of the cutoff distances R1(k) and R2(k). In +summary, there may be N\_LD distinct LD potentials. With each potential type (k), +one must specify: + +* the inner and outer cutoffs as R1 and R2 +* the central type filter a(k), where k = 1,2,...N\_LD +* the neighbor type filter b(k), where k = 1,2,...N\_LD +* the LD potential function F(k)(rho), typically as a table that is later spline-interpolated + + +---------- + + +**Tabulated input file format:** + + +.. parsed-literal:: + + Line 1: comment or blank (ignored) + Line 2: comment or blank (ignored) + Line 3: N_LD N_rho (# of LD potentials and # of tabulated values, single space separated) + Line 4: blank (ignored) + Line 5: R1(k) R2(k) (lower and upper cutoffs, single space separated) + Line 6: central-types (central atom types, single space separated) + Line 7: neighbor-types (neighbor atom types single space separated) + Line 8: rho_min rho_max drho (min, max and diff. in tabulated rho values, single space separated) + Line 9: F(k)(rho_min + 0.drho) + Line 10: F(k)(rho_min + 1.drho) + Line 11: F(k)(rho_min + 2.drho) + ... + Line 9+N_rho: F(k)(rho_min + N_rho . drho) + Line 10+N_rho: blank (ignored) + + Block 2 + + Block 3 + + Block N_LD + +Lines 5 to 9+N\_rho constitute the first block. Thus the input file is separated +(by blank lines) into N\_LD blocks each representing a separate LD potential and +each specifying its own upper and lower cutoffs, central and neighbor atoms, +and potential. In general, blank lines anywhere are ignored. + + +---------- + + +**Mixing, shift, table, tail correction, restart, info**\ : +This pair style does not support automatic mixing. For atom type pairs alpha, +beta and alpha != beta, even if LD potentials of type (alpha, alpha) and +(beta, beta) are provided, you will need to explicitly provide LD potential +types (alpha, beta) and (beta, alpha) if need be (Here, the notation (alpha, +beta) means that alpha is the central atom to which the LD potential is applied +and beta is the neighbor atom which contributes to the LD potential on alpha). + +This pair style does not support the :doc:`pair\_modify ` +shift, table, and tail options. + +The local/density pair style does not write its information to :doc:`binary restart files `, since it is stored in tabulated potential files. +Thus, you need to re-specify the pair\_style and pair\_coeff commands in +an input script that reads a restart file. + + +---------- + + +Restrictions +"""""""""""" + + +The local/density pair style is a part of the USER-MISC package. It is only +enabled if LAMMPS was built with that package. See the :doc:`Build package ` doc page for more info. + +Related commands +"""""""""""""""" + +:doc:`pair\_coeff ` + +**Default:** none + + +---------- + + +.. _Sanyal1: + + + +.. _Sanyal2: + +**(Sanyal1)** Sanyal and Shell, Journal of Chemical Physics, 2016, 145 (3), 034109. + + +**(Sanyal2)** Sanyal and Shell, Journal of Physical Chemistry B, 122 (21), 5678-5693. + +.. _Rosenberger: + + + +**(Rosenberger)** Rosenberger, Sanyal, Shell and van der Vegt, Journal of Chemical Physics, 2019, 151 (4), 044111. + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Commands_all.html diff --git a/doc/rst/pair_oxdna.rst b/doc/rst/pair_oxdna.rst index 7a80eecbad..b40cf1f6cc 100644 --- a/doc/rst/pair_oxdna.rst +++ b/doc/rst/pair_oxdna.rst @@ -33,7 +33,7 @@ Syntax .. parsed-literal:: - *oxdna/stk* args = seq T xi kappa 6.0 0.4 0.9 0.32 0.6 1.3 0 0.8 0.9 0 0.95 0.9 0 0.95 2.0 0.65 2.0 0.65 + *oxdna/stk* args = seq T xi kappa 6.0 0.4 0.9 0.32 0.75 1.3 0 0.8 0.9 0 0.95 0.9 0 0.95 2.0 0.65 2.0 0.65 seq = seqav (for average sequence stacking strength) or seqdep (for sequence-dependent stacking strength) T = temperature (oxDNA units, 0.1 = 300 K) xi = temperature-independent coefficient in stacking strength @@ -50,7 +50,7 @@ Examples pair_style hybrid/overlay oxdna/excv oxdna/stk oxdna/hbond oxdna/xstk oxdna/coaxstk pair_coeff \* \* oxdna/excv 2.0 0.7 0.675 2.0 0.515 0.5 2.0 0.33 0.32 - pair_coeff \* \* oxdna/stk seqdep 0.1 1.3448 2.6568 6.0 0.4 0.9 0.32 0.6 1.3 0 0.8 0.9 0 0.95 0.9 0 0.95 2.0 0.65 2.0 0.65 + pair_coeff \* \* oxdna/stk seqdep 0.1 1.3448 2.6568 6.0 0.4 0.9 0.32 0.75 1.3 0 0.8 0.9 0 0.95 0.9 0 0.95 2.0 0.65 2.0 0.65 pair_coeff \* \* oxdna/hbond seqdep 0.0 8.0 0.4 0.75 0.34 0.7 1.5 0 0.7 1.5 0 0.7 1.5 0 0.7 0.46 3.141592653589793 0.7 4.0 1.5707963267948966 0.45 4.0 1.5707963267948966 0.45 pair_coeff 1 4 oxdna/hbond seqdep 1.077 8.0 0.4 0.75 0.34 0.7 1.5 0 0.7 1.5 0 0.7 1.5 0 0.7 0.46 3.141592653589793 0.7 4.0 1.5707963267948966 0.45 4.0 1.5707963267948966 0.45 pair_coeff 2 3 oxdna/hbond seqdep 1.077 8.0 0.4 0.75 0.34 0.7 1.5 0 0.7 1.5 0 0.7 1.5 0 0.7 0.46 3.141592653589793 0.7 4.0 1.5707963267948966 0.45 4.0 1.5707963267948966 0.45 @@ -66,7 +66,10 @@ excluded volume interaction *oxdna/excv*\ , the stacking *oxdna/stk*\ , cross-st and coaxial stacking interaction *oxdna/coaxstk* as well as the hydrogen-bonding interaction *oxdna/hbond* between complementary pairs of nucleotides on opposite strands. Average sequence or sequence-dependent stacking and base-pairing strengths -are supported :ref:`(Sulc) `. +are supported :ref:`(Sulc) `. Quasi-unique base-pairing between nucleotides can be achieved by using +more complementary pairs of atom types like 5-8 and 6-7, 9-12 and 10-11, 13-16 and 14-15, etc. +This prevents the hybridization of in principle complementary bases within Ntypes/4 bases +up and down along the backbone. The exact functional form of the pair styles is rather complex. The individual potentials consist of products of modulation factors, diff --git a/doc/rst/pair_oxdna2.rst b/doc/rst/pair_oxdna2.rst index 79022dcdd9..4f64197f44 100644 --- a/doc/rst/pair_oxdna2.rst +++ b/doc/rst/pair_oxdna2.rst @@ -36,11 +36,11 @@ Syntax .. parsed-literal:: - *oxdna2/stk* args = seq T xi kappa 6.0 0.4 0.9 0.32 0.6 1.3 0 0.8 0.9 0 0.95 0.9 0 0.95 2.0 0.65 2.0 0.65 + *oxdna2/stk* args = seq T xi kappa 6.0 0.4 0.9 0.32 0.75 1.3 0 0.8 0.9 0 0.95 0.9 0 0.95 2.0 0.65 2.0 0.65 seq = seqav (for average sequence stacking strength) or seqdep (for sequence-dependent stacking strength) T = temperature (oxDNA units, 0.1 = 300 K) - xi = temperature-independent coefficient in stacking strength - kappa = coefficient of linear temperature dependence in stacking strength + xi = temperature-independent coefficient in stacking strength + kappa = coefficient of linear temperature dependence in stacking strength *oxdna2/hbond* args = seq eps 8.0 0.4 0.75 0.34 0.7 1.5 0 0.7 1.5 0 0.7 1.5 0 0.7 0.46 3.141592653589793 0.7 4.0 1.5707963267948966 0.45 4.0 1.5707963267948966 0.45 seq = seqav (for average sequence base-pairing strength) or seqdep (for sequence-dependent base-pairing strength) eps = 1.0678 (between base pairs A-T and C-G) or 0 (all other pairs) @@ -57,7 +57,7 @@ Examples pair_style hybrid/overlay oxdna2/excv oxdna2/stk oxdna2/hbond oxdna2/xstk oxdna2/coaxstk oxdna2/dh pair_coeff \* \* oxdna2/excv 2.0 0.7 0.675 2.0 0.515 0.5 2.0 0.33 0.32 - pair_coeff \* \* oxdna2/stk seqdep 0.1 1.3523 2.6717 6.0 0.4 0.9 0.32 0.6 1.3 0 0.8 0.9 0 0.95 0.9 0 0.95 2.0 0.65 2.0 0.65 + pair_coeff \* \* oxdna2/stk seqdep 0.1 1.3523 2.6717 6.0 0.4 0.9 0.32 0.75 1.3 0 0.8 0.9 0 0.95 0.9 0 0.95 2.0 0.65 2.0 0.65 pair_coeff \* \* oxdna2/hbond seqdep 0.0 8.0 0.4 0.75 0.34 0.7 1.5 0 0.7 1.5 0 0.7 1.5 0 0.7 0.46 3.141592653589793 0.7 4.0 1.5707963267948966 0.45 4.0 1.5707963267948966 0.45 pair_coeff 1 4 oxdna2/hbond seqdep 1.0678 8.0 0.4 0.75 0.34 0.7 1.5 0 0.7 1.5 0 0.7 1.5 0 0.7 0.46 3.141592653589793 0.7 4.0 1.5707963267948966 0.45 4.0 1.5707963267948966 0.45 pair_coeff 2 3 oxdna2/hbond seqdep 1.0678 8.0 0.4 0.75 0.34 0.7 1.5 0 0.7 1.5 0 0.7 1.5 0 0.7 0.46 3.141592653589793 0.7 4.0 1.5707963267948966 0.45 4.0 1.5707963267948966 0.45 @@ -74,7 +74,10 @@ excluded volume interaction *oxdna2/excv*\ , the stacking *oxdna2/stk*\ , cross- and coaxial stacking interaction *oxdna2/coaxstk*\ , electrostatic Debye-Hueckel interaction *oxdna2/dh* as well as the hydrogen-bonding interaction *oxdna2/hbond* between complementary pairs of nucleotides on opposite strands. Average sequence or sequence-dependent stacking and base-pairing strengths -are supported :ref:`(Sulc) `. +are supported :ref:`(Sulc) `. Quasi-unique base-pairing between nucleotides can be achieved by using +more complementary pairs of atom types like 5-8 and 6-7, 9-12 and 10-11, 13-16 and 14-15, etc. +This prevents the hybridization of in principle complementary bases within Ntypes/4 bases +up and down along the backbone. The exact functional form of the pair styles is rather complex. The individual potentials consist of products of modulation factors, diff --git a/doc/rst/pair_sdk.rst b/doc/rst/pair_sdk.rst deleted file mode 100644 index 17694067c8..0000000000 --- a/doc/rst/pair_sdk.rst +++ /dev/null @@ -1,203 +0,0 @@ -.. index:: pair\_style lj/sdk - -pair\_style lj/sdk command -========================== - -pair\_style lj/sdk/gpu command -============================== - -pair\_style lj/sdk/kk command -============================= - -pair\_style lj/sdk/omp command -============================== - -pair\_style lj/sdk/coul/long command -==================================== - -pair\_style lj/sdk/coul/long/gpu command -======================================== - -pair\_style lj/sdk/coul/long/omp command -======================================== - -pair\_style lj/sdk/coul/msm command -=================================== - -pair\_style lj/sdk/coul/msm/omp command -======================================= - -Syntax -"""""" - - -.. parsed-literal:: - - pair_style style args - -* style = *lj/sdk* or *lj/sdk/coul/long* -* args = list of arguments for a particular style - - -.. parsed-literal:: - - *lj/sdk* args = cutoff - cutoff = global cutoff for Lennard Jones interactions (distance units) - *lj/sdk/coul/long* args = cutoff (cutoff2) - cutoff = global cutoff for LJ (and Coulombic if only 1 arg) (distance units) - cutoff2 = global cutoff for Coulombic (optional) (distance units) - -Examples -"""""""" - - -.. parsed-literal:: - - pair_style lj/sdk 2.5 - pair_coeff 1 1 lj12_6 1 1.1 2.8 - - pair_style lj/sdk/coul/long 10.0 - pair_style lj/sdk/coul/long 10.0 12.0 - pair_coeff 1 1 lj9_6 100.0 3.5 12.0 - - pair_style lj/sdk/coul/msm 10.0 - pair_style lj/sdk/coul/msm 10.0 12.0 - pair_coeff 1 1 lj9_6 100.0 3.5 12.0 - -Description -""""""""""" - -The *lj/sdk* styles compute a 9/6, 12/4, or 12/6 Lennard-Jones potential, -given by - -.. image:: Eqs/pair_cmm.jpg - :align: center - -as required for the SDK Coarse-grained MD parameterization discussed in -:ref:`(Shinoda) ` and :ref:`(DeVane) `. Rc is the cutoff. - -Style *lj/sdk/coul/long* computes the adds Coulombic interactions -with an additional damping factor applied so it can be used in -conjunction with the :doc:`kspace\_style ` command and -its *ewald* or *pppm* or *pppm/cg* option. The Coulombic cutoff -specified for this style means that pairwise interactions within -this distance are computed directly; interactions outside that -distance are computed in reciprocal space. - -The following coefficients must be defined for each pair of atoms -types via the :doc:`pair\_coeff ` command as in the examples -above, or in the data file or restart files read by the -:doc:`read\_data ` or :doc:`read\_restart ` -commands, or by mixing as described below: - -* cg\_type (lj9\_6, lj12\_4, or lj12\_6) -* epsilon (energy units) -* sigma (distance units) -* cutoff1 (distance units) - -Note that sigma is defined in the LJ formula as the zero-crossing -distance for the potential, not as the energy minimum. The prefactors -are chosen so that the potential minimum is at -epsilon. - -The latter 2 coefficients are optional. If not specified, the global -LJ and Coulombic cutoffs specified in the pair\_style command are used. -If only one cutoff is specified, it is used as the cutoff for both LJ -and Coulombic interactions for this type pair. If both coefficients -are specified, they are used as the LJ and Coulombic cutoffs for this -type pair. - -For *lj/sdk/coul/long* and *lj/sdk/coul/msm* only the LJ cutoff can be -specified since a Coulombic cutoff cannot be specified for an -individual I,J type pair. All type pairs use the same global -Coulombic cutoff specified in the pair\_style command. - - ----------- - - -Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp* or *opt* suffix are -functionally the same as the corresponding style without the suffix. -They have been optimized to run faster, depending on your available -hardware, as discussed on the :doc:`Speed packages ` doc -page. The accelerated styles take the same arguments and should -produce the same results, except for round-off and precision issues. - -These accelerated styles are part of the GPU, USER-INTEL, KOKKOS, -USER-OMP, and OPT packages respectively. They are only enabled if -LAMMPS was built with those packages. See the :doc:`Build package ` doc page for more info. - -You can specify the accelerated styles explicitly in your input script -by including their suffix, or you can use the :doc:`-suffix command-line switch ` when you invoke LAMMPS, or you can use the -:doc:`suffix ` command in your input script. - -See the :doc:`Speed packages ` doc page for more -instructions on how to use the accelerated styles effectively. - - ----------- - - -**Mixing, shift, table, tail correction, restart, and rRESPA info**\ : - -For atom type pairs I,J and I != J, the epsilon and sigma coefficients -and cutoff distance for all of the lj/sdk pair styles *cannot* be mixed, -since different pairs may have different exponents. So all parameters -for all pairs have to be specified explicitly through the "pair\_coeff" -command. Defining then in a data file is also not supported, due to -limitations of that file format. - -All of the lj/sdk pair styles support the -:doc:`pair\_modify ` shift option for the energy of the -Lennard-Jones portion of the pair interaction. - -The *lj/sdk/coul/long* pair styles support the -:doc:`pair\_modify ` table option since they can tabulate -the short-range portion of the long-range Coulombic interaction. - -All of the lj/sdk pair styles write their information to :doc:`binary restart files `, so pair\_style and pair\_coeff commands do -not need to be specified in an input script that reads a restart file. - -The lj/sdk and lj/cut/coul/long pair styles do not support -the use of the *inner*\ , *middle*\ , and *outer* keywords of the :doc:`run\_style respa ` command. - - ----------- - - -Restrictions -"""""""""""" - - -All of the lj/sdk pair styles are part of the USER-CGSDK package. The -*lj/sdk/coul/long* style also requires the KSPACE package to be built -(which is enabled by default). They are only enabled if LAMMPS was -built with that package. See the :doc:`Build package ` -doc page for more info. - -Related commands -"""""""""""""""" - -:doc:`pair\_coeff `, :doc:`angle\_style sdk ` - -**Default:** none - - ----------- - - -.. _Shinoda3: - - - -**(Shinoda)** Shinoda, DeVane, Klein, Mol Sim, 33, 27 (2007). - -.. _DeVane: - - - -**(DeVane)** Shinoda, DeVane, Klein, Soft Matter, 4, 2453-2462 (2008). - - -.. _lws: http://lammps.sandia.gov -.. _ld: Manual.html -.. _lc: Commands_all.html diff --git a/doc/rst/pair_snap.rst b/doc/rst/pair_snap.rst index 4411d8f975..1b0fb0f385 100644 --- a/doc/rst/pair_snap.rst +++ b/doc/rst/pair_snap.rst @@ -57,7 +57,7 @@ the SNAP potential files themselves. Only a single pair\_coeff command is used with the *snap* style which specifies a SNAP coefficient file followed by a SNAP parameter file and then N additional arguments specifying the mapping of SNAP -elements to LAMMPS atom types, where N is the number of +elements to LAMMPS atom types, where N is the number of LAMMPS atom types: * SNAP coefficient file @@ -89,7 +89,7 @@ The name of the SNAP coefficient file usually ends in the ".snapcoeff" extension. It may contain coefficients for many SNAP elements. The only requirement is that it contain at least those element names appearing in the -LAMMPS mapping list. +LAMMPS mapping list. The name of the SNAP parameter file usually ends in the ".snapparam" extension. It contains a small number of parameters that define the overall form of the SNAP potential. diff --git a/doc/rst/pair_spin_dipole.rst b/doc/rst/pair_spin_dipole.rst index e5fc3b7b7e..87a3f7e424 100644 --- a/doc/rst/pair_spin_dipole.rst +++ b/doc/rst/pair_spin_dipole.rst @@ -12,7 +12,7 @@ Syntax .. parsed-literal:: - pair_style spin/dipole/cut cutoff + pair_style spin/dipole/cut cutoff pair_style spin/dipole/long cutoff * cutoff = global cutoff for magnetic dipole energy and forces @@ -26,35 +26,34 @@ Examples .. parsed-literal:: pair_style spin/dipole/cut 10.0 - pair_coeff \* \* 10.0 + pair_coeff \* \* 10.0 pair_coeff 2 3 8.0 pair_style spin/dipole/long 9.0 - pair_coeff \* \* 1.0 1.0 - pair_coeff 2 3 1.0 1.0 2.5 4.0 scale 0.5 - pair_coeff 2 3 1.0 1.0 2.5 4.0 + pair_coeff \* \* 10.0 + pair_coeff 2 3 6.0 Description """"""""""" Style *spin/dipole/cut* computes a short-range dipole-dipole -interaction between pairs of magnetic particles that each -have a magnetic spin. +interaction between pairs of magnetic particles that each +have a magnetic spin. The magnetic dipole-dipole interactions are computed by the -following formulas for the magnetic energy, magnetic precession +following formulas for the magnetic energy, magnetic precession vector omega and mechanical force between particles I and J. .. image:: Eqs/pair_spin_dipole.jpg :align: center -where si and sj are the spin on two magnetic particles, -r is their separation distance, and the vector e = (Ri - Rj)/\|Ri - Rj\| +where si and sj are the spin on two magnetic particles, +r is their separation distance, and the vector e = (Ri - Rj)/\|Ri - Rj\| is the direction vector between the two particles. Style *spin/dipole/long* computes long-range magnetic dipole-dipole interaction. A :doc:`kspace\_style ` must be defined to -use this pair style. Currently, :doc:`kspace\_style ewald/dipole/spin ` and :doc:`kspace\_style pppm/dipole/spin ` support long-range magnetic +use this pair style. Currently, :doc:`kspace\_style ewald/dipole/spin ` and :doc:`kspace\_style pppm/dipole/spin ` support long-range magnetic dipole-dipole interactions. @@ -76,8 +75,8 @@ Restrictions The *spin/dipole/cut* and *spin/dipole/long* styles are part of -the SPIN package. They are only enabled if LAMMPS was built with that -package. See the :doc:`Build package ` doc page for more +the SPIN package. They are only enabled if LAMMPS was built with that +package. See the :doc:`Build package ` doc page for more info. Using dipole/spin pair styles with *electron* :doc:`units ` is not diff --git a/doc/rst/pair_spin_dmi.rst b/doc/rst/pair_spin_dmi.rst index 9906bb15fe..166885d29d 100644 --- a/doc/rst/pair_spin_dmi.rst +++ b/doc/rst/pair_spin_dmi.rst @@ -21,7 +21,7 @@ Examples .. parsed-literal:: pair_style spin/dmi 4.0 - pair_coeff \* \* dmi 2.6 0.001 1.0 0.0 0.0 + pair_coeff \* \* dmi 2.6 0.001 1.0 0.0 0.0 pair_coeff 1 2 dmi 4.0 0.00109 0.0 0.0 1.0 Description diff --git a/doc/rst/pair_style.rst b/doc/rst/pair_style.rst index e847b0b80f..f6f686fc12 100644 --- a/doc/rst/pair_style.rst +++ b/doc/rst/pair_style.rst @@ -233,6 +233,7 @@ accelerated styles exist. * :doc:`lj/smooth/linear ` - linear smoothed LJ potential * `lj/switch3/coulgauss `_ - smoothed LJ vdW potential with Gaussian electrostatics * :doc:`lj96/cut ` - Lennard-Jones 9/6 potential +* :doc:`local/density ` - generalized basic local density potential * :doc:`lubricate ` - hydrodynamic lubrication forces * :doc:`lubricate/poly ` - hydrodynamic lubrication forces with polydispersity * :doc:`lubricateU ` - hydrodynamic lubrication forces for Fast Lubrication Dynamics diff --git a/doc/rst/pair_zero.rst b/doc/rst/pair_zero.rst index 0cb5c09bbf..6afafc2017 100644 --- a/doc/rst/pair_zero.rst +++ b/doc/rst/pair_zero.rst @@ -75,9 +75,8 @@ shift, table, and tail options. This pair style writes its information to :doc:`binary restart files `, 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 can only be used via the *pair* keyword of the -:doc:`run\_style respa ` command. It does not support the -*inner*\ , *middle*\ , *outer* keywords. +This pair style supports the use of the *inner*\ , *middle*\ , +and *outer* keywords of the :doc:`run\_style respa ` command. ---------- diff --git a/doc/rst/pairs.rst b/doc/rst/pairs.rst index 70ed3fe274..9124013161 100644 --- a/doc/rst/pairs.rst +++ b/doc/rst/pairs.rst @@ -66,6 +66,7 @@ Pair Styles pair_lj_smooth pair_lj_smooth_linear pair_lj_switch3_coulgauss + pair_local_density pair_lubricate pair_lubricateU pair_mdf diff --git a/doc/rst/temper.rst b/doc/rst/temper.rst index 887bf432c0..ef73ef4094 100644 --- a/doc/rst/temper.rst +++ b/doc/rst/temper.rst @@ -123,7 +123,13 @@ manner: dump file with snapshots at 300K (from all replicas), another with snapshots at 310K, etc. Note that these new dump files will not contain "continuous trajectories" for individual atoms, because two - successive snapshots (in time) may be from different replicas. + successive snapshots (in time) may be from different replicas. The + reorder\_remd\_traj python script can do the reordering for you + (and additionally also calculated configurational log-weights of + trajectory snapshots in the canonical ensemble). The script can be found + in the tools/replica directory while instructions on how to use it is + available in doc/Tools (in brief) and as a README file in tools/replica + (in detail). The last argument *index* in the temper command is optional and is used when restarting a tempering run from a set of restart files (one diff --git a/doc/rst/third_order.rst b/doc/rst/third_order.rst new file mode 100644 index 0000000000..13a230d511 --- /dev/null +++ b/doc/rst/third_order.rst @@ -0,0 +1,79 @@ +.. index:: third\_order + +third\_order command +==================== + +Syntax +"""""" + + +.. parsed-literal:: + + third_order group-ID style delta args keyword value ... + +* group-ID = ID of group of atoms to displace +* style = *regular* or *eskm* +* delta = finite different displacement length (distance units) +* one or more keyword/arg pairs may be appended + + .. parsed-literal:: + + keyword = *file* or *binary* + *file* name = name of output file for the third order tensor + *binary* arg = *yes* or *no* or *gzip* + + + +Examples +"""""""" + + +.. parsed-literal:: + + third_order 1 regular 0.000001 + third_order 1 eskm 0.000001 + third_order 3 regular 0.00004 file third_order.dat + third_order 5 eskm 0.00000001 file third_order.dat binary yes + +Description +""""""""""" + +Calculate the third order force constant tensor by finite difference of the selected group, + +.. image:: JPG/third_order_force_constant.png + :align: center + +where Phi is the third order force constant tensor. + +The output of the command is the tensor, three elements at a time. The +three elements correspond to the three gamma elements for a specific i/alpha/j/beta/k. +The initial five numbers are i, alpha, j, beta, and k respectively. + +If the style eskm is selected, the tensor will be using energy units of 10 J/mol. +These units conform to eskm style from the dynamical\_matrix command, which +will simplify operations using dynamical matrices with third order tensors. + +Restrictions +"""""""""""" + + +The command collects a 9 times the number of atoms in the group on every single MPI rank, +so the memory requirements can be very significant for large systems. + +This command is part of the USER-PHONON package. It is only enabled if +LAMMPS was built with that package. See the :doc:`Build package ` doc page for more info. + +Related commands +"""""""""""""""" + +:doc:`fix phonon ` :doc:`dynamical\_matrix ` + +Default +""""""" + +The default settings are file = "third\_order.dat", binary = no + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Commands_all.html