tx258/lammps-gran-kokkos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'master' into user-cgdna

Browse Source
This commit is contained in:
Oliver Henrich
2019-11-15 10:06:49 +00:00
parent e6aa79101f 5d042cf629
commit bac8d15764
1666 changed files with 145489 additions and 3914 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/.gitignore vendored
View File

@ -6,3 +6,5 @@
/LAMMPS.mobi
/Manual.pdf
/Developer.pdf
/doctrees
/docenv

64
doc/Makefile
View File

@ -1,12 +1,12 @@
# Makefile for LAMMPS documentation
SHELL = /bin/bash
SHA1 = $(shell echo ${USER}-${PWD} | python utils/sha1sum.py)
BUILDDIR = /tmp/lammps-docs-$(SHA1)
RSTDIR = $(BUILDDIR)/rst
BUILDDIR = ${CURDIR}
RSTDIR = $(BUILDDIR)/src
TXTDIR = $(BUILDDIR)/txt
VENV = $(BUILDDIR)/docenv
TXT2RST = $(VENV)/bin/txt2rst
ANCHORCHECK = $(VENV)/bin/doc_anchor_check
ANCHORCHECK = $(VENV)/bin/rst_anchor_check
PYTHON = $(shell which python3)
VIRTUALENV = virtualenv
@ -28,10 +28,10 @@ HAS_VIRTUALENV = YES
endif
SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())')
SOURCES=$(filter-out $(wildcard src/lammps_commands*.txt) src/lammps_support.txt src/lammps_tutorials.txt,$(wildcard src/*.txt))
OBJECTS=$(SOURCES:src/%.txt=$(RSTDIR)/%.rst)
SOURCES=$(filter-out $(wildcard $(TXTDIR)/lammps_commands*.txt) $(TXTDIR)/lammps_support.txt $(TXTDIR)/lammps_tutorials.txt,$(wildcard $(TXTDIR)/*.txt))
OBJECTS=$(SOURCES:$(TXTDIR)/%.txt=$(RSTDIR)/%.rst)
.PHONY: help clean-all clean epub mobi html pdf old venv spelling anchor_check
.PHONY: help clean-all clean epub mobi rst html pdf venv spelling anchor_check
# ------------------------------------------
@ -39,37 +39,36 @@ help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html create HTML doc pages in html dir"
@echo " pdf create Developer.pdf and Manual.pdf in this dir"
@echo " old create old-style HTML doc pages and Manual.pdf in old dir"
@echo " fetch fetch HTML and PDF files from LAMMPS web site"
@echo " epub create ePUB format manual for e-book readers"
@echo " mobi convert ePUB to MOBI format manual for e-book readers (e.g. Kindle)"
@echo " (requires ebook-convert tool from calibre)"
@echo " clean remove all intermediate RST files"
@echo " clean-all reset the entire build environment"
@echo " txt2html build txt2html tool"
@echo " anchor_check scan for duplicate anchor labels"
@echo " spelling spell-check the manual"
# ------------------------------------------
clean-all: clean
rm -rf $(BUILDDIR)/* utils/txt2html/txt2html.exe
rm -rf $(BUILDDIR)/docenv $(BUILDDIR)/doctrees
clean:
rm -rf $(RSTDIR) html old epub latex
rm -rf html epub latex
rm -rf spelling
clean-spelling:
rm -rf spelling
rst: clean $(OBJECTS) $(ANCHORCHECK)
html: $(OBJECTS) $(ANCHORCHECK)
@(\
. $(VENV)/bin/activate ;\
cp -r src/* $(RSTDIR)/ ;\
sphinx-build $(SPHINXEXTRA) -b html -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
echo "############################################" ;\
doc_anchor_check src/*.txt ;\
env LC_ALL=C grep -n '[^ -~]' src/*.txt ;\
rst_anchor_check src/*.rst ;\
env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\
echo "############################################" ;\
deactivate ;\
)
@ -89,8 +88,7 @@ spelling: $(OBJECTS) utils/sphinx-config/false_positives.txt
@(\
. $(VENV)/bin/activate ;\
pip install sphinxcontrib-spelling ;\
cp -r src/* $(RSTDIR)/ ;\
cp utils/sphinx-config/false_positives.txt $(RSTDIR)/ ;\
cp utils/sphinx-config/false_positives.txt $(RSTDIR)/ ;\
sphinx-build -b spelling -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\
deactivate ;\
)
@ -103,7 +101,6 @@ epub: $(OBJECTS)
@cp src/JPG/*.* epub/JPG
@(\
. $(VENV)/bin/activate ;\
cp -r src/* $(RSTDIR)/ ;\
sphinx-build $(SPHINXEXTRA) -b epub -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\
deactivate ;\
)
@ -126,10 +123,9 @@ pdf: $(OBJECTS) $(ANCHORCHECK)
)
@(\
. $(VENV)/bin/activate ;\
cp -r src/* $(RSTDIR)/ ;\
sphinx-build $(SPHINXEXTRA) -b latex -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\
echo "############################################" ;\
doc_anchor_check src/*.txt ;\
rst_anchor_check src/*.rst ;\
echo "############################################" ;\
deactivate ;\
)
@ -155,27 +151,6 @@ pdf: $(OBJECTS) $(ANCHORCHECK)
@rm -rf latex/USER/*/*.[sg]*
@echo "Build finished. Manual.pdf and Developer.pdf are in this directory."
old: utils/txt2html/txt2html.exe
@rm -rf old
@mkdir old; mkdir old/Eqs; mkdir old/JPG; mkdir old/PDF
@cd src; ../utils/txt2html/txt2html.exe -b *.txt; \
mv *.html ../old; \
cp Eqs/*.jpg ../old/Eqs; \
cp JPG/* ../old/JPG; \
cp PDF/* ../old/PDF;
@( set -e;\
cd src/Developer; \
pdflatex developer; \
pdflatex developer; \
mv developer.pdf ../../old/Developer.pdf; \
cd ../../old; \
for s in `echo ../src/*.txt | sed -e 's,\.\./src/,,g' -e 's/ \(pairs\|bonds\|angles\|dihedrals\|impropers\|commands_list\|fixes\|computes\).txt/ /g' | sed -e 's,\.txt,\.html,g'` ; \
do grep -q ^$$s ../src/lammps.book || \
echo WARNING: doc file $$s missing in src/lammps.book; done; \
htmldoc --batch ../src/lammps.book; \
)
fetch:
@rm -rf html_www Manual_www.pdf Developer_www.pdf
@curl -s -o Manual_www.pdf http://lammps.sandia.gov/doc/Manual.pdf
@ -184,21 +159,16 @@ fetch:
@tar xzf lammps-doc.tar.gz
@rm -f lammps-doc.tar.gz
txt2html: utils/txt2html/txt2html.exe
anchor_check : $(ANCHORCHECK)
@(\
. $(VENV)/bin/activate ;\
doc_anchor_check src/*.txt ;\
rst_anchor_check src/*.txt ;\
deactivate ;\
)
# ------------------------------------------
utils/txt2html/txt2html.exe: utils/txt2html/txt2html.cpp
g++ -O -Wall -o $@ $<
$(RSTDIR)/%.rst : src/%.txt $(TXT2RST)
$(RSTDIR)/%.rst : $(TXTDIR)/%.txt $(TXT2RST)
@(\
mkdir -p $(RSTDIR) ; \
. $(VENV)/bin/activate ;\

2
doc/lammps.1
View File

@ -1,4 +1,4 @@
.TH LAMMPS "19 September 2019" "2019-09-19"
.TH LAMMPS "30 October 2019" "2019-10-30"
.SH NAME
.B LAMMPS
\- Molecular Dynamics Simulator.

2
doc/src/.gitignore vendored Normal file
View File

@ -0,0 +1,2 @@
Eqs
JPG

28
doc/src/Build.rst Normal file
View File

@ -0,0 +1,28 @@
Build LAMMPS
************
LAMMPS can be built as an executable or library from source code via
either traditional makefiles (which may require manual editing)
for use with GNU make or gmake, or a build environment generated by CMake
(Unix Makefiles, Xcode, Visual Studio, KDevelop or more). As an
alternative you can download a package with pre-built executables
as described on the :doc:`Install <Install>` doc page.
.. toctree::
:maxdepth: 1
Build_cmake
Build_make
Build_link
Build_basics
Build_settings
Build_package
Build_extras
Build_windows
Build_development
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

437
doc/src/Build_basics.rst Normal file
View File

@ -0,0 +1,437 @@
Basic build options
===================
The following topics are covered on this page, for building both with
CMake and make:
* :ref:`Serial vs parallel build <serial>`
* :ref:`Choice of compiler and compile/link options <compile>`
* :ref:`Build LAMMPS as an executable or a library <exe>`
* :ref:`Build the LAMMPS documentation <doc>`
* :ref:`Install LAMMPS after a build <install>`
----------
.. _serial:
Serial vs parallel build
-------------------------------------
LAMMPS can be built to run in parallel using the ubiquitous `MPI (message-passing interface) <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
library. Or it can built to run on a single processor (serial)
without MPI. It can also be built with support for OpenMP threading
(see more discussion below).
**CMake variables**\ :
.. parsed-literal::
-D BUILD_MPI=value # yes or no, default is yes if CMake finds MPI, else no
-D BUILD_OMP=value # yes or no (default)
-D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc
# no default value
The executable created by CMake (after running make) is lmp\_name. If
the LAMMPS\_MACHINE variable is not specified, the executable is just
lmp. Using BUILD\_MPI=no will produce a serial executable.
**Traditional make**\ :
.. parsed-literal::
cd lammps/src
make mpi # parallel build, produces lmp_mpi using Makefile.mpi
make serial # serial build, produces lmp_serial using Makefile/serial
make mybox # uses Makefile.mybox to produce lmp_mybox
Serial build (see src/MAKE/Makefile.serial):
.. parsed-literal::
MPI_INC = -I../STUBS
MPI_PATH = -L../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
variables MPI\_INC, MPI\_PATH, MPI\_LIB. The MPI wrapper on the compiler
(e.g. mpicxx, mpiCC) knows where to find the needed include and
library files. Failing this, these 3 variables can be used to specify
where the mpi.h file (MPI\_INC), and the MPI library files (MPI\_PATH)
are found, and the name of the library files (MPI\_LIB).
For a serial build, you need to specify the 3 variables, as shown
above.
For a serial LAMMPS build, use the dummy MPI library provided in
src/STUBS. You also need to build the STUBS library for your platform
before making LAMMPS itself. A "make serial" build does this for.
Otherwise, type "make mpi-stubs" from the src directory, or "make"
from the src/STUBS dir. If the build fails, you will need to edit the
STUBS/Makefile for your platform.
The file STUBS/mpi.c provides a CPU timer function called MPI\_Wtime()
that calls gettimeofday() . If your system doesn't support
gettimeofday() , you'll need to insert code to call another timer.
Note that the ANSI-standard function clock() rolls over after an hour
or so, and is therefore insufficient for timing long LAMMPS
simulations.
**CMake and make info**\ :
If you are installing MPI yourself, we recommend MPICH2 from Argonne
National Laboratory or OpenMPI. MPICH can be downloaded from the
`Argonne MPI site <http://www.mcs.anl.gov/research/projects/mpich2/>`_.
OpenMPI can be downloaded from the `OpenMPI site <http://www.open-mpi.org>`_. Other MPI packages should also work.
If you are running on a large parallel machine, your system admins or
the vendor should have already installed a version of MPI, which is
likely to be faster than a self-installed MPICH or OpenMPI, so find
out how to build and link with it.
The majority of OpenMP (threading) support in LAMMPS is provided by
the USER-OMP package; see the :doc:`Speed omp <Speed_omp>` doc page for
details. The USER-INTEL package also provides OpenMP support (it is
compatible with USER-OMP) and adds vectorization support when compiled
with the Intel compilers on top of that. Also, the KOKKOS package can
be compiled for using OpenMP threading.
However, there are a few commands in LAMMPS that have native OpenMP
support. These are commands in the MPIIO, SNAP, USER-DIFFRACTION, and
USER-DPD packages. In addition some packages support OpenMP threading
indirectly through the libraries they interface to: e.g. LATTE and
USER-COLVARS. See the :doc:`Packages details <Packages_details>` doc
page for more info on these packages and the doc pages for their
respective commands for OpenMP threading info.
For CMake, if you use BUILD\_OMP=yes, you can use these packages and
turn on their native OpenMP support and turn on their native OpenMP
support at run time, by setting the OMP\_NUM\_THREADS environment
variable before you launch LAMMPS.
For building via conventional make, the CCFLAGS and LINKFLAGS
variables in Makefile.machine need to include the compiler flag that
enables OpenMP. For GNU compilers it is -fopenmp. For (recent) Intel
compilers it is -qopenmp. If you are using a different compiler,
please refer to its documentation.
.. _default-none-issues:
**OpenMP Compiler compatibility info**\ :
Some compilers do not fully support the 'default(none)' directive
and others (e.g. GCC version 9 and beyond) may implement OpenMP 4.0
semantics, which are incompatible with the OpenMP 3.1 directives used
in LAMMPS (for maximal compatibility with compiler versions in use).
In those case, all 'default(none)' directives (which aid in detecting
incorrect and unwanted sharing) can be replaced with 'default(shared)'
while dropping all 'shared()' directives. The script
'src/USER-OMP/hack\_openmp\_for\_pgi\_gcc9.sh' can be used to automate
this conversion.
----------
.. _compile:
Choice of compiler and compile/link options
---------------------------------------------------------
The choice of compiler and compiler flags can be important for
performance. Vendor compilers can produce faster code than
open-source compilers like GNU. On boxes with Intel CPUs, we suggest
trying the `Intel C++ compiler <intel_>`_.
.. _intel: https://software.intel.com/en-us/intel-compilers
On parallel clusters or supercomputers which use "modules" for their
compile/link environments, you can often access different compilers by
simply loading the appropriate module before building LAMMPS.
**CMake variables**\ :
.. parsed-literal::
-D CMAKE_CXX_COMPILER=name # name of C++ compiler
-D CMAKE_C_COMPILER=name # name of C compiler
-D CMAKE_Fortran_COMPILER=name # name of Fortran compiler
-D CMAKE_CXX_FLAGS=string # flags to use with C++ compiler
-D CMAKE_C_FLAGS=string # flags to use with C compiler
-D CMAKE_Fortran_FLAGS=string # flags to use with Fortran compiler
By default CMake will use a compiler it finds and it will add
optimization flags appropriate to that compiler and any :doc:`accelerator packages <Speed_packages>` you have included in the build.
You can tell CMake to look for a specific compiler with these variable
settings. Likewise you can specify the FLAGS variables if you want to
experiment with alternate optimization flags. You should specify all
3 compilers, so that the small number of LAMMPS source files written
in C or Fortran are built with a compiler consistent with the one used
for all the C++ files:
.. parsed-literal::
Building with GNU Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran
Building with Intel Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort
Building with LLVM/Clang Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang
.. note::
When the cmake command completes, it prints info to the screen
as to which compilers it is using, and what flags will be used in the
compilation. Note that if the top-level compiler is mpicxx, it is
simply a wrapper on a real compiler. The underlying compiler info is
what will be listed in the CMake output. You should check to insure
you are using the compiler and optimization flags are the ones you
want.
**Makefile.machine settings**\ :
Parallel build (see src/MAKE/Makefile.mpi):
.. parsed-literal::
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
The "compiler/linker settings" section of a Makefile.machine lists
compiler and linker settings for your C++ compiler, including
optimization flags. You should always use mpicxx or mpiCC for
a parallel build, since these compiler wrappers will include
a variety of settings appropriate for your MPI installation.
.. note::
If you build LAMMPS with any :doc:`accelerator packages <Speed_packages>` included, they have specific
optimization flags that are either required or recommended for optimal
performance. You need to include these in the CCFLAGS and LINKFLAGS
settings above. For details, see the individual package doc pages
listed on the :doc:`Speed packages <Speed_packages>` doc page. Or
examine these files in the src/MAKE/OPTIONS directory. They
correspond to each of the 5 accelerator packages and their hardware
variants:
.. parsed-literal::
Makefile.opt # OPT package
Makefile.omp # USER-OMP package
Makefile.intel_cpu # USER-INTEL package for CPUs
Makefile.intel_coprocessor # USER-INTEL package for KNLs
Makefile.gpu # GPU package
Makefile.kokkos_cuda_mpi # KOKKOS package for GPUs
Makefile.kokkos_omp # KOKKOS package for CPUs (OpenMP)
Makefile.kokkos_phi # KOKKOS package for KNLs (OpenMP)
----------
.. _exe:
Build LAMMPS as an executable or a library
----------------------------------------------------
LAMMPS can be built as either an executable or as a static or shared
library. The LAMMPS library can be called from another application or
a scripting language. See the :doc:`Howto couple <Howto_couple>` doc
page for more info on coupling LAMMPS to other codes. See the
:doc:`Python <Python_head>` doc page for more info on wrapping and
running LAMMPS from Python via its library interface.
**CMake variables**\ :
.. parsed-literal::
-D BUILD_EXE=value # yes (default) or no
-D BUILD_LIB=value # yes or no (default)
-D BUILD_SHARED_LIBS=value # yes or no (default)
-D LAMMPS_LIB_SUFFIX=name # name = mpi, serial, mybox, titan, laptop, etc
# no default value
Setting BUILD\_EXE=no will not produce an executable. Setting
BUILD\_LIB=yes will produce a static library named liblammps.a.
Setting both BUILD\_LIB=yes and BUILD\_SHARED\_LIBS=yes will produce a
shared library named liblammps.so. If LAMMPS\_LIB\_SUFFIX is set the generated
libraries will be named liblammps\_name.a or liblammps\_name.so instead.
**Traditional make**\ :
.. parsed-literal::
cd lammps/src
make machine # build LAMMPS executable lmp_machine
make mode=lib machine # build LAMMPS static lib liblammps_machine.a
make mode=shlib machine # build LAMMPS shared lib liblammps_machine.so
The two library builds also create generic soft links, named
liblammps.a and liblammps.so, which point to the liblammps\_machine
files.
**CMake and make info**\ :
Note that for a shared library to be usable by a calling program, all
the auxiliary libraries it depends on must also exist as shared
libraries. This will be the case for libraries included with LAMMPS,
such as the dummy MPI library in src/STUBS or any package libraries in
the lib/packages directory, since they are always built as shared
libraries using the -fPIC switch. However, if a library like MPI or
FFTW does not exist as a shared library, the shared library build will
generate an error. This means you will need to install a shared
library version of the auxiliary library. The build instructions for
the library should tell you how to do this.
As an example, here is how to build and install the `MPICH library <mpich_>`_, a popular open-source version of MPI, distributed by
Argonne National Lab, as a shared library in the default
/usr/local/lib location:
.. _mpich: http://www-unix.mcs.anl.gov/mpi
.. parsed-literal::
./configure --enable-shared
make
make install
You may need to use "sudo make install" in place of the last line if
you do not have write privileges for /usr/local/lib. The end result
should be the file /usr/local/lib/libmpich.so.
----------
.. _doc:
Build the LAMMPS documentation
----------------------------------------
**CMake variable**\ :
.. parsed-literal::
-D BUILD_DOC=value # yes or no (default)
This will create the HTML doc pages within the CMake build directory.
The reason to do this is if you want to "install" LAMMPS on a system
after the CMake build via "make install", and include the doc pages in
the install.
**Traditional make**\ :
.. parsed-literal::
cd lammps/doc
make html # html doc pages
make pdf # single Manual.pdf file
This will create a lammps/doc/html dir with the HTML doc pages so that
you can browse them locally on your system. Type "make" from the
lammps/doc dir to see other options.
.. note::
You can also download a tarball of the documentation for the
current LAMMPS version (HTML and PDF files), from the website
`download page <http://lammps.sandia.gov/download.html>`_.
----------
.. _tools:
Build LAMMPS tools
------------------------------
Some tools described in :doc:`Auxiliary tools <Tools>` can be built directly
using CMake or Make.
**CMake variable**\ :
.. parsed-literal::
-D BUILD_TOOLS=value # yes or no (default)
The generated binaries will also become part of the LAMMPS installation (see below)
**Traditional make**\ :
.. parsed-literal::
cd lammps/tools
make all # build all binaries of tools
make binary2txt # build only binary2txt tool
make chain # build only chain tool
make micelle2d # build only micelle2d tool
make thermo_extract # build only thermo_extract tool
----------
.. _install:
Install LAMMPS after a build
------------------------------------------
After building LAMMPS, you may wish to copy the LAMMPS executable of
library, along with other LAMMPS files (library header, doc files) to
a globally visible place on your system, for others to access. Note
that you may need super-user privileges (e.g. sudo) if the directory
you want to copy files to is protected.
**CMake variable**\ :
.. parsed-literal::
cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake
make # perform make after CMake command
make install # perform the installation into prefix
**Traditional make**\ :
There is no "install" option in the src/Makefile for LAMMPS. If you
wish to do this you will need to first build LAMMPS, then manually
copy the desired LAMMPS files to the appropriate system directories.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

245
doc/src/Build_cmake.rst Normal file
View File

@ -0,0 +1,245 @@
Build LAMMPS with CMake
=======================
This page is a short summary of how to use CMake to build LAMMPS.
Details on CMake variables that enable specific LAMMPS build options
are given on the pages linked to from the :doc:`Build <Build>` doc page.
Richard Berger (Temple U) has also written a `more comprehensive guide <https://github.com/lammps/lammps/blob/master/cmake/README.md>`_
for how to use CMake to build LAMMPS. If you are new to CMake it is a
good place to start.
----------
Building LAMMPS with CMake is a two-step process. First you use CMake
to create a build environment in a new directory. On Linux systems,
this will be based on makefiles for use with make. Then you use the
make command to build LAMMPS, which uses the created
Makefile(s). Example:
.. parsed-literal::
cd lammps # change to the LAMMPS distribution directory
mkdir build; cd build # create a new directory (folder) for build
cmake [options ...] ../cmake # configuration with (command-line) cmake
make # compilation
The cmake command will detect available features, enable selected
packages and options, and will generate the build environment. By default
this build environment will be created for "Unix Makefiles" on most
platforms and particularly on Linux. However, alternate build tools
(e.g. Ninja) and support files for Integrated Development Environments
(IDE) like Eclipse, CodeBlocks, or Kate can be generated, too. This is
selected via the "-G" command line flag. For the rest of the documentation
we will assume that the build environment is generated for makefiles
and thus the make command will be used to compile and link LAMMPS as
indicated above, producing (by default) an executable called "lmp" and
a library called "liblammps.a" in the "build" folder. When generating
a build environment for the "Ninja" build tool, the build command would
be "ninja" instead of "make".
If your machine has multiple CPU cores (most do these days), using a
command like "make -jN" (with N being the number of available local
CPU cores) can be much faster. If you plan to do development on
LAMMPS or need to re-compile LAMMPS repeatedly, installation of the
ccache (= Compiler Cache) software may speed up repeated compilation
even more.
After compilation, you may optionally install the LAMMPS executable into
your system with:
.. parsed-literal::
make install # optional, copy LAMMPS executable & library elsewhere
This will install the lammps executable and library (if requested), some
tools (if configured) and additional files like library API headers,
manpages, potential and force field files. The location of the installation
tree is set by the CMake variable "CMAKE\_INSTALL\_PREFIX" which defaults
to ${HOME}/.local
----------
There are 3 variants of CMake: a command-line version (cmake), a text mode
UI version (ccmake), and a graphical GUI version (cmake-GUI). You can use
any of them interchangeably to configure and create the LAMMPS build
environment. On Linux all the versions produce a Makefile as their
output. See more details on each below.
You can specify a variety of options with any of the 3 versions, which
affect how the build is performed and what is included in the LAMMPS
executable. Links to pages explaining all the options are listed on
the :doc:`Build <Build>` doc page.
You must perform the CMake build system generation and compilation in
a new directory you create. It can be anywhere on your local machine.
In these Build pages we assume that you are building in a directory
called "lammps/build". You can perform separate builds independently
with different options, so long as you perform each of them in a
separate directory you create. All the auxiliary files created by one
build process (executable, object files, log files, etc) are stored in
this directory or sub-directories within it that CMake creates.
.. note::
To perform a CMake build, no packages can be installed or a
build been previously attempted in the LAMMPS src directory by using
"make" commands to :doc:`perform a conventional LAMMPS build <Build_make>`. CMake detects if this is the case and
generates an error, telling you to type "make no-all purge" in the src
directory to un-install all packages. The purge removes all the \*.h
files auto-generated by make.
You must have CMake version 2.8 or later on your system to build
LAMMPS. A handful of LAMMPS packages (KOKKOS, LATTE, MSCG) require a
later version. CMake will print a message telling you if a later
version is required. Installation instructions for CMake are below.
After the initial build, if you edit LAMMPS source files, or add your
own new files to the source directory, you can just re-type make from
your build directory and it will re-compile only the files that have
changed. If you want to change CMake options you can run cmake (or
ccmake or cmake-gui) again from the same build directory and alter
various options; see details below. Or you can remove the entire build
folder, recreate the directory and start over.
----------
**Command-line version of CMake**\ :
.. parsed-literal::
cmake [options ...] /path/to/lammps/cmake # build from any dir
cmake [options ...] ../cmake # build from lammps/build
The cmake command takes one required argument, which is the LAMMPS
cmake directory which contains the CMakeLists.txt file.
The argument can be preceeded or followed by various CMake
command-line options. Several useful ones are:
.. parsed-literal::
-D CMAKE_INSTALL_PREFIX=path # where to install LAMMPS executable/lib if desired
-D CMAKE_BUILD_TYPE=type # type = RelWithDebInfo (default), Release, MinSizeRel, or Debug
-G output # style of output CMake generates
-DVARIABLE=value # setting for a LAMMPS feature to enable
-D VARIABLE=value # ditto, but cannot come after CMakeLists.txt dir
-C path/to/preset/file # load some CMake settings before configuring
All the LAMMPS-specific -D variables that a LAMMPS build supports are
described on the pages linked to from the :doc:`Build <Build>` doc page.
All of these variable names are upper-case and their values are
lower-case, e.g. -D LAMMPS\_SIZES=smallbig. For boolean values, any of
these forms can be used: yes/no, on/off, 1/0.
On Unix/Linux machines, CMake generates a Makefile by default to
perform the LAMMPS build. Alternate forms of build info can be
generated via the -G switch, e.g. Visual Studio on a Windows machine,
Xcode on MacOS, or KDevelop on Linux. Type "cmake --help" to see the
"Generator" styles of output your system supports.
.. note::
When CMake runs, it prints configuration info to the screen.
You should review this to verify all the features you requested were
enabled, including packages. You can also see what compilers and
compile options will be used for the build. Any errors in CMake
variable syntax will also be flagged, e.g. mis-typed variable names or
variable values.
CMake creates a CMakeCache.txt file when it runs. This stores all the
settings, so that when running CMake again you can use the current
folder '.' instead of the path to the LAMMPS cmake folder as the
required argument to the CMake command. Either way the existing
settings will be inherited unless the CMakeCache.txt file is removed.
If you later want to change a setting you can rerun cmake in the build
directory with different setting. Please note that some automatically
detected variables will not change their value when you rerun cmake.
In these cases it is usually better to first remove all the
files/directories in the build directory, or start with a fresh build
directory.
----------
**Curses version (terminal-style menu) of CMake**\ :
.. parsed-literal::
ccmake ../cmake
You initiate the configuration and build environment generation steps
separately. For the first you have to type **c**\ , for the second you
have to type **g**\ . You may need to type **c** multiple times, and may be
required to edit some of the entries of CMake configuration variables
in between. Please see the `ccmake manual <https://cmake.org/cmake/help/latest/manual/ccmake.1.html>`_ for
more information.
----------
**GUI version of CMake**\ :
.. parsed-literal::
cmake-gui ../cmake
You initiate the configuration and build environment generation steps
separately. For the first you have to click on the **Configure** button,
for the second you have to click on the **Generate** button. You may
need to click on **Configure** multiple times, and may be required to
edit some of the entries of CMake configuration variables in between.
Please see the `cmake-gui manual <https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html>`_
for more information.
----------
**Installing CMake**
Check if your machine already has CMake installed:
.. parsed-literal::
which cmake # do you have it?
which cmake3 # version 3 may have this name
cmake --version # what specific version you have
On clusters or supercomputers which use environment modules to manage
software packages, do this:
.. parsed-literal::
module list # is a cmake module already loaded?
module avail # is a cmake module available?
module load cmake3 # load cmake module with appropriate name
Most Linux distributions offer pre-compiled cmake packages through
their package management system. If you do not have CMake or a new
enough version, you can download the latest version at
`https://cmake.org/download/ <https://cmake.org/download/>`_.
Instructions on how to install it on various platforms can be found
`on this page <https://cmake.org/install/>`_.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

120
doc/src/Build_development.rst Normal file
View File

@ -0,0 +1,120 @@
Development build options (CMake only)
======================================
The CMake build of LAMMPS has a few extra options which are useful during
development, testing or debugging.
----------
.. _compilation:
Verify compilation flags
------------------------------------------
Sometimes it is necessary to verify the complete sequence of compilation flags
generated by the CMake build. To enable a more verbose output during
compilation you can use the following option.
.. parsed-literal::
-D CMAKE_VERBOSE_MAKEFILE=value # value = no (default) or yes
Another way of doing this without reconfiguration is calling make with variable VERBOSE set to 1:
.. parsed-literal::
make VERBOSE=1
----------
.. _sanitizer:
Address, Undefined Behavior, and Thread Sanitizer Support
-------------------------------------------------------------------------
Compilers such as GCC and Clang support generating binaries which use different
sanitizers to detect problems in code during run-time. They can detect `memory leaks <https://clang.llvm.org/docs/AddressSanitizer.html>`_,
code that runs into `undefined behavior <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html>`_ of the
language and `data races <https://clang.llvm.org/docs/ThreadSanitizer.html>`_ in threaded code.
The following settings allow you enable these features if your compiler supports
it. Please note that they come with a performance hit. However, they are
usually faster than using tools like Valgrind.
.. parsed-literal::
-D ENABLE_SANITIZE_ADDRESS=value # enable Address Sanitizer, value = no (default) or yes
-D ENABLE_SANITIZE_UNDEFINED=value # enable Undefined Behaviour Sanitizer, value = no (default) or yes
-D ENABLE_SANITIZE_THREAD=value # enable Thread Sanitizer, value = no (default) or yes
----------
.. _testing:
Code Coverage and Testing
---------------------------------------
We do extensive regression testing of the LAMMPS code base on a continuous
basis. Some of the logic to do this has been added to the CMake build so
developers can run the tests directly on their workstation.
.. note::
this is incomplete and only represents a small subset of tests that we run
.. parsed-literal::
-D ENABLE_TESTING=value # enable simple run tests of LAMMPS, value = no (default) or yes
-D LAMMPS_TESTING_SOURCE_DIR=path # path to lammps-testing repository (option if in custom location)
-D LAMMPS_TESTING_GIT_TAG=value # version of lammps-testing repository that should be used, value = master (default) or custom git commit or tag
If you enable testing in the CMake build it will create an additional target called "test". You can run them with:
.. parsed-literal::
make test
The test cases used come from the lammps-testing repository. They are
derivatives of the examples folder with some modifications to make the run
faster.
You can also collect code coverage metrics while running the tests by enabling
coverage support during building.
.. parsed-literal::
-D ENABLE_COVERAGE=value # enable coverage measurements, value = no (default) or yes
This will also add the following targets to generate coverage reports after running the LAMMPS executable:
.. parsed-literal::
make test # run tests first!
make gen_coverage_html # generate coverage report in HTML format
make gen_coverage_xml # generate coverage report in XML format
These reports require GCOVR to be installed. The easiest way to do this to install it via pip:
.. parsed-literal::
pip install git+https://github.com/gcovr/gcovr.git
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

1399
doc/src/Build_extras.rst Normal file
View File

File diff suppressed because it is too large Load Diff

91
doc/src/Build_link.rst Normal file
View File

@ -0,0 +1,91 @@
Link LAMMPS as a library to another code
========================================
LAMMPS can be used as a library by another application, including
Python scripts. The files src/library.cpp and library.h define the
C-style API for using LAMMPS as a library. See the :doc:`Howto library <Howto_library>` doc page for a description of the
interface and how to extend it for your needs.
The :doc:`Build basics <Build_basics>` doc page explains how to build
LAMMPS as either a shared or static library. This results in one of
these 2 files:
liblammps.so # shared library
liblammps.a # static library
----------
**Link with LAMMPS as a static library**\ :
The calling application can link to LAMMPS as a static library with a
link command like this:
g++ caller.o -L/home/sjplimp/lammps/src -llammps -o caller
The -L argument is the path to where the liblammps.a file is. The
-llammps argument is shorthand for the file liblammps.a.
----------
**Link with LAMMPS as a shared library**\ :
If you wish to link to liblammps.so, the operating system finds shared
libraries to load at run-time using the environment variable
LD\_LIBRARY\_PATH. To enable this you can do one of two things:
(1) Copy the liblammps.so file to a location the system can find it,
such as /usr/local/lib. I.e. a directory already listed in your
LD\_LIBRARY\_PATH variable. You can type
.. parsed-literal::
printenv LD_LIBRARY_PATH
to see what directories are in that list.
(2) Add the LAMMPS src directory (or the directory you perform CMake
build in) to your LD\_LIBRARY\_PATH, so that the current version of the
shared library is always available to programs that use it.
For the csh or tcsh shells, you would add something like this to your
~/.cshrc file:
.. parsed-literal::
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src
----------
**Calling the LAMMPS library**\ :
Either flavor of library (static or shared) allows one or more LAMMPS
objects to be instantiated from the calling program.
When used from a C++ program, all of LAMMPS is wrapped in a LAMMPS\_NS
namespace; you can safely use any of its classes and methods from
within the calling code, as needed.
When used from a C or Fortran program, the library has a simple
C-style interface, provided in src/library.cpp and src/library.h.
See the :doc:`Python library <Python_library>` doc page for a
description of the Python interface to LAMMPS, which wraps the C-style
interface.
See the sample codes in examples/COUPLE/simple for examples of C++ and
C and Fortran codes that invoke LAMMPS through its library interface.
Other examples in the COUPLE directory use coupling ideas discussed on
the :doc:`Howto couple <Howto_couple>` doc page.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

94
doc/src/Build_make.rst Normal file
View File

@ -0,0 +1,94 @@
Build LAMMPS with make
======================
Building LAMMPS with traditional makefiles requires that you have a
Makefile."machine" file appropriate for your system in the src/MAKE,
src/MAKE/MACHINES, src/MAKE/OPTIONS, or src/MAKE/MINE directory (see
below). It can include various options for customizing your LAMMPS
build with a number of global compilation options and features.
To include LAMMPS packages (i.e. optional commands and styles) you
must install them first, as discussed on the :doc:`Build package <Build_package>` doc page. If the packages require
provided or external libraries, you must build those libraries before
building LAMMPS. Building :doc:`LAMMPS with CMake <Build_cmake>` can
automate all of this for many types of machines, especially
workstations, desktops and laptops, so we suggest you try it first.
These commands perform a default LAMMPS build, producing the LAMMPS
executable lmp\_serial or lmp\_mpi in lammps/src:
.. parsed-literal::
cd lammps/src
make serial # build a serial LAMMPS executable
make mpi # build a parallel LAMMPS executable with MPI
make # see a variety of make options
This initial compilation can take a long time, since LAMMPS is a large
project with many features. If your machine has multiple CPU cores
(most do these days), using a command like "make -jN mpi" (with N =
the number of available CPU cores) can be much faster. If you plan to
do development on LAMMPS or need to re-compile LAMMPS repeatedly, the
installation of the ccache (= Compiler Cache) software may speed up
compilation even more.
After the initial build, whenever you edit LAMMPS source files, or add
or remove new files to the source directory (e.g. by installing or
uninstalling packages), you must re-compile and relink the LAMMPS
executable with the same "make" command. This makefiles dependencies
should insure that only the subset of files that need to be are
re-compiled.
.. note::
When you build LAMMPS for the first time, a long list of \*.d
files will be printed out rapidly. This is not an error; it is the
Makefile doing its normal creation of dependencies.
----------
The lammps/src/MAKE tree contains all the Makefile.machine files
included in the LAMMPS distribution. Typing "make machine" uses
Makefile.machine. Thus the "make serial" or "make mpi" lines above
use Makefile.serial and Makefile.mpi. Others are in these dirs:
.. parsed-literal::
OPTIONS # Makefiles which enable specific options
MACHINES # Makefiles for specific machines
MINE # customized Makefiles you create (you may need to create this folder)
Typing "make" lists all the available Makefile.machine files. A file
with the same name can appear in multiple folders (not a good idea).
The order the dirs are searched is as follows: src/MAKE/MINE,
src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives preference
to a customized file you put in src/MAKE/MINE.
Makefiles you may wish to try include these (some require a package
first be installed). Many of these include specific compiler flags
for optimized performance. Please note, however, that some of these
customized machine Makefile are contributed by users. Since both
compilers, OS configurations, and LAMMPS itself keep changing, their
settings may become outdated:
.. parsed-literal::
make mac # build serial LAMMPS on a Mac
make mac_mpi # build parallel LAMMPS on a Mac
make intel_cpu # build with the USER-INTEL package optimized for CPUs
make knl # build with the USER-INTEL package optimized for KNLs
make opt # build with the OPT package optimized for CPUs
make omp # build with the USER-OMP package optimized for OpenMP
make kokkos_omp # build with the KOKKOS package for OpenMP
make kokkos_cuda_mpi # build with the KOKKOS package for GPUs
make kokkos_phi # build with the KOKKOS package for KNLs
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

265
doc/src/Build_package.rst Normal file
View File

@ -0,0 +1,265 @@
Include packages in build
=========================
In LAMMPS, a package is a group of files that enable a specific set of
features. For example, force fields for molecular systems or
rigid-body constraints are in packages. In the src directory, each
package is a sub-directory with the package name in capital letters.
An overview of packages is given on the :doc:`Packages <Packages>` doc
page. Brief overviews of each package are on the :doc:`Packages details <Packages_details>` doc page.
When building LAMMPS, you can choose to include or exclude each
package. In general there is no need to include a package if you
never plan to use its features.
If you get a run-time error that a LAMMPS command or style is
"Unknown", it is often because the command is contained in a package,
and your build did not include that package. Running LAMMPS with the
:doc:`-h command-line switch <Run_options>` will print all the included
packages and commands for that executable.
For the majority of packages, if you follow the single step below to
include it, you can then build LAMMPS exactly the same as you would
without any packages installed. A few packages may require additional
steps, as explained on the :doc:`Build extras <Build_extras>` doc page.
These links take you to the extra instructions for those select
packages:
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`COMPRESS <compress>` | :ref:`GPU <gpu>` | :ref:`KIM <kim>` | :ref:`KOKKOS <kokkos>` | :ref:`LATTE <latte>` | :ref:`MESSAGE <message>` |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`MSCG <mscg>` | :ref:`OPT <opt>` | :ref:`POEMS <poems>` | :ref:`PYTHON <python>` | :ref:`VORONOI <voronoi>` | :ref:`USER-ADIOS <user-adios>` |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-ATC <user-atc>` | :ref:`USER-AWPMD <user-awpmd>` | :ref:`USER-COLVARS <user-colvars>` | :ref:`USER-H5MD <user-h5md>` | :ref:`USER-INTEL <user-intel>` | :ref:`USER-MOLFILE <user-molfile>` |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-NETCDF <user-netcdf>` | :ref:`USER-PLUMED <user-plumed>` | :ref:`USER-OMP <user-omp>` | :ref:`USER-QMMM <user-qmmm>` | :ref:`USER-QUIP <user-quip>` | :ref:`USER-SCAFACOS <user-scafacos>` |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-SMD <user-smd>` | :ref:`USER-VTK <user-vtk>` | | | | |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
The mechanism for including packages is simple but different for CMake
versus make.
**CMake variables**\ :
.. parsed-literal::
-D PKG_NAME=value # yes or no (default)
Examples:
.. parsed-literal::
-D PKG_MANYBODY=yes
-D PKG_USER-INTEL=yes
All standard and user packages are included the same way. Note that
USER packages have a hyphen between USER and the rest of the package
name, not an underscore.
See the shortcut section below for how to install many packages at
once with CMake.
.. note::
If you toggle back and forth between building with CMake vs
make, no packages in the src directory can be installed when you
invoke cmake. CMake will give an error if that is not the case,
indicating how you can un-install all packages in the src dir.
**Traditional make**\ :
.. parsed-literal::
cd lammps/src
make ps # check which packages are currently installed
make yes-name # install a package with name
make no-name # un-install a package with name
make mpi # build LAMMPS with whatever packages are now installed
Examples:
.. parsed-literal::
make no-rigid
make yes-user-intel
All standard and user packages are included the same way.
See the shortcut section below for how to install many packages at
once with make.
.. note::
You must always re-build LAMMPS (via make) after installing or
un-installing a package, for the action to take effect.
.. note::
You cannot install or un-install packages and build LAMMPS in a
single make command with multiple targets, e.g. make yes-colloid mpi.
This is because the make procedure creates a list of source files that
will be out-of-date for the build if the package configuration changes
within the same command. You can include or exclude multiple packages
in a single make command, e.g. make yes-colloid no-manybody.
**CMake and make info**\ :
Any package can be included or excluded in a LAMMPS build, independent
of all other packages. However, some packages include files derived
from files in other packages. LAMMPS checks for this and does the
right thing. Individual files are only included if their dependencies
are already included. Likewise, if a package is excluded, other files
dependent on that package are also excluded.
When you download a LAMMPS tarball or download LAMMPS source files
from the Git or SVN repositories, no packages are pre-installed in the
src directory.
.. note::
Prior to Aug 2018, if you downloaded a tarball, 3 packages
(KSPACE, MANYBODY, MOLECULE) were pre-installed in the src directory.
That is no longer the case, so that CMake will build as-is without the
need to un-install those packages.
----------
**CMake shortcuts for installing many packages**\ :
Instead of specifying all the CMake options via the command-line,
CMake allows initializing the variable cache using script files. These
are regular CMake files which can manipulate and set variables, and
can also contain control flow constructs.
LAMMPS includes several of these files to define configuration
"presets", similar to the options that exist for the Make based
system. Using these files you can enable/disable portions of the
available packages in LAMMPS. If you need a custom preset you can take
one of them as a starting point and customize it to your needs.
+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/all\_on.cmake [OPTIONS] ../cmake | enable all packages |
+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/all\_off.cmake [OPTIONS] ../cmake | disable all packages |
+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/minimal.cmake [OPTIONS] ../cmake | enable just a few core packages |
+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/most.cmake [OPTIONS] ../cmake | enable most common packages |
+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/nolib.cmake [OPTIONS] ../cmake | disable packages that do require extra libraries or tools |
+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/clang.cmake [OPTIONS] ../cmake | change settings to use the Clang compilers by default |
+-------------------------------------------------------------+-----------------------------------------------------------+
| cmake -C ../cmake/presets/mingw.cmake [OPTIONS] ../cmake | enable all packages compatible with MinGW compilers |
+-------------------------------------------------------------+-----------------------------------------------------------+
.. note::
Running cmake this way manipulates the variable cache in your
current build directory. You can combine multiple presets and options
in a single cmake run, or change settings incrementally by running
cmake with new flags.
**Example:**
.. parsed-literal::
# build LAMMPS with most commonly used packages, but then remove
# those requiring additional library or tools, but still enable
# GPU package and configure it for using CUDA. You can run.
mkdir build
cd build
cmake -C ../cmake/presets/most.cmake -C ../cmake/presets/nolib.cmake -D PKG_GPU=on -D GPU_API=cuda ../cmake
# to add another package, say BODY to the previous configuration you can run:
cmake -D PKG_BODY=on .
# to reset the package selection from above to the default of no packages
# but leaving all other settings untouched. You can run:
cmake -C ../cmake/presets/no_all.cmake .
----------
**Make shortcuts for installing many packages**\ :
The following commands are useful for managing package source files
and their installation when building LAMMPS via traditional make.
Just type "make" in lammps/src to see a one-line summary.
These commands install/un-install sets of packages:
+-----------------------------------+-----------------------------------------------------+
| make yes-all | install all packages |
+-----------------------------------+-----------------------------------------------------+
| make no-all | un-install all packages |
+-----------------------------------+-----------------------------------------------------+
| make yes-standard or make yes-std | install standard packages |
+-----------------------------------+-----------------------------------------------------+
| make no-standard or make no-std | un-install standard packages |
+-----------------------------------+-----------------------------------------------------+
| make yes-user | install user packages |
+-----------------------------------+-----------------------------------------------------+
| make no-user | un-install user packages |
+-----------------------------------+-----------------------------------------------------+
| make yes-lib | install packages that require extra libraries |
+-----------------------------------+-----------------------------------------------------+
| make no-lib | un-install packages that require extra libraries |
+-----------------------------------+-----------------------------------------------------+
| make yes-ext | install packages that require external libraries |
+-----------------------------------+-----------------------------------------------------+
| make no-ext | un-install packages that require external libraries |
+-----------------------------------+-----------------------------------------------------+
which install/un-install various sets of packages. Typing "make
package" will list all the these commands.
.. note::
Installing or un-installing a package works by simply copying
files back and forth between the main src directory and
sub-directories with the package name (e.g. src/KSPACE, src/USER-ATC),
so that the files are included or excluded when LAMMPS is built.
The following make commands help manage files that exist in both the
src directory and in package sub-directories. You do not normally
need to use these commands unless you are editing LAMMPS files or are
:doc:`installing a patch <Install_patch>` downloaded from the LAMMPS web
site.
Type "make package-status" or "make ps" to show which packages are
currently installed. For those that are installed, it will list any
files that are different in the src directory and package
sub-directory.
Type "make package-installed" or "make pi" to show which packages are
currently installed, without listing the status of packages that are
not installed.
Type "make package-update" or "make pu" to overwrite src files with
files from the package sub-directories if the package is installed.
It should be used after a :doc:`patch has been applied <Install_patch>`,
since patches only update the files in the package sub-directory, but
not the src files.
Type "make package-overwrite" to overwrite files in the package
sub-directories with src files.
Type "make package-diff" to list all differences between pairs of
files in both the src dir and a package dir.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

479
doc/src/Build_settings.rst Normal file
View File

@ -0,0 +1,479 @@
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 <cxx11>` when building all of LAMMPS
| :ref:`FFT library <fft>` for use with the :doc:`kspace\_style pppm <kspace_style>` command
| :ref:`Size of LAMMPS data types <size>`
| :ref:`Read or write compressed files <gzip>`
| :ref:`Output of JPG and PNG files <graphics>` via the :doc:`dump image <dump_image>` command
| :ref:`Output of movie files <graphics>` via the :doc:`dump\_movie <dump_image>` command
| :ref:`Memory allocation alignment <align>`
| :ref:`Workaround for long long integers <longlong>`
| :ref:`Error handling exceptions <exceptions>` when using LAMMPS as a library
|
----------
.. _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
---------------------
When the KSPACE package is included in a LAMMPS build, the
:doc:`kspace\_style pppm <kspace_style>` command performs 3d FFTs which
require use of an FFT library to compute 1d FFTs. The KISS FFT
library is included with LAMMPS but other libraries can be faster.
LAMMPS can use them if they are available on your system.
**CMake variables**\ :
.. parsed-literal::
-D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found, else KISS
-D FFT_SINGLE=value # yes or no (default), no = double precision
-D FFT_PACK=value # array (default) or pointer or memcpy
.. note::
The values for the FFT variable must be in upper-case. This is
an exception to the rule that all CMake variables can be specified
with lower-case values.
Usually these settings are all that is needed. If CMake cannot find
the FFT library, you can set these variables:
.. parsed-literal::
-D FFTW3_INCLUDE_DIRS=path # path to FFTW3 include files
-D FFTW3_LIBRARIES=path # path to FFTW3 libraries
-D MKL_INCLUDE_DIRS=path # ditto for Intel MKL library
-D MKL_LIBRARIES=path
**Makefile.machine settings**\ :
.. parsed-literal::
FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS
# default is KISS if not specified
FFT_INC = -DFFT_SINGLE # do not specify for double precision
FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY
# default is FFT\_PACK\_ARRAY if not specified
.. parsed-literal::
FFT_INC = -I/usr/local/include
FFT_PATH = -L/usr/local/lib
FFT_LIB = -lfftw3 # FFTW3 double precision
FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision
FFT_LIB = -lmkl_intel_lp64 -lmkl_sequential -lmkl_core # MKL with Intel compiler
FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU compier
As with CMake, you do not need to set paths in FFT\_INC or FFT\_PATH, if
make can find the FFT header and library files. You must specify
FFT\_LIB with the appropriate FFT libraries to include in the link.
**CMake and make info**\ :
The `KISS FFT library <http://kissfft.sf.net>`_ is included in the LAMMPS
distribution. It is portable across all platforms. Depending on the
size of the FFTs and the number of processors used, the other
libraries listed here can be faster.
However, note that long-range Coulombics are only a portion of the
per-timestep CPU cost, FFTs are only a portion of long-range
Coulombics, and 1d FFTs are only a portion of the FFT cost (parallel
communication can be costly). A breakdown of these timings is printed
to the screen at the end of a run using the :doc:`kspace\_style pppm <kspace_style>` command. The :doc:`Run output <Run_output>`
doc page gives more details.
FFTW is a fast, portable FFT library that should also work on any
platform and can be faster than the KISS FFT library. You can
download it from `www.fftw.org <http://www.fftw.org>`_. LAMMPS requires
version 3.X; the legacy version 2.1.X is no longer supported.
Building FFTW for your box should be as simple as ./configure; make;
make install. The install command typically requires root privileges
(e.g. invoke it via sudo), unless you specify a local directory with
the "--prefix" option of configure. Type "./configure --help" to see
various options.
The Intel MKL math library is part of the Intel compiler suite. It
can be used with the Intel or GNU compiler (see FFT\_LIB setting above).
Performing 3d FFTs in parallel can be time consuming due to data
access and required communication. This cost can be reduced by
performing single-precision FFTs instead of double precision. Single
precision means the real and imaginary parts of a complex datum are
4-byte floats. Double precision means they are 8-byte doubles. Note
that Fourier transform and related PPPM operations are somewhat less
sensitive to floating point truncation errors and thus the resulting
error is less than the difference in precision. Using the -DFFT\_SINGLE
setting trades off a little accuracy for reduced memory use and
parallel communication costs for transposing 3d FFT data.
When using -DFFT\_SINGLE with FFTW3 you may need to build the FFTW
library a second time with support for single-precision.
For FFTW3, do the following, which should produce the additional
library libfftw3f.a
.. parsed-literal::
make clean
./configure --enable-single; make; make install
Performing 3d FFTs requires communication to transpose the 3d FFT
grid. The data packing/unpacking for this can be done in one of 3
modes (ARRAY, POINTER, MEMCPY) as set by the FFT\_PACK syntax above.
Depending on the machine, the size of the FFT grid, the number of
processors used, one option may be slightly faster. The default is
ARRAY mode.
----------
.. _size:
Size of LAMMPS data types
------------------------------------
LAMMPS has a few integer data types which can be defined as 4-byte or
8-byte integers. The default setting of "smallbig" is almost always
adequate.
**CMake variable**\ :
.. parsed-literal::
-D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall
**Makefile.machine setting**\ :
.. parsed-literal::
LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL
# default is LAMMPS\_SMALLBIG if not specified
**CMake and make info**\ :
The default "smallbig" setting allows for simulations with:
* total atom count = 2\^63 atoms (about 9e18)
* total timesteps = 2\^63 (about 9e18)
* atom IDs = 2\^31 (about 2 billion)
* image flags = roll over at 512
The "bigbig" setting increases the latter two limits. It allows for:
* total atom count = 2\^63 atoms (about 9e18)
* total timesteps = 2\^63 (about 9e18)
* atom IDs = 2\^63 (about 9e18)
* image flags = roll over at about 1 million (2\^20)
The "smallsmall" setting is only needed if your machine does not
support 8-byte integers. It allows for:
* total atom count = 2\^31 atoms (about 2 billion)
* total timesteps = 2\^31 (about 2 billion)
* atom IDs = 2\^31 (about 2 billion)
* image flags = roll over at 512 (2\^9)
Atom IDs are not required for atomic systems which do not store bond
topology information, though IDs are enabled by default. The
:doc:`atom\_modify id no <atom_modify>` command will turn them off. Atom
IDs are required for molecular systems with bond topology (bonds,
angles, dihedrals, etc). Thus if you model a molecular system with
more than 2 billion atoms, you need the "bigbig" setting.
Image flags store 3 values per atom which count the number of times an
atom has moved through the periodic box in each dimension. See the
:doc:`dump <dump>` doc page for a discussion. If an atom moves through
the periodic box more than this limit, the value will "roll over",
e.g. from 511 to -512, which can cause diagnostics like the
mean-squared displacement, as calculated by the :doc:`compute msd <compute_msd>` command, to be faulty.
Note that the USER-ATC package and the USER-INTEL package are currently
not compatible with the "bigbig" setting. Also, there are limitations
when using the library interface. Some functions with known issues
have been replaced by dummy calls printing a corresponding error rather
than crashing randomly or corrupting data.
Also note that the GPU package requires its lib/gpu library to be
compiled with the same size setting, or the link will fail. A CMake
build does this automatically. When building with make, the setting
in whichever lib/gpu/Makefile is used must be the same as above.
----------
.. _graphics:
Output of JPG, PNG, and movie files
--------------------------------------------------
The :doc:`dump image <dump_image>` command has options to output JPEG or
PNG image files. Likewise the :doc:`dump movie <dump_image>` command
outputs movie files in MPEG format. Using these options requires the
following settings:
**CMake variables**\ :
.. parsed-literal::
-D WITH_JPEG=value # yes or no
# default = yes if CMake finds JPEG files, else no
-D WITH_PNG=value # yes or no
# default = yes if CMake finds PNG and ZLIB files, else no
-D WITH_FFMPEG=value # yes or no
# default = yes if CMake can find ffmpeg, else no
Usually these settings are all that is needed. If CMake cannot find
the graphics header, library, executable files, you can set these
variables:
.. parsed-literal::
-D JPEG_INCLUDE_DIR=path # path to jpeglib.h header file
-D JPEG_LIBRARIES=path # path to libjpeg.a (.so) file
-D PNG_INCLUDE_DIR=path # path to png.h header file
-D PNG_LIBRARIES=path # path to libpng.a (.so) file
-D ZLIB_INCLUDE_DIR=path # path to zlib.h header file
-D ZLIB_LIBRARIES=path # path to libz.a (.so) file
-D FFMPEG_EXECUTABLE=path # path to ffmpeg executable
**Makefile.machine settings**\ :
.. parsed-literal::
LMP_INC = -DLAMMPS_JPEG
LMP_INC = -DLAMMPS_PNG
LMP_INC = -DLAMMPS_FFMPEG
JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header files if make cannot find them
JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them
JPG_LIB = -ljpeg -lpng -lz # library names
As with CMake, you do not need to set JPG\_INC or JPG\_PATH, if make can
find the graphics header and library files. You must specify JPG\_LIB
with a list of graphics libraries to include in the link. You must
insure ffmpeg is in a directory where LAMMPS can find it at runtime,
i.e. a dir in your PATH environment variable.
**CMake and make info**\ :
Using ffmpeg to output movie files requires that your machine
supports the "popen" function in the standard runtime library.
.. note::
On some clusters with high-speed networks, using the fork()
library calls (required by popen()) can interfere with the fast
communication library and lead to simulations using ffmpeg to hang or
crash.
----------
.. _gzip:
Read or write compressed files
-----------------------------------------
If this option is enabled, large files can be read or written with
gzip compression by several LAMMPS commands, including
:doc:`read\_data <read_data>`, :doc:`rerun <rerun>`, and :doc:`dump <dump>`.
**CMake variables**\ :
.. parsed-literal::
-D WITH_GZIP=value # yes or no
# default is yes if CMake can find gzip, else no
-D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it
**Makefile.machine setting**\ :
.. parsed-literal::
LMP_INC = -DLAMMPS_GZIP
**CMake and make info**\ :
This option requires that your machine supports the "popen()" function
in the standard runtime library and that a gzip executable can be
found by LAMMPS during a run.
.. note::
On some clusters with high-speed networks, using the fork()
library calls (required by popen()) can interfere with the fast
communication library and lead to simulations using compressed output
or input to hang or crash. For selected operations, compressed file
I/O is also available using a compression library instead, which is
what the :ref:`COMPRESS package <PKG-COMPRESS>` enables.
----------
.. _align:
Memory allocation alignment
---------------------------------------
This setting enables the use of the posix\_memalign() call instead of
malloc() when LAMMPS allocates large chunks or memory. This can make
vector instructions on CPUs more efficient, if dynamically allocated
memory is aligned on larger-than-default byte boundaries.
On most current systems, the malloc() implementation returns
pointers that are aligned to 16-byte boundaries. Using SSE vector
instructions efficiently, however, requires memory blocks being
aligned on 64-byte boundaries.
**CMake variable**\ :
.. parsed-literal::
-D LAMMPS_MEMALIGN=value # 0, 8, 16, 32, 64 (default)
Use a LAMMPS\_MEMALIGN value of 0 to disable using posix\_memalign()
and revert to using the malloc() C-library function instead. When
compiling LAMMPS for Windows systems, malloc() will always be used
and this setting ignored.
**Makefile.machine setting**\ :
.. parsed-literal::
LMP_INC = -DLAMMPS_MEMALIGN=value # 8, 16, 32, 64
Do not set -DLAMMPS\_MEMALIGN, if you want to have memory allocated
with the malloc() function call instead. -DLAMMPS\_MEMALIGN **cannot**
be used on Windows, as it does use different function calls for
allocating aligned memory, that are not compatible with how LAMMPS
manages its dynamical memory.
----------
.. _longlong:
Workaround for long long integers
------------------------------------------------
If your system or MPI version does not recognize "long long" data
types, the following setting will be needed. It converts "long long"
to a "long" data type, which should be the desired 8-byte integer on
those systems:
**CMake variable**\ :
.. parsed-literal::
-D LAMMPS_LONGLONG_TO_LONG=value # yes or no (default)
**Makefile.machine setting**\ :
.. parsed-literal::
LMP_INC = -DLAMMPS_LONGLONG_TO_LONG
----------
.. _exceptions:
Exception handling when using LAMMPS as a library
------------------------------------------------------------------
This setting is useful when external codes drive LAMMPS as a library.
With this option enabled LAMMPS errors do not kill the caller.
Instead, the call stack is unwound and control returns to the caller,
e.g. to Python.
**CMake variable**\ :
.. parsed-literal::
-D LAMMPS_EXCEPTIONS=value # yes or no (default)
**Makefile.machine setting**\ :
.. parsed-literal::
LMP_INC = -DLAMMPS_EXCEPTIONS
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

111
doc/src/Build_windows.rst Normal file
View File

@ -0,0 +1,111 @@
Notes for building LAMMPS on Windows
====================================
* :ref:`General remarks <generic>`
* :ref:`Running Linux on Windows <linux>`
* :ref:`Using GNU GCC ported to Windows <gnu>`
* :ref:`Using a cross-compiler <cross>`
----------
.. _generic:
General remarks
-----------------------------
LAMMPS is developed and tested primarily on Linux machines. The vast
majority of HPC clusters and supercomputers today runs on Linux as well.
Thus portability to other platforms is desired, but not always achieved.
The LAMMPS developers strongly rely on LAMMPS users giving feedback and
providing assistance in resolving portability issues. This particularly
true for compiling LAMMPS on Windows, since this platform has significant
differences with some low-level functionality.
.. _linux:
Running Linux on Windows
------------------------------------
So before trying to build LAMMPS on Windows, please consider if using
the pre-compiled Windows binary packages are sufficient for your needs
(as an aside, those packages themselves are build on a Linux machine
using cross-compilers). If it is necessary for your to compile LAMMPS
on a Windows machine (e.g. because it is your main desktop), please also
consider using a virtual machine software and run a Linux virtual machine,
or - if have a recently updated Windows 10 installation - consider using
the Windows subsystem for Linux, which allows to run a bash shell from
Ubuntu and from there on, you can pretty much use that shell like you
are running on an Ubuntu Linux machine (e.g. installing software via
apt-get). For more details on that, please see :doc:`this tutorial <Howto_bash>`
.. _gnu:
Using GNU GCC ported to Windows
-----------------------------------------
One option for compiling LAMMPS on Windows natively, that has been known
to work in the past is to install a bash shell, unix shell utilities,
perl, GNU make, and a GNU compiler ported to Windows. The Cygwin package
provides a unix/linux interface to low-level Windows functions, so LAMMPS
can be compiled on Windows. The necessary (minor) modifications to LAMMPS
are included, but may not always up-to-date for recently added functionality
and the corresponding new code. A machine makefile for using cygwin for
the old build system is provided. Using CMake for this mode of compilation
is untested and not likely to work.
When compiling for Windows do **not** set the -DLAMMPS\_MEMALIGN define
in the LMP\_INC makefile variable and add -lwsock32 -lpsapi to the linker
flags in LIB makefile variable. Try adding -static-libgcc or -static or
both to the linker flags when your resulting LAMMPS Windows executable
complains about missing .dll files. The CMake configuration should set
this up automatically, but is untested.
In case of problems, you are recommended to contact somebody with
experience in using cygwin. If you do come across portability problems
requiring changes to the LAMMPS source code, or figure out corrections
yourself, please report them on the lammps-users mailing list, or file
them as an issue or pull request on the LAMMPS GitHub project.
.. _cross:
Using a cross-compiler
----------------------------------
If you need to provide custom LAMMPS binaries for Windows, but do not
need to do the compilation on Windows, please consider using a Linux
to Windows cross-compiler. This is how currently the Windows binary
packages are created by the LAMMPS developers. Because of that, this is
probably the currently best tested and supported way to build LAMMPS
executables for Windows. There are makefiles provided for the
traditional build system, but CMake has also been successfully tested
using the mingw32-cmake and mingw64-cmake wrappers that are bundled
with the cross-compiler environment on Fedora machines. A CMake preset
selecting all packages compatible with this cross-compilation build
is provided. You likely need to disable the GPU package unless you
download and install the contents of the pre-compiled `OpenCL ICD loader library <https://download.lammps.org/thirdparty/opencl-win-devel.tar.gz>`_
into your MinGW64 cross-compiler environment. The cross-compilation
currently will only produce non-MPI serial binaries.
Please keep in mind, though, that this only applies to compiling LAMMPS.
Whether the resulting binaries do work correctly is no tested by the
LAMMPS developers. We instead rely on the feedback of the users
of these pre-compiled LAMMPS packages for Windows. We will try to resolve
issues to the best of our abilities if we become aware of them. However
this is subject to time constraints and focus on HPC platforms.
.. _native:
Native Visual C++ support
--------------------------------------
Support for the Visual C++ compilers is currently not available. The
CMake build system is capable of creating suitable a Visual Studio
style build environment, but the LAMMPS code itself is not fully ported
to support Visual C++. Volunteers to take on this task are welcome.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

34
doc/src/Commands.rst Normal file
View File

@ -0,0 +1,34 @@
Commands
********
These pages describe how a LAMMPS input script is formatted and the
commands in it are used to define a LAMMPS simulation.
.. toctree::
:maxdepth: 1
Commands_input
Commands_parse
Commands_structure
Commands_category
.. toctree::
:maxdepth: 1
Commands_all
Commands_fix
Commands_compute
Commands_pair
Commands_bond
Commands_kspace
.. toctree::
:maxdepth: 1
Commands_removed
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

59
doc/src/Commands_all.rst Normal file
View File

@ -0,0 +1,59 @@
+----------------------------------------+------------------------------------+------------------------------------------+
| :doc:`General commands <Commands_all>` | :doc:`Fix styles <Commands_fix>` | :doc:`Compute styles <Commands_compute>` |
+----------------------------------------+------------------------------------+------------------------------------------+
| :doc:`Pair styles <Commands_pair>` | :doc:`Bond styles <Commands_bond>` | :ref:`Angle styles <angle>` |
+----------------------------------------+------------------------------------+------------------------------------------+
| :ref:`Dihedral styles <dihedral>` | :ref:`Improper styles <improper>` | :doc:`KSpace styles <Commands_kspace>` |
+----------------------------------------+------------------------------------+------------------------------------------+
General commands
================
An alphabetic list of all general LAMMPS commands.
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`angle\_coeff <angle_coeff>` | :doc:`angle\_style <angle_style>` | :doc:`atom\_modify <atom_modify>` | :doc:`atom\_style <atom_style>` | :doc:`balance <balance>` | :doc:`bond\_coeff <bond_coeff>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`bond\_style <bond_style>` | :doc:`bond\_write <bond_write>` | :doc:`boundary <boundary>` | :doc:`box <box>` | :doc:`change\_box <change_box>` | :doc:`clear <clear>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`comm\_modify <comm_modify>` | :doc:`comm\_style <comm_style>` | :doc:`compute <compute>` | :doc:`compute\_modify <compute_modify>` | :doc:`create\_atoms <create_atoms>` | :doc:`create\_bonds <create_bonds>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`create\_box <create_box>` | :doc:`delete\_atoms <delete_atoms>` | :doc:`delete\_bonds <delete_bonds>` | :doc:`dielectric <dielectric>` | :doc:`dihedral\_coeff <dihedral_coeff>` | :doc:`dihedral\_style <dihedral_style>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`dimension <dimension>` | :doc:`displace\_atoms <displace_atoms>` | :doc:`dump <dump>` | :doc:`dump adios <dump_adios>` | :doc:`dump image <dump_image>` | :doc:`dump movie <dump_image>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`dump netcdf <dump_netcdf>` | :doc:`dump netcdf/mpiio <dump_netcdf>` | :doc:`dump vtk <dump_vtk>` | :doc:`dump\_modify <dump_modify>` | :doc:`dynamical\_matrix <dynamical_matrix>` | :doc:`echo <echo>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`fix <fix>` | :doc:`fix\_modify <fix_modify>` | :doc:`group <group>` | :doc:`group2ndx <group2ndx>` | :doc:`hyper <hyper>` | :doc:`if <if>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`info <info>` | :doc:`improper\_coeff <improper_coeff>` | :doc:`improper\_style <improper_style>` | :doc:`include <include>` | :doc:`jump <jump>` | :doc:`kim\_init <kim_commands>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`kim\_interactions <kim_commands>` | :doc:`kim\_query <kim_commands>` | :doc:`kspace\_modify <kspace_modify>` | :doc:`kspace\_style <kspace_style>` | :doc:`label <label>` | :doc:`lattice <lattice>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`log <log>` | :doc:`mass <mass>` | :doc:`message <message>` | :doc:`minimize <minimize>` | :doc:`min\_modify <min_modify>` | :doc:`min\_style <min_style>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`min\_style spin <min_spin>` | :doc:`molecule <molecule>` | :doc:`ndx2group <group2ndx>` | :doc:`neb <neb>` | :doc:`neb/spin <neb_spin>` | :doc:`neigh\_modify <neigh_modify>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`neighbor <neighbor>` | :doc:`newton <newton>` | :doc:`next <next>` | :doc:`package <package>` | :doc:`pair\_coeff <pair_coeff>` | :doc:`pair\_modify <pair_modify>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`pair\_style <pair_style>` | :doc:`pair\_write <pair_write>` | :doc:`partition <partition>` | :doc:`prd <prd>` | :doc:`print <print>` | :doc:`processors <processors>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`python <python>` | :doc:`quit <quit>` | :doc:`read\_data <read_data>` | :doc:`read\_dump <read_dump>` | :doc:`read\_restart <read_restart>` | :doc:`region <region>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`replicate <replicate>` | :doc:`rerun <rerun>` | :doc:`reset\_ids <reset_ids>` | :doc:`reset\_timestep <reset_timestep>` | :doc:`restart <restart>` | :doc:`run <run>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`run\_style <run_style>` | :doc:`server <server>` | :doc:`set <set>` | :doc:`shell <shell>` | :doc:`special\_bonds <special_bonds>` | :doc:`suffix <suffix>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`tad <tad>` | :doc:`temper <temper>` | :doc:`temper/grem <temper_grem>` | :doc:`temper/npt <temper_npt>` | :doc:`thermo <thermo>` | :doc:`thermo\_modify <thermo_modify>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`thermo\_style <thermo_style>` | :doc:`third\_order <third_order>` | :doc:`timer <timer>` | :doc:`timestep <timestep>` | :doc:`uncompute <uncompute>` | :doc:`undump <undump>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`unfix <unfix>` | :doc:`units <units>` | :doc:`variable <variable>` | :doc:`velocity <velocity>` | :doc:`write\_coeff <write_coeff>` | :doc:`write\_data <write_data>` |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
| :doc:`write\_dump <write_dump>` | :doc:`write\_restart <write_restart>` | | | | |
+-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

112
doc/src/Commands_bond.rst Normal file
View File

@ -0,0 +1,112 @@
.. _bond:
Bond\_style potentials
=================================
All LAMMPS :doc:`bond\_style <bond_style>` commands. Some styles 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 <bond_none>` | :doc:`zero <bond_zero>` | :doc:`hybrid <bond_hybrid>` | |
+---------------------------------------+-------------------------------------------------+---------------------------------------------------------+---------------------------------+
| | | | |
+---------------------------------------+-------------------------------------------------+---------------------------------------------------------+---------------------------------+
| :doc:`class2 (ko) <bond_class2>` | :doc:`fene (iko) <bond_fene>` | :doc:`fene/expand (o) <bond_fene_expand>` | :doc:`gromos (o) <bond_gromos>` |
+---------------------------------------+-------------------------------------------------+---------------------------------------------------------+---------------------------------+
| :doc:`harmonic (iko) <bond_harmonic>` | :doc:`harmonic/shift (o) <bond_harmonic_shift>` | :doc:`harmonic/shift/cut (o) <bond_harmonic_shift_cut>` | :doc:`mm3 <bond_mm3>` |
+---------------------------------------+-------------------------------------------------+---------------------------------------------------------+---------------------------------+
| :doc:`morse (o) <bond_morse>` | :doc:`nonlinear (o) <bond_nonlinear>` | :doc:`oxdna/fene <bond_oxdna>` | :doc:`oxdna2/fene <bond_oxdna>` |
+---------------------------------------+-------------------------------------------------+---------------------------------------------------------+---------------------------------+
| :doc:`quartic (o) <bond_quartic>` | :doc:`table (o) <bond_table>` | | |
+---------------------------------------+-------------------------------------------------+---------------------------------------------------------+---------------------------------+
----------
.. _angle:
Angle\_style potentials
===================================
All LAMMPS :doc:`angle\_style <angle_style>` commands. Some styles 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 <angle_none>` | :doc:`zero <angle_zero>` | :doc:`hybrid <angle_hybrid>` | |
+------------------------------------------------------+--------------------------------------------------+----------------------------------------------------+----------------------------------------------+
| | | | |
+------------------------------------------------------+--------------------------------------------------+----------------------------------------------------+----------------------------------------------+
| :doc:`charmm (iko) <angle_charmm>` | :doc:`class2 (ko) <angle_class2>` | :doc:`class2/p6 <angle_class2>` | :doc:`cosine (ko) <angle_cosine>` |
+------------------------------------------------------+--------------------------------------------------+----------------------------------------------------+----------------------------------------------+
| :doc:`cosine/buck6d <angle_cosine_buck6d>` | :doc:`cosine/delta (o) <angle_cosine_delta>` | :doc:`cosine/periodic (o) <angle_cosine_periodic>` | :doc:`cosine/shift (o) <angle_cosine_shift>` |
+------------------------------------------------------+--------------------------------------------------+----------------------------------------------------+----------------------------------------------+
| :doc:`cosine/shift/exp (o) <angle_cosine_shift_exp>` | :doc:`cosine/squared (o) <angle_cosine_squared>` | :doc:`cross <angle_cross>` | :doc:`dipole (o) <angle_dipole>` |
+------------------------------------------------------+--------------------------------------------------+----------------------------------------------------+----------------------------------------------+
| :doc:`fourier (o) <angle_fourier>` | :doc:`fourier/simple (o) <angle_fourier_simple>` | :doc:`harmonic (iko) <angle_harmonic>` | :doc:`mm3 <angle_mm3>` |
+------------------------------------------------------+--------------------------------------------------+----------------------------------------------------+----------------------------------------------+
| :doc:`quartic (o) <angle_quartic>` | :doc:`sdk (o) <angle_sdk>` | :doc:`table (o) <angle_table>` | |
+------------------------------------------------------+--------------------------------------------------+----------------------------------------------------+----------------------------------------------+
----------
.. _dihedral:
Dihedral\_style potentials
=========================================
All LAMMPS :doc:`dihedral\_style <dihedral_style>` commands. Some styles
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 <dihedral_none>` | :doc:`zero <dihedral_zero>` | :doc:`hybrid <dihedral_hybrid>` | |
+-------------------------------------------+-------------------------------------------+-------------------------------------------+---------------------------------------------------------+
| | | | |
+-------------------------------------------+-------------------------------------------+-------------------------------------------+---------------------------------------------------------+
| :doc:`charmm (iko) <dihedral_charmm>` | :doc:`charmmfsw <dihedral_charmm>` | :doc:`class2 (ko) <dihedral_class2>` | :doc:`cosine/shift/exp (o) <dihedral_cosine_shift_exp>` |
+-------------------------------------------+-------------------------------------------+-------------------------------------------+---------------------------------------------------------+
| :doc:`fourier (io) <dihedral_fourier>` | :doc:`harmonic (iko) <dihedral_harmonic>` | :doc:`helix (o) <dihedral_helix>` | :doc:`multi/harmonic (o) <dihedral_multi_harmonic>` |
+-------------------------------------------+-------------------------------------------+-------------------------------------------+---------------------------------------------------------+
| :doc:`nharmonic (o) <dihedral_nharmonic>` | :doc:`opls (iko) <dihedral_opls>` | :doc:`quadratic (o) <dihedral_quadratic>` | :doc:`spherical <dihedral_spherical>` |
+-------------------------------------------+-------------------------------------------+-------------------------------------------+---------------------------------------------------------+
| :doc:`table (o) <dihedral_table>` | :doc:`table/cut <dihedral_table_cut>` | | |
+-------------------------------------------+-------------------------------------------+-------------------------------------------+---------------------------------------------------------+
----------
.. _improper:
Improper\_style potentials
=========================================
All LAMMPS :doc:`improper\_style <improper_style>` commands. Some styles
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 <improper_none>` | :doc:`zero <improper_zero>` | :doc:`hybrid <improper_hybrid>` | |
+--------------------------------------+-----------------------------------------+-------------------------------------------+---------------------------------------------------------+
| | | | |
+--------------------------------------+-----------------------------------------+-------------------------------------------+---------------------------------------------------------+
| :doc:`class2 (ko) <improper_class2>` | :doc:`cossq (o) <improper_cossq>` | :doc:`cvff (io) <improper_cvff>` | :doc:`distance <improper_distance>` |
+--------------------------------------+-----------------------------------------+-------------------------------------------+---------------------------------------------------------+
| :doc:`distharm <improper_distharm>` | :doc:`fourier (o) <improper_fourier>` | :doc:`harmonic (iko) <improper_harmonic>` | :doc:`inversion/harmonic <improper_inversion_harmonic>` |
+--------------------------------------+-----------------------------------------+-------------------------------------------+---------------------------------------------------------+
| :doc:`ring (o) <improper_ring>` | :doc:`sqdistharm <improper_sqdistharm>` | :doc:`umbrella (o) <improper_umbrella>` | |
+--------------------------------------+-----------------------------------------+-------------------------------------------+---------------------------------------------------------+
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

137
doc/src/Commands_category.rst Normal file
View File

@ -0,0 +1,137 @@
Commands by category
====================
This page lists most of the LAMMPS commands, grouped by category. The
:doc:`General commands <Commands_all>` doc page lists all general commands
alphabetically. Style options for entries like fix, compute, pair etc.
have their own pages where they are listed alphabetically.
Initialization:
* :doc:`newton <newton>`,
* :doc:`package <package>`,
* :doc:`processors <processors>`,
* :doc:`suffix <suffix>`,
* :doc:`units <units>`
Setup simulation box:
* :doc:`boundary <boundary>`,
* :doc:`box <box>`,
* :doc:`change\_box <change_box>`,
* :doc:`create\_box <create_box>`,
* :doc:`dimension <dimension>`,
* :doc:`lattice <lattice>`,
* :doc:`region <region>`
Setup atoms:
* :doc:`atom\_modify <atom_modify>`,
* :doc:`atom\_style <atom_style>`,
* :doc:`balance <balance>`,
* :doc:`create\_atoms <create_atoms>`,
* :doc:`create\_bonds <create_bonds>`,
* :doc:`delete\_atoms <delete_atoms>`,
* :doc:`delete\_bonds <delete_bonds>`,
* :doc:`displace\_atoms <displace_atoms>`,
* :doc:`group <group>`,
* :doc:`mass <mass>`,
* :doc:`molecule <molecule>`,
* :doc:`read\_data <read_data>`,
* :doc:`read\_dump <read_dump>`,
* :doc:`read\_restart <read_restart>`,
* :doc:`replicate <replicate>`,
* :doc:`set <set>`,
* :doc:`velocity <velocity>`
Force fields:
* :doc:`angle\_coeff <angle_coeff>`,
* :doc:`angle\_style <angle_style>`,
* :doc:`bond\_coeff <bond_coeff>`,
* :doc:`bond\_style <bond_style>`,
* :doc:`bond\_write <bond_write>`,
* :doc:`dielectric <dielectric>`,
* :doc:`dihedral\_coeff <dihedral_coeff>`,
* :doc:`dihedral\_style <dihedral_style>`,
* :doc:`improper\_coeff <improper_coeff>`,
* :doc:`improper\_style <improper_style>`,
* :doc:`kspace\_modify <kspace_modify>`,
* :doc:`kspace\_style <kspace_style>`,
* :doc:`pair\_coeff <pair_coeff>`,
* :doc:`pair\_modify <pair_modify>`,
* :doc:`pair\_style <pair_style>`,
* :doc:`pair\_write <pair_write>`,
* :doc:`special\_bonds <special_bonds>`
Settings:
* :doc:`comm\_modify <comm_modify>`,
* :doc:`comm\_style <comm_style>`,
* :doc:`info <info>`,
* :doc:`min\_modify <min_modify>`,
* :doc:`min\_style <min_style>`,
* :doc:`neigh\_modify <neigh_modify>`,
* :doc:`neighbor <neighbor>`,
* :doc:`partition <partition>`,
* :doc:`reset\_timestep <reset_timestep>`,
* :doc:`run\_style <run_style>`,
* :doc:`timer <timer>`,
* :doc:`timestep <timestep>`
Operations within timestepping (fixes) and diagnostics (computes):
* :doc:`compute <compute>`,
* :doc:`compute\_modify <compute_modify>`,
* :doc:`fix <fix>`,
* :doc:`fix\_modify <fix_modify>`,
* :doc:`uncompute <uncompute>`,
* :doc:`unfix <unfix>`
Output:
* :doc:`dump image <dump_image>`,
* :doc:`dump movie <dump_image>`,
* :doc:`dump <dump>`,
* :doc:`dump\_modify <dump_modify>`,
* :doc:`restart <restart>`,
* :doc:`thermo <thermo>`,
* :doc:`thermo\_modify <thermo_modify>`,
* :doc:`thermo\_style <thermo_style>`,
* :doc:`undump <undump>`,
* :doc:`write\_coeff <write_coeff>`,
* :doc:`write\_data <write_data>`,
* :doc:`write\_dump <write_dump>`,
* :doc:`write\_restart <write_restart>`
Actions:
* :doc:`minimize <minimize>`,
* :doc:`neb <neb>`,
* :doc:`neb\_spin <neb_spin>`,
* :doc:`prd <prd>`,
* :doc:`rerun <rerun>`,
* :doc:`run <run>`,
* :doc:`tad <tad>`,
* :doc:`temper <temper>`
Input script control:
* :doc:`clear <clear>`,
* :doc:`echo <echo>`,
* :doc:`if <if>`,
* :doc:`include <include>`,
* :doc:`jump <jump>`,
* :doc:`label <label>`,
* :doc:`log <log>`,
* :doc:`next <next>`,
* :doc:`print <print>`,
* :doc:`python <python>`,
* :doc:`quit <quit>`,
* :doc:`shell <shell>`,
* :doc:`variable <variable>`
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

70
doc/src/Commands_compute.rst Normal file
View File

@ -0,0 +1,70 @@
+----------------------------------------+------------------------------------+------------------------------------------+
| :doc:`General commands <Commands_all>` | :doc:`Fix styles <Commands_fix>` | :doc:`Compute styles <Commands_compute>` |
+----------------------------------------+------------------------------------+------------------------------------------+
| :doc:`Pair styles <Commands_pair>` | :doc:`Bond styles <Commands_bond>` | :ref:`Angle styles <angle>` |
+----------------------------------------+------------------------------------+------------------------------------------+
| :ref:`Dihedral styles <dihedral>` | :ref:`Improper styles <improper>` | :doc:`KSpace styles <Commands_kspace>` |
+----------------------------------------+------------------------------------+------------------------------------------+
Compute commands
================
An alphabetic list of all LAMMPS :doc:`compute <compute>` commands.
Some styles have accelerated versions. This is indicated by
additional letters in parenthesis: g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`ackland/atom <compute_ackland_atom>` | :doc:`adf <compute_adf>` | :doc:`aggregate/atom <compute_cluster_atom>` | :doc:`angle <compute_angle>` | :doc:`angle/local <compute_angle_local>` | :doc:`angmom/chunk <compute_angmom_chunk>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`basal/atom <compute_basal_atom>` | :doc:`body/local <compute_body_local>` | :doc:`bond <compute_bond>` | :doc:`bond/local <compute_bond_local>` | :doc:`centro/atom <compute_centro_atom>` | :doc:`chunk/atom <compute_chunk_atom>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`chunk/spread/atom <compute_chunk_spread_atom>` | :doc:`cluster/atom <compute_cluster_atom>` | :doc:`cna/atom <compute_cna_atom>` | :doc:`cnp/atom <compute_cnp_atom>` | :doc:`com <compute_com>` | :doc:`com/chunk <compute_com_chunk>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`contact/atom <compute_contact_atom>` | :doc:`coord/atom <compute_coord_atom>` | :doc:`damage/atom <compute_damage_atom>` | :doc:`dihedral <compute_dihedral>` | :doc:`dihedral/local <compute_dihedral_local>` | :doc:`dilatation/atom <compute_dilatation_atom>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`dipole/chunk <compute_dipole_chunk>` | :doc:`displace/atom <compute_displace_atom>` | :doc:`dpd <compute_dpd>` | :doc:`dpd/atom <compute_dpd_atom>` | :doc:`edpd/temp/atom <compute_edpd_temp_atom>` | :doc:`entropy/atom <compute_entropy_atom>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`erotate/asphere <compute_erotate_asphere>` | :doc:`erotate/rigid <compute_erotate_rigid>` | :doc:`erotate/sphere <compute_erotate_sphere>` | :doc:`erotate/sphere/atom <compute_erotate_sphere_atom>` | :doc:`event/displace <compute_event_displace>` | :doc:`fep <compute_fep>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`force/tally <compute_tally>` | :doc:`fragment/atom <compute_cluster_atom>` | :doc:`global/atom <compute_global_atom>` | :doc:`group/group <compute_group_group>` | :doc:`gyration <compute_gyration>` | :doc:`gyration/chunk <compute_gyration_chunk>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`gyration/shape <compute_gyration_shape>` | :doc:`gyration/shape/chunk <compute_gyration_shape_chunk>` | :doc:`heat/flux <compute_heat_flux>` | :doc:`heat/flux/tally <compute_tally>` | :doc:`hexorder/atom <compute_hexorder_atom>` | :doc:`hma <compute_hma>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`improper <compute_improper>` | :doc:`improper/local <compute_improper_local>` | :doc:`inertia/chunk <compute_inertia_chunk>` | :doc:`ke <compute_ke>` | :doc:`ke/atom <compute_ke_atom>` | :doc:`ke/atom/eff <compute_ke_atom_eff>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`ke/eff <compute_ke_eff>` | :doc:`ke/rigid <compute_ke_rigid>` | :doc:`meso/e/atom <compute_meso_e_atom>` | :doc:`meso/rho/atom <compute_meso_rho_atom>` | :doc:`meso/t/atom <compute_meso_t_atom>` | :doc:`momentum <compute_momentum>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`msd <compute_msd>` | :doc:`msd/chunk <compute_msd_chunk>` | :doc:`msd/nongauss <compute_msd_nongauss>` | :doc:`omega/chunk <compute_omega_chunk>` | :doc:`orientorder/atom <compute_orientorder_atom>` | :doc:`pair <compute_pair>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`pair/local <compute_pair_local>` | :doc:`pe <compute_pe>` | :doc:`pe/atom <compute_pe_atom>` | :doc:`pe/mol/tally <compute_tally>` | :doc:`pe/tally <compute_tally>` | :doc:`plasticity/atom <compute_plasticity_atom>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`pressure <compute_pressure>` | :doc:`pressure/cylinder <compute_pressure_cylinder>` | :doc:`pressure/uef <compute_pressure_uef>` | :doc:`property/atom <compute_property_atom>` | :doc:`property/chunk <compute_property_chunk>` | :doc:`property/local <compute_property_local>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`ptm/atom <compute_ptm_atom>` | :doc:`rdf <compute_rdf>` | :doc:`reduce <compute_reduce>` | :doc:`reduce/chunk <compute_reduce_chunk>` | :doc:`reduce/region <compute_reduce>` | :doc:`rigid/local <compute_rigid_local>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`saed <compute_saed>` | :doc:`slice <compute_slice>` | :doc:`smd/contact/radius <compute_smd_contact_radius>` | :doc:`smd/damage <compute_smd_damage>` | :doc:`smd/hourglass/error <compute_smd_hourglass_error>` | :doc:`smd/internal/energy <compute_smd_internal_energy>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`smd/plastic/strain <compute_smd_plastic_strain>` | :doc:`smd/plastic/strain/rate <compute_smd_plastic_strain_rate>` | :doc:`smd/rho <compute_smd_rho>` | :doc:`smd/tlsph/defgrad <compute_smd_tlsph_defgrad>` | :doc:`smd/tlsph/dt <compute_smd_tlsph_dt>` | :doc:`smd/tlsph/num/neighs <compute_smd_tlsph_num_neighs>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`smd/tlsph/shape <compute_smd_tlsph_shape>` | :doc:`smd/tlsph/strain <compute_smd_tlsph_strain>` | :doc:`smd/tlsph/strain/rate <compute_smd_tlsph_strain_rate>` | :doc:`smd/tlsph/stress <compute_smd_tlsph_stress>` | :doc:`smd/triangle/vertices <compute_smd_triangle_vertices>` | :doc:`smd/ulsph/num/neighs <compute_smd_ulsph_num_neighs>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`smd/ulsph/strain <compute_smd_ulsph_strain>` | :doc:`smd/ulsph/strain/rate <compute_smd_ulsph_strain_rate>` | :doc:`smd/ulsph/stress <compute_smd_ulsph_stress>` | :doc:`smd/vol <compute_smd_vol>` | :doc:`sna/atom <compute_sna_atom>` | :doc:`snad/atom <compute_sna_atom>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`snav/atom <compute_sna_atom>` | :doc:`spin <compute_spin>` | :doc:`stress/atom <compute_stress_atom>` | :doc:`stress/mop <compute_stress_mop>` | :doc:`stress/mop/profile <compute_stress_mop>` | :doc:`stress/tally <compute_tally>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`tdpd/cc/atom <compute_tdpd_cc_atom>` | :doc:`temp (k) <compute_temp>` | :doc:`temp/asphere <compute_temp_asphere>` | :doc:`temp/body <compute_temp_body>` | :doc:`temp/chunk <compute_temp_chunk>` | :doc:`temp/com <compute_temp_com>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`temp/cs <compute_temp_cs>` | :doc:`temp/deform <compute_temp_deform>` | :doc:`temp/deform/eff <compute_temp_deform_eff>` | :doc:`temp/drude <compute_temp_drude>` | :doc:`temp/eff <compute_temp_eff>` | :doc:`temp/partial <compute_temp_partial>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`temp/profile <compute_temp_profile>` | :doc:`temp/ramp <compute_temp_ramp>` | :doc:`temp/region <compute_temp_region>` | :doc:`temp/region/eff <compute_temp_region_eff>` | :doc:`temp/rotate <compute_temp_rotate>` | :doc:`temp/sphere <compute_temp_sphere>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`temp/uef <compute_temp_uef>` | :doc:`ti <compute_ti>` | :doc:`torque/chunk <compute_torque_chunk>` | :doc:`vacf <compute_vacf>` | :doc:`vcm/chunk <compute_vcm_chunk>` | :doc:`voronoi/atom <compute_voronoi_atom>` |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
| :doc:`xrd <compute_xrd>` | | | | | |
+--------------------------------------------------------+------------------------------------------------------------------+--------------------------------------------------------------+----------------------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------+
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

94
doc/src/Commands_fix.rst Normal file
View File

@ -0,0 +1,94 @@
+----------------------------------------+------------------------------------+------------------------------------------+
| :doc:`General commands <Commands_all>` | :doc:`Fix styles <Commands_fix>` | :doc:`Compute styles <Commands_compute>` |
+----------------------------------------+------------------------------------+------------------------------------------+
| :doc:`Pair styles <Commands_pair>` | :doc:`Bond styles <Commands_bond>` | :ref:`Angle styles <angle>` |
+----------------------------------------+------------------------------------+------------------------------------------+
| :ref:`Dihedral styles <dihedral>` | :ref:`Improper styles <improper>` | :doc:`KSpace styles <Commands_kspace>` |
+----------------------------------------+------------------------------------+------------------------------------------+
Fix commands
============
An alphabetic list of all LAMMPS :doc:`fix <fix>` commands. Some styles
have accelerated versions. This is indicated by additional letters in
parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t =
OPT.
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`adapt <fix_adapt>` | :doc:`adapt/fep <fix_adapt_fep>` | :doc:`addforce <fix_addforce>` | :doc:`addtorque <fix_addtorque>` | :doc:`append/atoms <fix_append_atoms>` | :doc:`atc <fix_atc>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`atom/swap <fix_atom_swap>` | :doc:`ave/atom <fix_ave_atom>` | :doc:`ave/chunk <fix_ave_chunk>` | :doc:`ave/correlate <fix_ave_correlate>` | :doc:`ave/correlate/long <fix_ave_correlate_long>` | :doc:`ave/histo <fix_ave_histo>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`ave/histo/weight <fix_ave_histo>` | :doc:`ave/time <fix_ave_time>` | :doc:`aveforce <fix_aveforce>` | :doc:`balance <fix_balance>` | :doc:`bocs <fix_bocs>` | :doc:`bond/break <fix_bond_break>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`bond/create <fix_bond_create>` | :doc:`bond/react <fix_bond_react>` | :doc:`bond/swap <fix_bond_swap>` | :doc:`box/relax <fix_box_relax>` | :doc:`client/md <fix_client_md>` | :doc:`cmap <fix_cmap>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`colvars <fix_colvars>` | :doc:`controller <fix_controller>` | :doc:`deform (k) <fix_deform>` | :doc:`deposit <fix_deposit>` | :doc:`dpd/energy (k) <fix_dpd_energy>` | :doc:`drag <fix_drag>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`drude <fix_drude>` | :doc:`drude/transform/direct <fix_drude_transform>` | :doc:`drude/transform/inverse <fix_drude_transform>` | :doc:`dt/reset <fix_dt_reset>` | :doc:`edpd/source <fix_dpd_source>` | :doc:`efield <fix_efield>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`ehex <fix_ehex>` | :doc:`electron/stopping <fix_electron_stopping>` | :doc:`enforce2d (k) <fix_enforce2d>` | :doc:`eos/cv <fix_eos_cv>` | :doc:`eos/table <fix_eos_table>` | :doc:`eos/table/rx (k) <fix_eos_table_rx>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`evaporate <fix_evaporate>` | :doc:`external <fix_external>` | :doc:`ffl <fix_ffl>` | :doc:`filter/corotate <fix_filter_corotate>` | :doc:`flow/gauss <fix_flow_gauss>` | :doc:`freeze (k) <fix_freeze>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`gcmc <fix_gcmc>` | :doc:`gld <fix_gld>` | :doc:`gle <fix_gle>` | :doc:`gravity (ko) <fix_gravity>` | :doc:`grem <fix_grem>` | :doc:`halt <fix_halt>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`heat <fix_heat>` | :doc:`hyper/global <fix_hyper_global>` | :doc:`hyper/local <fix_hyper_local>` | :doc:`imd <fix_imd>` | :doc:`indent <fix_indent>` | :doc:`ipi <fix_ipi>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`langevin (k) <fix_langevin>` | :doc:`langevin/drude <fix_langevin_drude>` | :doc:`langevin/eff <fix_langevin_eff>` | :doc:`langevin/spin <fix_langevin_spin>` | :doc:`latte <fix_latte>` | :doc:`lb/fluid <fix_lb_fluid>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`lb/momentum <fix_lb_momentum>` | :doc:`lb/pc <fix_lb_pc>` | :doc:`lb/rigid/pc/sphere <fix_lb_rigid_pc_sphere>` | :doc:`lb/viscous <fix_lb_viscous>` | :doc:`lineforce <fix_lineforce>` | :doc:`manifoldforce <fix_manifoldforce>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`meso <fix_meso>` | :doc:`meso/move <fix_meso_move>` | :doc:`meso/stationary <fix_meso_stationary>` | :doc:`momentum (k) <fix_momentum>` | :doc:`move <fix_move>` | :doc:`mscg <fix_mscg>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`msst <fix_msst>` | :doc:`mvv/dpd <fix_mvv_dpd>` | :doc:`mvv/edpd <fix_mvv_dpd>` | :doc:`mvv/tdpd <fix_mvv_dpd>` | :doc:`neb <fix_neb>` | :doc:`neb\_spin <fix_neb_spin>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`nph (ko) <fix_nh>` | :doc:`nph/asphere (o) <fix_nph_asphere>` | :doc:`nph/body <fix_nph_body>` | :doc:`nph/eff <fix_nh_eff>` | :doc:`nph/sphere (o) <fix_nph_sphere>` | :doc:`nphug (o) <fix_nphug>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`npt (iko) <fix_nh>` | :doc:`npt/asphere (o) <fix_npt_asphere>` | :doc:`npt/body <fix_npt_body>` | :doc:`npt/eff <fix_nh_eff>` | :doc:`npt/sphere (o) <fix_npt_sphere>` | :doc:`npt/uef <fix_nh_uef>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`nve (iko) <fix_nve>` | :doc:`nve/asphere (i) <fix_nve_asphere>` | :doc:`nve/asphere/noforce <fix_nve_asphere_noforce>` | :doc:`nve/awpmd <fix_nve_awpmd>` | :doc:`nve/body <fix_nve_body>` | :doc:`nve/dot <fix_nve_dot>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`nve/dotc/langevin <fix_nve_dotc_langevin>` | :doc:`nve/eff <fix_nve_eff>` | :doc:`nve/limit <fix_nve_limit>` | :doc:`nve/line <fix_nve_line>` | :doc:`nve/manifold/rattle <fix_nve_manifold_rattle>` | :doc:`nve/noforce <fix_nve_noforce>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`nve/sphere (ko) <fix_nve_sphere>` | :doc:`nve/spin <fix_nve_spin>` | :doc:`nve/tri <fix_nve_tri>` | :doc:`nvk <fix_nvk>` | :doc:`nvt (iko) <fix_nh>` | :doc:`nvt/asphere (o) <fix_nvt_asphere>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`nvt/body <fix_nvt_body>` | :doc:`nvt/eff <fix_nh_eff>` | :doc:`nvt/manifold/rattle <fix_nvt_manifold_rattle>` | :doc:`nvt/sllod (io) <fix_nvt_sllod>` | :doc:`nvt/sllod/eff <fix_nvt_sllod_eff>` | :doc:`nvt/sphere (o) <fix_nvt_sphere>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`nvt/uef <fix_nh_uef>` | :doc:`oneway <fix_oneway>` | :doc:`orient/bcc <fix_orient>` | :doc:`orient/fcc <fix_orient>` | :doc:`phonon <fix_phonon>` | :doc:`pimd <fix_pimd>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`planeforce <fix_planeforce>` | :doc:`plumed <fix_plumed>` | :doc:`poems <fix_poems>` | :doc:`pour <fix_pour>` | :doc:`precession/spin <fix_precession_spin>` | :doc:`press/berendsen <fix_press_berendsen>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`print <fix_print>` | :doc:`property/atom (k) <fix_property_atom>` | :doc:`python/invoke <fix_python_invoke>` | :doc:`python/move <fix_python_move>` | :doc:`qbmsst <fix_qbmsst>` | :doc:`qeq/comb (o) <fix_qeq_comb>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`qeq/dynamic <fix_qeq>` | :doc:`qeq/fire <fix_qeq>` | :doc:`qeq/point <fix_qeq>` | :doc:`qeq/reax (ko) <fix_qeq_reax>` | :doc:`qeq/shielded <fix_qeq>` | :doc:`qeq/slater <fix_qeq>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`qmmm <fix_qmmm>` | :doc:`qtb <fix_qtb>` | :doc:`rattle <fix_shake>` | :doc:`reax/c/bonds (k) <fix_reaxc_bonds>` | :doc:`reax/c/species (k) <fix_reaxc_species>` | :doc:`recenter <fix_recenter>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`restrain <fix_restrain>` | :doc:`rhok <fix_rhok>` | :doc:`rigid (o) <fix_rigid>` | :doc:`rigid/meso <fix_rigid_meso>` | :doc:`rigid/nph (o) <fix_rigid>` | :doc:`rigid/nph/small <fix_rigid>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`rigid/npt (o) <fix_rigid>` | :doc:`rigid/npt/small <fix_rigid>` | :doc:`rigid/nve (o) <fix_rigid>` | :doc:`rigid/nve/small <fix_rigid>` | :doc:`rigid/nvt (o) <fix_rigid>` | :doc:`rigid/nvt/small <fix_rigid>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`rigid/small (o) <fix_rigid>` | :doc:`rx (k) <fix_rx>` | :doc:`saed/vtk <fix_saed_vtk>` | :doc:`setforce (k) <fix_setforce>` | :doc:`shake <fix_shake>` | :doc:`shardlow (k) <fix_shardlow>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`smd <fix_smd>` | :doc:`smd/adjust\_dt <fix_smd_adjust_dt>` | :doc:`smd/integrate\_tlsph <fix_smd_integrate_tlsph>` | :doc:`smd/integrate\_ulsph <fix_smd_integrate_ulsph>` | :doc:`smd/move\_tri\_surf <fix_smd_move_triangulated_surface>` | :doc:`smd/setvel <fix_smd_setvel>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`smd/wall\_surface <fix_smd_wall_surface>` | :doc:`spring <fix_spring>` | :doc:`spring/chunk <fix_spring_chunk>` | :doc:`spring/rg <fix_spring_rg>` | :doc:`spring/self <fix_spring_self>` | :doc:`srd <fix_srd>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`store/force <fix_store_force>` | :doc:`store/state <fix_store_state>` | :doc:`tdpd/source <fix_dpd_source>` | :doc:`temp/berendsen <fix_temp_berendsen>` | :doc:`temp/csld <fix_temp_csvr>` | :doc:`temp/csvr <fix_temp_csvr>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`temp/rescale <fix_temp_rescale>` | :doc:`temp/rescale/eff <fix_temp_rescale_eff>` | :doc:`tfmc <fix_tfmc>` | :doc:`thermal/conductivity <fix_thermal_conductivity>` | :doc:`ti/spring <fix_ti_spring>` | :doc:`tmd <fix_tmd>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`ttm <fix_ttm>` | :doc:`ttm/mod <fix_ttm>` | :doc:`tune/kspace <fix_tune_kspace>` | :doc:`vector <fix_vector>` | :doc:`viscosity <fix_viscosity>` | :doc:`viscous <fix_viscous>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`wall/body/polygon <fix_wall_body_polygon>` | :doc:`wall/body/polyhedron <fix_wall_body_polyhedron>` | :doc:`wall/colloid <fix_wall>` | :doc:`wall/ees <fix_wall_ees>` | :doc:`wall/gran <fix_wall_gran>` | :doc:`wall/gran/region <fix_wall_gran_region>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`wall/harmonic <fix_wall>` | :doc:`wall/lj1043 <fix_wall>` | :doc:`wall/lj126 <fix_wall>` | :doc:`wall/lj93 (k) <fix_wall>` | :doc:`wall/morse <fix_wall>` | :doc:`wall/piston <fix_wall_piston>` |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
| :doc:`wall/reflect (k) <fix_wall_reflect>` | :doc:`wall/region <fix_wall_region>` | :doc:`wall/region/ees <fix_wall_ees>` | :doc:`wall/srd <fix_wall_srd>` | | |
+--------------------------------------------------+--------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------+----------------------------------------------------------------+------------------------------------------------+
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

42
doc/src/Commands_input.txt → doc/src/Commands_input.rst
View File

@ -1,13 +1,5 @@
"Higher level section"_Commands.html - "LAMMPS WWW Site"_lws - "LAMMPS
Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Commands_all.html)
:line
LAMMPS input scripts :h3
LAMMPS input scripts
====================
LAMMPS executes by reading commands from a input script (text file),
one line at a time. When the input script ends, LAMMPS exits. Each
@ -24,15 +16,21 @@ simulation with all the settings. Rather, the input script is read
one line at a time and each command takes effect when it is read.
Thus this sequence of commands:
timestep 0.5
run 100
run 100 :pre
.. code-block:: LAMMPS
timestep 0.5
run 100
run 100
does something different than this sequence:
run 100
timestep 0.5
run 100 :pre
.. code-block:: LAMMPS
run 100
timestep 0.5
run 100
In the first case, the specified timestep (0.5 fs) is used for two
simulations of 100 timesteps each. In the 2nd case, the default
@ -47,14 +45,18 @@ belong to the group.
(3) Sometimes command B will use values that can be set by command A.
This means command A must precede command B in the input script if it
is to have the desired effect. For example, the
"read_data"_read_data.html command initializes the system by setting
:doc:`read\_data <read_data>` command initializes the system by setting
up the simulation box and assigning atoms to processors. If default
values are not desired, the "processors"_processors.html and
"boundary"_boundary.html commands need to be used before read_data to
values are not desired, the :doc:`processors <processors>` and
:doc:`boundary <boundary>` commands need to be used before read\_data to
tell LAMMPS how to map processors to the simulation box.
Many input script errors are detected by LAMMPS and an ERROR or
WARNING message is printed. The "Errors"_Errors.html doc page gives
WARNING message is printed. The :doc:`Errors <Errors>` doc page gives
more information on what errors mean. The documentation for each
command lists restrictions on how the command can be used.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

28
doc/src/Commands_kspace.rst Normal file
View File

@ -0,0 +1,28 @@
+----------------------------------------+------------------------------------+------------------------------------------+
| :doc:`General commands <Commands_all>` | :doc:`Fix styles <Commands_fix>` | :doc:`Compute styles <Commands_compute>` |
+----------------------------------------+------------------------------------+------------------------------------------+
| :doc:`Pair styles <Commands_pair>` | :doc:`Bond styles <Commands_bond>` | :ref:`Angle styles <angle>` |
+----------------------------------------+------------------------------------+------------------------------------------+
| :ref:`Dihedral styles <dihedral>` | :ref:`Improper styles <improper>` | :doc:`KSpace styles <Commands_kspace>` |
+----------------------------------------+------------------------------------+------------------------------------------+
KSpace solvers
==============
All LAMMPS :doc:`kspace\_style <kspace_style>` solvers. Some styles have
accelerated versions. This is indicated by additional letters in
parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t =
OPT.
+------------------------------------+--------------------------------------+-------------------------------------+---------------------------------------+
| :doc:`ewald (o) <kspace_style>` | :doc:`ewald/disp <kspace_style>` | :doc:`msm (o) <kspace_style>` | :doc:`msm/cg (o) <kspace_style>` |
+------------------------------------+--------------------------------------+-------------------------------------+---------------------------------------+
| :doc:`pppm (gok) <kspace_style>` | :doc:`pppm/cg (o) <kspace_style>` | :doc:`pppm/disp (i) <kspace_style>` | :doc:`pppm/disp/tip4p <kspace_style>` |
+------------------------------------+--------------------------------------+-------------------------------------+---------------------------------------+
| :doc:`pppm/stagger <kspace_style>` | :doc:`pppm/tip4p (o) <kspace_style>` | :doc:`scafacos <kspace_style>` | |
+------------------------------------+--------------------------------------+-------------------------------------+---------------------------------------+
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

136
doc/src/Commands_pair.rst Normal file
View File

@ -0,0 +1,136 @@
+----------------------------------------+------------------------------------+------------------------------------------+
| :doc:`General commands <Commands_all>` | :doc:`Fix styles <Commands_fix>` | :doc:`Compute styles <Commands_compute>` |
+----------------------------------------+------------------------------------+------------------------------------------+
| :doc:`Pair styles <Commands_pair>` | :doc:`Bond styles <Commands_bond>` | :ref:`Angle styles <angle>` |
+----------------------------------------+------------------------------------+------------------------------------------+
| :ref:`Dihedral styles <dihedral>` | :ref:`Improper styles <improper>` | :doc:`KSpace styles <Commands_kspace>` |
+----------------------------------------+------------------------------------+------------------------------------------+
Pair\_style potentials
======================
All LAMMPS :doc:`pair\_style <pair_style>` commands. Some styles 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 <pair_none>` | :doc:`zero <pair_zero>` | :doc:`hybrid (k) <pair_hybrid>` | :doc:`hybrid/overlay (k) <pair_hybrid>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| | | | |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`adp (o) <pair_adp>` | :doc:`agni (o) <pair_agni>` | :doc:`airebo (io) <pair_airebo>` | :doc:`airebo/morse (io) <pair_airebo>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`atm <pair_atm>` | :doc:`awpmd/cut <pair_awpmd>` | :doc:`beck (go) <pair_beck>` | :doc:`body/nparticle <pair_body_nparticle>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`body/rounded/polygon <pair_body_rounded_polygon>` | :doc:`body/rounded/polyhedron <pair_body_rounded_polyhedron>` | :doc:`bop <pair_bop>` | :doc:`born (go) <pair_born>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`born/coul/dsf <pair_born>` | :doc:`born/coul/dsf/cs <pair_cs>` | :doc:`born/coul/long (go) <pair_born>` | :doc:`born/coul/long/cs (g) <pair_cs>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`born/coul/msm (o) <pair_born>` | :doc:`born/coul/wolf (go) <pair_born>` | :doc:`born/coul/wolf/cs (g) <pair_cs>` | :doc:`brownian (o) <pair_brownian>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`brownian/poly (o) <pair_brownian>` | :doc:`buck (giko) <pair_buck>` | :doc:`buck/coul/cut (giko) <pair_buck>` | :doc:`buck/coul/long (giko) <pair_buck>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`buck/coul/long/cs <pair_cs>` | :doc:`buck/coul/msm (o) <pair_buck>` | :doc:`buck/long/coul/long (o) <pair_buck_long>` | :doc:`buck/mdf <pair_mdf>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`buck6d/coul/gauss/dsf <pair_buck6d_coul_gauss>` | :doc:`buck6d/coul/gauss/long <pair_buck6d_coul_gauss>` | :doc:`colloid (go) <pair_colloid>` | :doc:`comb (o) <pair_comb>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`comb3 <pair_comb>` | :doc:`cosine/squared <pair_cosine_squared>` | :doc:`coul/cut (gko) <pair_coul>` | :doc:`coul/cut/soft (o) <pair_fep_soft>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`coul/debye (gko) <pair_coul>` | :doc:`coul/diel (o) <pair_coul_diel>` | :doc:`coul/dsf (gko) <pair_coul>` | :doc:`coul/long (gko) <pair_coul>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`coul/long/cs (g) <pair_cs>` | :doc:`coul/long/soft (o) <pair_fep_soft>` | :doc:`coul/msm (o) <pair_coul>` | :doc:`coul/shield <pair_coul_shield>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`coul/streitz <pair_coul>` | :doc:`coul/wolf (ko) <pair_coul>` | :doc:`coul/wolf/cs <pair_cs>` | :doc:`dpd (gio) <pair_dpd>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`dpd/fdt <pair_dpd_fdt>` | :doc:`dpd/fdt/energy (k) <pair_dpd_fdt>` | :doc:`dpd/tstat (go) <pair_dpd>` | :doc:`dsmc <pair_dsmc>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`e3b <pair_e3b>` | :doc:`drip <pair_drip>` | :doc:`eam (gikot) <pair_eam>` | :doc:`eam/alloy (gikot) <pair_eam>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`eam/cd (o) <pair_eam>` | :doc:`eam/cd/old (o) <pair_eam>` | :doc:`eam/fs (gikot) <pair_eam>` | :doc:`edip (o) <pair_edip>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`edip/multi <pair_edip>` | :doc:`edpd <pair_meso>` | :doc:`eff/cut <pair_eff>` | :doc:`eim (o) <pair_eim>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`exp6/rx (k) <pair_exp6_rx>` | :doc:`extep <pair_extep>` | :doc:`gauss (go) <pair_gauss>` | :doc:`gauss/cut (o) <pair_gauss>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`gayberne (gio) <pair_gayberne>` | :doc:`gran/hertz/history (o) <pair_gran>` | :doc:`gran/hooke (o) <pair_gran>` | :doc:`gran/hooke/history (ko) <pair_gran>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`granular <pair_granular>` | :doc:`gw <pair_gw>` | :doc:`gw/zbl <pair_gw>` | :doc:`hbond/dreiding/lj (o) <pair_hbond_dreiding>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`hbond/dreiding/morse (o) <pair_hbond_dreiding>` | :doc:`ilp/graphene/hbn <pair_ilp_graphene_hbn>` | :doc:`kim <pair_kim>` | :doc:`kolmogorov/crespi/full <pair_kolmogorov_crespi_full>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`kolmogorov/crespi/z <pair_kolmogorov_crespi_z>` | :doc:`lcbop <pair_lcbop>` | :doc:`lebedeva/z <pair_lebedeva_z>` | :doc:`lennard/mdf <pair_mdf>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`line/lj <pair_line_lj>` | :doc:`list <pair_list>` | :doc:`lj/charmm/coul/charmm (iko) <pair_charmm>` | :doc:`lj/charmm/coul/charmm/implicit (ko) <pair_charmm>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`lj/charmm/coul/long (gikot) <pair_charmm>` | :doc:`lj/charmm/coul/long/soft (o) <pair_fep_soft>` | :doc:`lj/charmm/coul/msm (o) <pair_charmm>` | :doc:`lj/charmmfsw/coul/charmmfsh <pair_charmm>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`lj/charmmfsw/coul/long <pair_charmm>` | :doc:`lj/class2 (gko) <pair_class2>` | :doc:`lj/class2/coul/cut (ko) <pair_class2>` | :doc:`lj/class2/coul/cut/soft <pair_fep_soft>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`lj/class2/coul/long (gko) <pair_class2>` | :doc:`lj/class2/coul/long/soft <pair_fep_soft>` | :doc:`lj/class2/soft <pair_fep_soft>` | :doc:`lj/cubic (go) <pair_lj_cubic>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`lj/cut (gikot) <pair_lj>` | :doc:`lj/cut/coul/cut (gko) <pair_lj>` | :doc:`lj/cut/coul/cut/soft (o) <pair_fep_soft>` | :doc:`lj/cut/coul/debye (gko) <pair_lj>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`lj/cut/coul/dsf (gko) <pair_lj>` | :doc:`lj/cut/coul/long (gikot) <pair_lj>` | :doc:`lj/cut/coul/long/cs <pair_cs>` | :doc:`lj/cut/coul/long/soft (o) <pair_fep_soft>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`lj/cut/coul/msm (go) <pair_lj>` | :doc:`lj/cut/coul/wolf (o) <pair_lj>` | :doc:`lj/cut/dipole/cut (go) <pair_dipole>` | :doc:`lj/cut/dipole/long (g) <pair_dipole>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`lj/cut/dipole/sf (go) <pair_dipole>` | :doc:`lj/cut/soft (o) <pair_fep_soft>` | :doc:`lj/cut/thole/long (o) <pair_thole>` | :doc:`lj/cut/tip4p/cut (o) <pair_lj>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`lj/cut/tip4p/long (ot) <pair_lj>` | :doc:`lj/cut/tip4p/long/soft (o) <pair_fep_soft>` | :doc:`lj/expand (gko) <pair_lj_expand>` | :doc:`lj/expand/coul/long (g) <pair_lj_expand>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`lj/gromacs (gko) <pair_gromacs>` | :doc:`lj/gromacs/coul/gromacs (ko) <pair_gromacs>` | :doc:`lj/long/coul/long (iot) <pair_lj_long>` | :doc:`lj/long/dipole/long <pair_dipole>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`lj/long/tip4p/long (o) <pair_lj_long>` | :doc:`lj/mdf <pair_mdf>` | :doc:`lj/sdk (gko) <pair_sdk>` | :doc:`lj/sdk/coul/long (go) <pair_sdk>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`lj/sdk/coul/msm (o) <pair_sdk>` | :doc:`lj/sf/dipole/sf (go) <pair_dipole>` | :doc:`lj/smooth (o) <pair_lj_smooth>` | :doc:`lj/smooth/linear (o) <pair_lj_smooth_linear>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`lj/switch3/coulgauss/long <pair_lj_switch3_coulgauss>` | :doc:`lj96/cut (go) <pair_lj96>` | :doc:`local/density <pair_local_density>` | :doc:`lubricate (o) <pair_lubricate>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`lubricate/poly (o) <pair_lubricate>` | :doc:`lubricateU <pair_lubricateU>` | :doc:`lubricateU/poly <pair_lubricateU>` | :doc:`mdpd <pair_meso>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`mdpd/rhosum <pair_meso>` | :doc:`meam/c <pair_meamc>` | :doc:`meam/spline (o) <pair_meam_spline>` | :doc:`meam/sw/spline <pair_meam_sw_spline>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`mgpt <pair_mgpt>` | :doc:`mie/cut (g) <pair_mie>` | :doc:`momb <pair_momb>` | :doc:`morse (gkot) <pair_morse>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`morse/smooth/linear (o) <pair_morse>` | :doc:`morse/soft <pair_fep_soft>` | :doc:`multi/lucy <pair_multi_lucy>` | :doc:`multi/lucy/rx (k) <pair_multi_lucy_rx>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`nb3b/harmonic <pair_nb3b_harmonic>` | :doc:`nm/cut (o) <pair_nm>` | :doc:`nm/cut/coul/cut (o) <pair_nm>` | :doc:`nm/cut/coul/long (o) <pair_nm>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`oxdna/coaxstk <pair_oxdna>` | :doc:`oxdna/excv <pair_oxdna>` | :doc:`oxdna/hbond <pair_oxdna>` | :doc:`oxdna/stk <pair_oxdna>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`oxdna/xstk <pair_oxdna>` | :doc:`oxdna2/coaxstk <pair_oxdna2>` | :doc:`oxdna2/dh <pair_oxdna2>` | :doc:`oxdna2/excv <pair_oxdna2>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`oxdna2/hbond <pair_oxdna2>` | :doc:`oxdna2/stk <pair_oxdna2>` | :doc:`oxdna2/xstk <pair_oxdna2>` | :doc:`peri/eps <pair_peri>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`peri/lps (o) <pair_peri>` | :doc:`peri/pmb (o) <pair_peri>` | :doc:`peri/ves <pair_peri>` | :doc:`polymorphic <pair_polymorphic>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`python <pair_python>` | :doc:`quip <pair_quip>` | :doc:`reax/c (ko) <pair_reaxc>` | :doc:`rebo (io) <pair_airebo>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`resquared (go) <pair_resquared>` | :doc:`sdpd/taitwater/isothermal <pair_sdpd_taitwater_isothermal>` | :doc:`smd/hertz <pair_smd_hertz>` | :doc:`smd/tlsph <pair_smd_tlsph>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`smd/tri\_surface <pair_smd_triangulated_surface>` | :doc:`smd/ulsph <pair_smd_ulsph>` | :doc:`smtbq <pair_smtbq>` | :doc:`snap (k) <pair_snap>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`snap (k) <pair_snap>` | :doc:`soft (go) <pair_soft>` | :doc:`sph/heatconduction <pair_sph_heatconduction>` | :doc:`sph/idealgas <pair_sph_idealgas>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`sph/lj <pair_sph_lj>` | :doc:`sph/rhosum <pair_sph_rhosum>` | :doc:`sph/taitwater <pair_sph_taitwater>` | :doc:`sph/taitwater/morris <pair_sph_taitwater_morris>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`spin/dipole/cut <pair_spin_dipole>` | :doc:`spin/dipole/long <pair_spin_dipole>` | :doc:`spin/dmi <pair_spin_dmi>` | :doc:`spin/exchange <pair_spin_exchange>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`spin/magelec <pair_spin_magelec>` | :doc:`spin/neel <pair_spin_neel>` | :doc:`srp <pair_srp>` | :doc:`sw (giko) <pair_sw>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`table (gko) <pair_table>` | :doc:`table/rx (k) <pair_table_rx>` | :doc:`tdpd <pair_meso>` | :doc:`tersoff (giko) <pair_tersoff>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`tersoff/mod (gko) <pair_tersoff_mod>` | :doc:`tersoff/mod/c (o) <pair_tersoff_mod>` | :doc:`tersoff/table (o) <pair_tersoff>` | :doc:`tersoff/zbl (gko) <pair_tersoff_zbl>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`thole <pair_thole>` | :doc:`tip4p/cut (o) <pair_coul>` | :doc:`tip4p/long (o) <pair_coul>` | :doc:`tip4p/long/soft (o) <pair_fep_soft>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`tri/lj <pair_tri_lj>` | :doc:`ufm (got) <pair_ufm>` | :doc:`vashishta (gko) <pair_vashishta>` | :doc:`vashishta/table (o) <pair_vashishta>` |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
| :doc:`yukawa (gko) <pair_yukawa>` | :doc:`yukawa/colloid (go) <pair_yukawa_colloid>` | :doc:`zbl (gko) <pair_zbl>` | |
+--------------------------------------------------------------+-------------------------------------------------------------------+-----------------------------------------------------+-------------------------------------------------------------+
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

99
doc/src/Commands_parse.txt → doc/src/Commands_parse.rst
View File

@ -1,13 +1,5 @@
"Higher level section"_Commands.html - "LAMMPS WWW Site"_lws - "LAMMPS
Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Commands_all.html)
:line
Parsing rules for input scripts :h3
Parsing rules for input scripts
===============================
Each non-blank line in the input script is treated as a command.
LAMMPS commands are case sensitive. Command names are lower-case, as
@ -30,6 +22,10 @@ comment after a trailing "&" character will prevent the command from
continuing on the next line. Also note that for multi-line commands a
single leading "#" will comment out the entire command.
.. code-block:: LAMMPS
# this is a comment
(3) The line is searched repeatedly for $ characters, which indicate
variables that are replaced with a text string. See an exception in
(6).
@ -37,11 +33,11 @@ variables that are replaced with a text string. See an exception in
If the $ is followed by curly brackets, then the variable name is the
text inside the curly brackets. If no curly brackets follow the $,
then the variable name is the single character immediately following
the $. Thus $\{myTemp\} and $x refer to variable names "myTemp" and
the $. Thus ${myTemp} and $x refer to variable names "myTemp" and
"x".
How the variable is converted to a text string depends on what style
of variable it is; see the "variable"_variable.html doc page for details.
of variable it is; see the :doc:`variable <variable>` doc page for details.
It can be a variable that stores multiple text strings, and return one
of them. The returned text string can be multiple "words" (space
separated) which will then be interpreted as multiple arguments in the
@ -50,17 +46,23 @@ will be evaluated and its numeric result returned as a string.
As a special case, if the $ is followed by parenthesis, then the text
inside the parenthesis is treated as an "immediate" variable and
evaluated as an "equal-style variable"_variable.html. This is a way
evaluated as an :doc:`equal-style variable <variable>`. This is a way
to use numeric formulas in an input script without having to assign
them to variable names. For example, these 3 input script lines:
variable X equal (xlo+xhi)/2+sqrt(v_area)
region 1 block $X 2 INF INF EDGE EDGE
variable X delete :pre
.. code-block:: LAMMPS
variable X equal (xlo+xhi)/2+sqrt(v_area)
region 1 block $X 2 INF INF EDGE EDGE
variable X delete
can be replaced by
region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE :pre
.. code-block:: LAMMPS
region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE
so that you do not have to define (or discard) a temporary variable X.
@ -73,21 +75,27 @@ specified a high-precision "%.20g" is used as the default.
This can be useful for formatting print output to a desired precision:
print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom" :pre
.. code-block:: LAMMPS
print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom"
Note that neither the curly-bracket or immediate form of variables can
contain nested $ characters for other variables to substitute for.
Thus you cannot do this:
variable a equal 2
variable b2 equal 4
print "B2 = $\{b$a\}" :pre
.. code-block:: LAMMPS
variable a equal 2
variable b2 equal 4
print "B2 = ${b$a}"
Nor can you specify this $($x-1.0) for an immediate variable, but
you could use $(v_x-1.0), since the latter is valid syntax for an
"equal-style variable"_variable.html.
you could use $(v\_x-1.0), since the latter is valid syntax for an
:doc:`equal-style variable <variable>`.
See the "variable"_variable.html command for more details of how
See the :doc:`variable <variable>` command for more details of how
strings are assigned to variables and evaluated, and how they can be
used in input script commands.
@ -108,29 +116,38 @@ multiple lines of an argument to retain their line breaks, the text
can be enclosed in triple quotes, in which case "&" characters are not
needed. For example:
print "Volume = $v"
print 'Volume = $v'
if "$\{steps\} > 1000" then quit
variable a string "red green blue &
purple orange cyan"
print """
System volume = $v
System temperature = $t
""" :pre
.. code-block:: LAMMPS
print "Volume = $v"
print 'Volume = $v'
if "${steps} > 1000" then quit
variable a string "red green blue &
purple orange cyan"
print """
System volume = $v
System temperature = $t
"""
In each case, the single, double, or triple quotes are removed when
the single argument they enclose is stored internally.
See the "dump modify format"_dump_modify.html, "print"_print.html,
"if"_if.html, and "python"_python.html commands for examples.
See the :doc:`dump modify format <dump_modify>`, :doc:`print <print>`,
:doc:`if <if>`, and :doc:`python <python>` commands for examples.
A "#" or "$" character that is between quotes will not be treated as a
comment indicator in (2) or substituted for as a variable in (3).
NOTE: If the argument is itself a command that requires a quoted
argument (e.g. using a "print"_print.html command as part of an
"if"_if.html or "run every"_run.html command), then single, double, or
triple quotes can be nested in the usual manner. See the doc pages
for those commands for examples. Only one of level of nesting is
allowed, but that should be sufficient for most use cases.
.. note::
If the argument is itself a command that requires a quoted
argument (e.g. using a :doc:`print <print>` command as part of an
:doc:`if <if>` or :doc:`run every <run>` command), then single, double, or
triple quotes can be nested in the usual manner. See the doc pages
for those commands for examples. Only one of level of nesting is
allowed, but that should be sufficient for most use cases.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

67
doc/src/Commands_removed.rst Normal file
View File

@ -0,0 +1,67 @@
Removed commands and packages
=============================
This page lists LAMMPS commands and packages that have been removed from
the distribution and provides suggestions for alternatives or replacements.
LAMMPS has special dummy styles implemented, that will stop LAMMPS and
print a suitable error message in most cases, when a style/command is used
that has been removed.
Fix ave/spatial and fix ave/spatial/sphere
------------------------------------------
The fixes ave/spatial and ave/spatial/sphere have been removed from LAMMPS
since they were superseded by the more general and extensible "chunk
infrastructure". Here the system is partitioned in one of many possible
ways through the :doc:`compute chunk/atom <compute_chunk_atom>` command
and then averaging is done using :doc:`fix ave/chunk <fix_ave_chunk>`.
Please refer to the :doc:`chunk HOWTO <Howto_chunk>` section for an overview.
MEAM package
------------
The MEAM package has been removed since it was superseded by the
:ref:`USER-MEAMC package <PKG-USER-MEAMC>`. The code in
the USER-MEAMC package is a translation of the Fortran code of MEAM into C++,
which removes several restrictions (e.g. there can be multiple instances
in hybrid pair styles) and allows for some optimizations leading
to better performance. The new pair style :doc:`meam/c <pair_meamc>` has
the exact same syntax as the old "meam" pair style and thus pair style
:doc:`meam <pair_meamc>` is an alias to the new style and backward
compatibility of old inputs is preserved.
REAX package
------------
The REAX package has been removed since it was superseded by the
:ref:`USER-REAXC package <PKG-USER-REAXC>`. The USER-REAXC
package has been tested to yield equivalent results to the REAX package,
offers better performance, supports OpenMP multi-threading via USER-OMP,
and GPU and threading parallelization through KOKKOS. The new pair styles
are not syntax compatible with the removed reax pair style, so input
files will have to be adapted.
USER-CUDA package
-----------------
The USER-CUDA package had been removed, since it had been unmaintained
for a long time and had known bugs and problems. Significant parts of
the design were transferred to the
:ref:`KOKKOS package <PKG-KOKKOS>`, which has similar
performance characteristics on Nvidia GPUs. Both, the KOKKOS
and the :ref:`GPU package <PKG-GPU>` are maintained
and allow running LAMMPS with GPU acceleration.
restart2data tool
-----------------
The functionality of the restart2data tool has been folded into the
LAMMPS executable directly instead of having a separate tool. A
combination of the commands :doc:`read\_restart <read_restart>` and
:doc:`write\_data <write_data>` can be used to the same effect. For added
convenience this conversion can also be triggered by :doc:`command line flags <Run_options>`
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

91
doc/src/Commands_structure.rst Normal file
View File

@ -0,0 +1,91 @@
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 <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 <units>`,
:doc:`dimension <dimension>`, :doc:`newton <newton>`,
:doc:`processors <processors>`, :doc:`boundary <boundary>`,
:doc:`atom\_style <atom_style>`, :doc:`atom\_modify <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 <pair_style>`, :doc:`bond\_style <bond_style>`,
:doc:`angle\_style <angle_style>`, :doc:`dihedral\_style <dihedral_style>`,
:doc:`improper\_style <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 <read_data>` or
:doc:`read\_restart <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 <lattice>`,
:doc:`region <region>`, :doc:`create\_box <create_box>`,
:doc:`create\_atoms <create_atoms>`. The entire set of atoms can be
duplicated to make a larger simulation using the
:doc:`replicate <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 <pair_coeff>`,
:doc:`bond\_coeff <bond_coeff>`, :doc:`angle\_coeff <angle_coeff>`,
:doc:`dihedral\_coeff <dihedral_coeff>`,
:doc:`improper\_coeff <improper_coeff>`,
:doc:`kspace\_style <kspace_style>`, :doc:`dielectric <dielectric>`,
:doc:`special\_bonds <special_bonds>`.
Various simulation parameters are set by these commands:
:doc:`neighbor <neighbor>`, :doc:`neigh\_modify <neigh_modify>`,
:doc:`group <group>`, :doc:`timestep <timestep>`,
:doc:`reset\_timestep <reset_timestep>`, :doc:`run\_style <run_style>`,
:doc:`min\_style <min_style>`, :doc:`min\_modify <min_modify>`.
Fixes impose a variety of boundary conditions, time integration, and
diagnostic options. The :doc:`fix <fix>` command comes in many flavors.
Various computations can be specified for execution during a
simulation using the :doc:`compute <compute>`,
:doc:`compute\_modify <compute_modify>`, and :doc:`variable <variable>`
commands.
Output options are set by the :doc:`thermo <thermo>`, :doc:`dump <dump>`,
and :doc:`restart <restart>` commands.
(4) Run a simulation
A molecular dynamics simulation is run using the :doc:`run <run>`
command. Energy minimization (molecular statics) is performed using
the :doc:`minimize <minimize>` command. A parallel tempering
(replica-exchange) simulation can be run using the
:doc:`temper <temper>` command.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

22
doc/src/Errors.rst Normal file
View File

@ -0,0 +1,22 @@
Errors
******
These doc pages describe the errors you can encounter when using
LAMMPS. The common problems include conceptual issues. The messages
and warnings doc pages give complete lists of all the messages the
code may generate (except those generated by USER packages), with
additional details for many of them.
.. toctree::
:maxdepth: 1
Errors_common
Errors_bugs
Errors_messages
Errors_warnings
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

32
doc/src/Errors_bugs.rst Normal file
View File

@ -0,0 +1,32 @@
Reporting bugs
==============
If you are confident that you have found a bug in LAMMPS, follow these
steps.
Check the `New features and bug fixes <http://lammps.sandia.gov/bug.html>`_ section of the `LAMMPS WWW site <lws_>`_ to see if the bug has already been reported or fixed or the
`Unfixed bug <http://lammps.sandia.gov/unbug.html>`_ to see if a fix is
pending.
Check the `mailing list <http://lammps.sandia.gov/mail.html>`_ to see if
it has been discussed before.
If not, send an email to the mailing list describing the problem with
any ideas you have as to what is causing it or where in the code the
problem might be. The developers will ask for more info if needed,
such as an input script or data files.
The most useful thing you can do to help us fix the bug is to isolate
the problem. Run it on the smallest number of atoms and fewest number
of processors and with the simplest input script that reproduces the
bug and try to identify what command or combination of commands is
causing the problem.
.. note::
this page needs to have GitHub issues info added
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

128
doc/src/Errors_common.rst Normal file
View File

@ -0,0 +1,128 @@
Common problems
===============
If two LAMMPS runs do not produce the exact same answer on different
machines or different numbers of processors, this is typically not a
bug. In theory you should get identical answers on any number of
processors and on any machine. In practice, numerical round-off can
cause slight differences and eventual divergence of molecular dynamics
phase space trajectories within a few 100s or few 1000s of timesteps.
However, the statistical properties of the two runs (e.g. average
energy or temperature) should still be the same.
If the :doc:`velocity <velocity>` command is used to set initial atom
velocities, a particular atom can be assigned a different velocity
when the problem is run on a different number of processors or on
different machines. If this happens, the phase space trajectories of
the two simulations will rapidly diverge. See the discussion of the
*loop* option in the :doc:`velocity <velocity>` command for details and
options that avoid this issue.
Similarly, the :doc:`create\_atoms <create_atoms>` command generates a
lattice of atoms. For the same physical system, the ordering and
numbering of atoms by atom ID may be different depending on the number
of processors.
Some commands use random number generators which may be setup to
produce different random number streams on each processor and hence
will produce different effects when run on different numbers of
processors. A commonly-used example is the :doc:`fix langevin <fix_langevin>` command for thermostatting.
A LAMMPS simulation typically has two stages, setup and run. Most
LAMMPS errors are detected at setup time; others like a bond
stretching too far may not occur until the middle of a run.
LAMMPS tries to flag errors and print informative error messages so
you can fix the problem. For most errors it will also print the last
input script command that it was processing. Of course, LAMMPS cannot
figure out your physics or numerical mistakes, like choosing too big a
timestep, specifying erroneous force field coefficients, or putting 2
atoms on top of each other! If you run into errors that LAMMPS
doesn't catch that you think it should flag, please send an email to
the `developers <http://lammps.sandia.gov/authors.html>`_.
If you get an error message about an invalid command in your input
script, you can determine what command is causing the problem by
looking in the log.lammps file or using the :doc:`echo command <echo>`
to see it on the screen. If you get an error like "Invalid ...
style", with ... being fix, compute, pair, etc, it means that you
mistyped the style name or that the command is part of an optional
package which was not compiled into your executable. The list of
available styles in your executable can be listed by using :doc:`the -h command-line swith <Run_options>`. The installation and
compilation of optional packages is explained on the :doc:`Build packages <Build_package>` doc page.
For a given command, LAMMPS expects certain arguments in a specified
order. If you mess this up, LAMMPS will often flag the error, but it
may also simply read a bogus argument and assign a value that is
valid, but not what you wanted. E.g. trying to read the string "abc"
as an integer value of 0. Careful reading of the associated doc page
for the command should allow you to fix these problems. In most cases,
where LAMMPS expects to read a number, either integer or floating point,
it performs a stringent test on whether the provided input actually
is an integer or floating-point number, respectively, and reject the
input with an error message (for instance, when an integer is required,
but a floating-point number 1.0 is provided):
.. parsed-literal::
ERROR: Expected integer parameter instead of '1.0' in input script or data file
Some commands allow for using variable references in place of numeric
constants so that the value can be evaluated and may change over the
course of a run. This is typically done with the syntax *v\_name* for a
parameter, where name is the name of the variable. On the other hand,
immediate variable expansion with the syntax $\ *name* is performed while
reading the input and before parsing commands,
.. note::
Using a variable reference (i.e. *v\_name*) is only allowed if
the documentation of the corresponding command explicitly says it is.
Otherwise, you will receive an error message of this kind:
.. parsed-literal::
ERROR: Expected floating point parameter instead of 'v_name' in input script or data file
Generally, LAMMPS will print a message to the screen and logfile and
exit gracefully when it encounters a fatal error. Sometimes it will
print a WARNING to the screen and logfile and continue on; you can
decide if the WARNING is important or not. A WARNING message that is
generated in the middle of a run is only printed to the screen, not to
the logfile, to avoid cluttering up thermodynamic output. If LAMMPS
crashes or hangs without spitting out an error message first then it
could be a bug (see :doc:`this section <Errors_bugs>`) or one of the following
cases:
LAMMPS runs in the available memory a processor allows to be
allocated. Most reasonable MD runs are compute limited, not memory
limited, so this shouldn't be a bottleneck on most platforms. Almost
all large memory allocations in the code are done via C-style malloc's
which will generate an error message if you run out of memory.
Smaller chunks of memory are allocated via C++ "new" statements. If
you are unlucky you could run out of memory just when one of these
small requests is made, in which case the code will crash or hang (in
parallel), since LAMMPS doesn't trap on those errors.
Illegal arithmetic can cause LAMMPS to run slow or crash. This is
typically due to invalid physics and numerics that your simulation is
computing. If you see wild thermodynamic values or NaN values in your
LAMMPS output, something is wrong with your simulation. If you
suspect this is happening, it is a good idea to print out
thermodynamic info frequently (e.g. every timestep) via the
:doc:`thermo <thermo>` so you can monitor what is happening.
Visualizing the atom movement is also a good idea to insure your model
is behaving as you expect.
In parallel, one way LAMMPS can hang is due to how different MPI
implementations handle buffering of messages. If the code hangs
without an error message, it may be that you need to specify an MPI
setting or two (usually via an environment variable) to enable
buffering or boost the sizes of messages that can be buffered.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

8408
doc/src/Errors_messages.rst Normal file
View File

File diff suppressed because it is too large Load Diff

796
doc/src/Errors_warnings.rst Normal file
View File

@ -0,0 +1,796 @@
Warning messages
================
This is an alphabetic list of the WARNING messages LAMMPS prints out
and the reason why. If the explanation here is not sufficient, the
documentation for the offending command may help. Warning messages
also list the source file and line number where the warning was
generated. For example, a message like this:
.. parsed-literal::
WARNING: Bond atom missing in box size check (domain.cpp:187)
means that line #187 in the file src/domain.cpp generated the error.
Looking in the source code may help you figure out what went wrong.
Note that warning messages from :doc:`user-contributed packages <Packages_user>` are not listed here. If such a warning
occurs and is not self-explanatory, you'll need to look in the source
code or contact the author of the package.
Doc page with :doc:`ERROR messages <Errors_messages>`
----------
*Adjusting Coulombic cutoff for MSM, new cutoff = %g*
The adjust/cutoff command is turned on and the Coulombic cutoff has been
adjusted to match the user-specified accuracy.
*Angle atoms missing at step %ld*
One or more of 3 atoms needed to compute a particular angle are
missing on this processor. Typically this is because the pairwise
cutoff is set too short or the angle has blown apart and an atom is
too far away.
*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.
*Bond atom missing in box size check*
The 2nd atoms needed to compute a particular bond is missing on this
processor. Typically this is because the pairwise cutoff is set too
short or the bond has blown apart and an atom is too far away.
*Bond atom missing in image check*
The 2nd atom in a particular bond is missing on this processor.
Typically this is because the pairwise cutoff is set too short or the
bond has blown apart and an atom is too far away.
*Bond atoms missing at step %ld*
The 2nd atom needed to compute a particular bond is missing on this
processor. Typically this is because the pairwise cutoff is set too
short or the bond has blown apart and an atom is too far away.
*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.
"Extent" in this context means the maximum end-to-end length of the
bond/angle/dihedral. LAMMPS computes this by taking the maximum bond
length, multiplying by the number of bonds in the interaction (e.g. 3
for a dihedral) and adding a small amount of stretch.
*Bond/react: Atom affected by reaction too close to template edge*
This means an atom which changes type or connectivity during the
reaction is too close to an 'edge' atom defined in the superimpose
file. This could cause incorrect assignment of bonds, angle, etc.
Generally, this means you must include more atoms in your templates,
such that there are at least two atoms between each atom involved in
the reaction and an edge atom.
*Both groups in compute group/group have a net charge; the Kspace boundary correction to energy will be non-zero*
Self-explanatory.
*Calling write\_dump before a full system init.*
The write\_dump command is used before the system has been fully
initialized as part of a 'run' or 'minimize' command. Not all dump
styles and features are fully supported at this point and thus the
command may fail or produce incomplete or incorrect output. Insert
a "run 0" command, if a full system init is required.
*Cannot count rigid body degrees-of-freedom before bodies are fully initialized*
This means the temperature associated with the rigid bodies may be
incorrect on this timestep.
*Cannot count rigid body degrees-of-freedom before bodies are initialized*
This means the temperature associated with the rigid bodies may be
incorrect on this timestep.
*Cannot include log terms without 1/r terms; setting flagHI to 1*
Self-explanatory.
*Cannot include log terms without 1/r terms; setting flagHI to 1.*
Self-explanatory.
*Charges are set, but coulombic solver is not used*
Self-explanatory.
*Charges did not converge at step %ld: %lg*
Self-explanatory.
*Communication cutoff is 0.0. No ghost atoms will be generated. Atoms may get lost*
The communication cutoff defaults to the maximum of what is inferred from
pair and bond styles (will be zero, if none are defined) and what is specified
via :doc:`comm\_modify cutoff <comm_modify>` (defaults to 0.0). If this results
to 0.0, no ghost atoms will be generated and LAMMPS may lose atoms or use
incorrect periodic images of atoms in interaction lists. To avoid, either use
:doc:`pair style zero <pair_zero>` with a suitable cutoff or use :doc:`comm\_modify cutoff <comm_modify>`.
*Communication cutoff is too small for SNAP micro load balancing, increased to %lf*
Self-explanatory.
*Compute cna/atom cutoff may be too large to find ghost atom neighbors*
The neighbor cutoff used may not encompass enough ghost atoms
to perform this operation correctly.
*Computing temperature of portions of rigid bodies*
The group defined by the temperature compute does not encompass all
the atoms in one or more rigid bodies, so the change in
degrees-of-freedom for the atoms in those partial rigid bodies will
not be accounted for.
*Create\_bonds max distance > minimum neighbor cutoff*
This means atom pairs for some atom types may not be in the neighbor
list and thus no bond can be created between them.
*Delete\_atoms cutoff > minimum neighbor cutoff*
This means atom pairs for some atom types may not be in the neighbor
list and thus an atom in that pair cannot be deleted.
*Dihedral atoms missing at step %ld*
One or more of 4 atoms needed to compute a particular dihedral are
missing on this processor. Typically this is because the pairwise
cutoff is set too short or the dihedral has blown apart and an atom is
too far away.
*Dihedral problem*
Conformation of the 4 listed dihedral atoms is extreme; you may want
to check your simulation geometry.
*Dihedral problem: %d %ld %d %d %d %d*
Conformation of the 4 listed dihedral atoms is extreme; you may want
to check your simulation geometry.
*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.
*Energy due to X extra global DOFs will be included in minimizer energies*
When using fixes like box/relax, the potential energy used by the minimizer
is augmented by an additional energy provided by the fix. Thus the printed
converged energy may be different from the total potential energy.
*Estimated error in splitting of dispersion coeffs is %g*
Error is greater than 0.0001 percent.
*Ewald/disp Newton solver failed, using old method to estimate g\_ewald*
Self-explanatory. Choosing a different cutoff value may help.
*FENE bond too long*
A FENE bond has stretched dangerously far. It's interaction strength
will be truncated to attempt to prevent the bond from blowing up.
*FENE bond too long: %ld %d %d %g*
A FENE bond has stretched dangerously far. It's interaction strength
will be truncated to attempt to prevent the bond from blowing up.
*FENE bond too long: %ld %g*
A FENE bond has stretched dangerously far. It's interaction strength
will be truncated to attempt to prevent the bond from blowing up.
*Fix SRD walls overlap but fix srd overlap not set*
You likely want to set this in your input script.
*Fix bond/swap will ignore defined angles*
See the doc page for fix bond/swap for more info on this
restriction.
*Fix deposit near setting < possible overlap separation %g*
This test is performed for finite size particles with a diameter, not
for point particles. The near setting is smaller than the particle
diameter which can lead to overlaps.
*Fix evaporate may delete atom with non-zero molecule ID*
This is probably an error, since you should not delete only one atom
of a molecule.
*Fix gcmc using full\_energy option*
Fix gcmc has automatically turned on the full\_energy option since it
is required for systems like the one specified by the user. User input
included one or more of the following: kspace, triclinic, a hybrid
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.
*Fix qeq CG convergence failed (%g) after %d iterations at %ld step*
Self-explanatory.
*Fix qeq has non-zero lower Taper radius cutoff*
Absolute value must be <= 0.01.
*Fix qeq has very low Taper radius cutoff*
Value should typically be >= 5.0.
*Fix qeq/dynamic tolerance may be too small for damped dynamics*
Self-explanatory.
*Fix qeq/fire tolerance may be too small for damped fires*
Self-explanatory.
*Fix rattle should come after all other integration fixes*
This fix is designed to work after all other integration fixes change
atom positions. Thus it should be the last integration fix specified.
If not, it will not satisfy the desired constraints as well as it
otherwise would.
*Fix recenter should come after all other integration fixes*
Other fixes may change the position of the center-of-mass, so
fix recenter should come last.
*Fix srd SRD moves may trigger frequent reneighboring*
This is because the SRD particles may move long distances.
*Fix srd grid size > 1/4 of big particle diameter*
This may cause accuracy problems.
*Fix srd particle moved outside valid domain*
This may indicate a problem with your simulation parameters.
*Fix srd particles may move > big particle diameter*
This may cause accuracy problems.
*Fix srd viscosity < 0.0 due to low SRD density*
This may cause accuracy problems.
*Fixes cannot send data in Kokkos communication, switching to classic communication*
This is current restriction with Kokkos.
*For better accuracy use 'pair\_modify table 0'*
The user-specified force accuracy cannot be achieved unless the table
feature is disabled by using 'pair\_modify table 0'.
*Geometric mixing assumed for 1/r\^6 coefficients*
Self-explanatory.
*Group for fix\_modify temp != fix group*
The fix\_modify command is specifying a temperature computation that
computes a temperature on a different group of atoms than the fix
itself operates on. This is probably not what you want to do.
*H matrix size has been exceeded: m\_fill=%d H.m=%d\n*
This is the size of the matrix.
*Ignoring unknown or incorrect info command flag*
Self-explanatory. An unknown argument was given to the info command.
Compare your input with the documentation.
*Improper atoms missing at step %ld*
One or more of 4 atoms needed to compute a particular improper are
missing on this processor. Typically this is because the pairwise
cutoff is set too short or the improper has blown apart and an atom is
too far away.
*Improper problem: %d %ld %d %d %d %d*
Conformation of the 4 listed improper atoms is extreme; you may want
to check your simulation geometry.
*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
unwrapped using the image flags, the two atoms are far apart.
Specifically they are further apart than half a periodic box length.
Or they are more than a box length apart in a non-periodic dimension.
This is usually due to the initial data file not having correct image
flags for the 2 atoms in a bond that straddles a periodic boundary.
They should be different by 1 in that case. This is a warning because
inconsistent image flags will not cause problems for dynamics or most
LAMMPS simulations. However they can cause problems when such atoms
are used with the fix rigid or replicate commands. Note that if you
have an infinite periodic crystal with bonds then it is impossible to
have fully consistent image flags, since some bonds will cross
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.
*KIM Model does not provide 'forces'; Forces will be zero*
Self-explanatory.
*KIM Model does not provide 'particleEnergy'; energy per atom will be zero*
Self-explanatory.
*KIM Model does not provide 'particleVirial'; virial per atom will be zero*
Self-explanatory.
*Kspace\_modify slab param < 2.0 may cause unphysical behavior*
The kspace\_modify slab parameter should be larger to insure periodic
grids padded with empty space do not overlap.
*Less insertions than requested*
The fix pour command was unsuccessful at finding open space
for as many particles as it tried to insert.
*Library error in lammps\_gather\_atoms*
This library function cannot be used if atom IDs are not defined
or are not consecutively numbered.
*Library error in lammps\_scatter\_atoms*
This library function cannot be used if atom IDs are not defined or
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.
*Lost atoms via displace\_atoms: original %ld current %ld*
The command options you have used caused atoms to be lost.
*Lost atoms: original %ld current %ld*
Lost atoms are checked for each time thermo output is done. See the
thermo\_modify lost command for options. Lost atoms usually indicate
bad dynamics, e.g. atoms have been blown far out of the simulation
box, or moved further than one processor's sub-domain away before
reneighboring.
*MSM mesh too small, increasing to 2 points in each direction*
Self-explanatory.
*Mismatch between velocity and compute groups*
The temperature computation used by the velocity command will not be
on the same group of atoms that velocities are being set for.
*Mixing forced for lj coefficients*
Self-explanatory.
*Molecule attributes do not match system attributes*
An attribute is specified (e.g. diameter, charge) that is
not defined for the specified atom style.
*Molecule has bond topology but no special bond settings*
This means the bonded atoms will not be excluded in pair-wise
interactions.
*Molecule template for create\_atoms has multiple molecules*
The create\_atoms command will only create molecules of a single type,
i.e. the first molecule in the template.
*Molecule template for fix gcmc has multiple molecules*
The fix gcmc command will only create molecules of a single type,
i.e. the first molecule in the template.
*Molecule template for fix shake has multiple molecules*
The fix shake command will only recognize molecules of a single
type, i.e. the first molecule in the template.
*More than one compute centro/atom*
It is not efficient to use compute centro/atom more than once.
*More than one compute cluster/atom*
It is not efficient to use compute cluster/atom more than once.
*More than one compute cna/atom defined*
It is not efficient to use compute cna/atom more than once.
*More than one compute contact/atom*
It is not efficient to use compute contact/atom more than once.
*More than one compute coord/atom*
It is not efficient to use compute coord/atom more than once.
*More than one compute damage/atom*
It is not efficient to use compute ke/atom more than once.
*More than one compute dilatation/atom*
Self-explanatory.
*More than one compute erotate/sphere/atom*
It is not efficient to use compute erorate/sphere/atom more than once.
*More than one compute hexorder/atom*
It is not efficient to use compute hexorder/atom more than once.
*More than one compute ke/atom*
It is not efficient to use compute ke/atom more than once.
*More than one compute orientorder/atom*
It is not efficient to use compute orientorder/atom more than once.
*More than one compute plasticity/atom*
Self-explanatory.
*More than one compute sna/atom*
Self-explanatory.
*More than one compute snad/atom*
Self-explanatory.
*More than one compute snav/atom*
Self-explanatory.
*More than one fix poems*
It is not efficient to use fix poems more than once.
*More than one fix rigid*
It is not efficient to use fix rigid more than once.
*Neighbor exclusions used with KSpace solver may give inconsistent Coulombic energies*
This is because excluding specific pair interactions also excludes
them from long-range interactions which may not be the desired effect.
The special\_bonds command handles this consistently by insuring
excluded (or weighted) 1-2, 1-3, 1-4 interactions are treated
consistently by both the short-range pair style and the long-range
solver. This is not done for exclusions of charged atom pairs via the
neigh\_modify exclude command.
*New thermo\_style command, previous thermo\_modify settings will be lost*
If a thermo\_style command is used after a thermo\_modify command, the
settings changed by the thermo\_modify command will be reset to their
default values. This is because the thermo\_modify command acts on
the currently defined thermo style, and a thermo\_style command creates
a new style.
*No Kspace calculation with verlet/split*
The 2nd partition performs a kspace calculation so the kspace\_style
command must be used.
*No automatic unit conversion to XTC file format conventions possible for units lj*
This means no scaling will be performed.
*No fixes defined, atoms won't move*
If you are not using a fix like nve, nvt, npt then atom velocities and
coordinates will not be updated during timestepping.
*No joints between rigid bodies, use fix rigid instead*
The bodies defined by fix poems are not connected by joints. POEMS
will integrate the body motion, but it would be more efficient to use
fix rigid.
*Not using real units with pair reax*
This is most likely an error, unless you have created your own ReaxFF
parameter file in a different set of units.
*Number of MSM mesh points changed to be a multiple of 2*
MSM requires that the number of grid points in each direction be a multiple
of two and the number of grid points in one or more directions have been
adjusted to meet this requirement.
*OMP\_NUM\_THREADS environment is not set.*
This environment variable must be set appropriately to use the
USER-OMP package.
*One or more atoms are time integrated more than once*
This is probably an error since you typically do not want to
advance the positions or velocities of an atom more than once
per timestep.
*One or more chunks do not contain all atoms in molecule*
This may not be what you intended.
*One or more dynamic groups may not be updated at correct point in timestep*
If there are other fixes that act immediately after the initial stage
of time integration within a timestep (i.e. after atoms move), then
the command that sets up the dynamic group should appear after those
fixes. This will insure that dynamic group assignments are made
after all atoms have moved.
*One or more respa levels compute no forces*
This is computationally inefficient.
*Pair COMB charge %.10f with force %.10f hit max barrier*
Something is possibly wrong with your model.
*Pair COMB charge %.10f with force %.10f hit min barrier*
Something is possibly wrong with your model.
*Pair brownian needs newton pair on for momentum conservation*
Self-explanatory.
*Pair dpd needs newton pair on for momentum conservation*
Self-explanatory.
*Pair dsmc: num\_of\_collisions > number\_of\_A*
Collision model in DSMC is breaking down.
*Pair dsmc: num\_of\_collisions > number\_of\_B*
Collision model in DSMC is breaking down.
*Pair style in data file differs from currently defined pair style*
Self-explanatory.
*Pair style restartinfo set but has no restart support*
This pair style has a bug, where it does not support reading and
writing information to a restart file, but does not set the member
variable "restartinfo" to 0 as required in that case.
*Particle deposition was unsuccessful*
The fix deposit command was not able to insert as many atoms as
needed. The requested volume fraction may be too high, or other atoms
may be in the insertion region.
*Proc sub-domain size < neighbor skin, could lead to lost atoms*
The decomposition of the physical domain (likely due to load
balancing) has led to a processor's sub-domain being smaller than the
neighbor skin in one or more dimensions. Since reneighboring is
triggered by atoms moving the skin distance, this may lead to lost
atoms, if an atom moves all the way across a neighboring processor's
sub-domain before reneighboring is triggered.
*Reducing PPPM order b/c stencil extends beyond nearest neighbor processor*
This may lead to a larger grid than desired. See the kspace\_modify overlap
command to prevent changing of the PPPM order.
*Reducing PPPMDisp Coulomb order b/c stencil extends beyond neighbor processor*
This may lead to a larger grid than desired. See the kspace\_modify overlap
command to prevent changing of the PPPM order.
*Reducing PPPMDisp dispersion order b/c stencil extends beyond neighbor processor*
This may lead to a larger grid than desired. See the kspace\_modify overlap
command to prevent changing of the PPPM order.
*Replacing a fix, but new group != old group*
The ID and style of a fix match for a fix you are changing with a fix
command, but the new group you are specifying does not match the old
group.
*Replicating in a non-periodic dimension*
The parameters for a replicate command will cause a non-periodic
dimension to be replicated; this may cause unwanted behavior.
*Resetting reneighboring criteria during PRD*
A PRD simulation requires that neigh\_modify settings be delay = 0,
every = 1, check = yes. Since these settings were not in place,
LAMMPS changed them and will restore them to their original values
after the PRD simulation.
*Resetting reneighboring criteria during TAD*
A TAD simulation requires that neigh\_modify settings be delay = 0,
every = 1, check = yes. Since these settings were not in place,
LAMMPS changed them and will restore them to their original values
after the PRD simulation.
*Resetting reneighboring criteria during minimization*
Minimization requires that neigh\_modify settings be delay = 0, every =
1, check = yes. Since these settings were not in place, LAMMPS
changed them and will restore them to their original values after the
minimization.
*Restart file used different # of processors*
The restart file was written out by a LAMMPS simulation running on a
different number of processors. Due to round-off, the trajectories of
your restarted simulation may diverge a little more quickly than if
you ran on the same # of processors.
*Restart file used different 3d processor grid*
The restart file was written out by a LAMMPS simulation running on a
different 3d grid of processors. Due to round-off, the trajectories
of your restarted simulation may diverge a little more quickly than if
you ran on the same # of processors.
*Restart file used different boundary settings, using restart file values*
Your input script cannot change these restart file settings.
*Restart file used different newton bond setting, using restart file value*
The restart file value will override the setting in the input script.
*Restart file used different newton pair setting, using input script value*
The input script value will override the setting in the restart file.
*Restrain problem: %d %ld %d %d %d %d*
Conformation of the 4 listed dihedral atoms is extreme; you may want
to check your simulation geometry.
*Running PRD with only one replica*
This is allowed, but you will get no parallel speed-up.
*SRD bin shifting turned on due to small lamda*
This is done to try to preserve accuracy.
*SRD bin size for fix srd differs from user request*
Fix SRD had to adjust the bin size to fit the simulation box. See the
cubic keyword if you want this message to be an error vs warning.
*SRD bins for fix srd are not cubic enough*
The bin shape is not within tolerance of cubic. See the cubic
keyword if you want this message to be an error vs warning.
*SRD particle %d started inside big particle %d on step %ld bounce %d*
See the inside keyword if you want this message to be an error vs
warning.
*SRD particle %d started inside wall %d on step %ld bounce %d*
See the inside keyword if you want this message to be an error vs
warning.
*Shake determinant < 0.0*
The determinant of the quadratic equation being solved for a single
cluster specified by the fix shake command is numerically suspect. LAMMPS
will set it to 0.0 and continue.
*Shell command '%s' failed with error '%s'*
Self-explanatory.
*Shell command returned with non-zero status*
This may indicate the shell command did not operate as expected.
*Should not allow rigid bodies to bounce off reflecting walls*
LAMMPS allows this, but their dynamics are not computed correctly.
*Should not use fix nve/limit with fix shake or fix rattle*
This will lead to invalid constraint forces in the SHAKE/RATTLE
computation.
*Simulations might be very slow because of large number of structure factors*
Self-explanatory.
*Slab correction not needed for MSM*
Slab correction is intended to be used with Ewald or PPPM and is not needed by MSM.
*System is not charge neutral, net charge = %g*
The total charge on all atoms on the system is not 0.0.
For some KSpace solvers this is only a warning.
*Table inner cutoff >= outer cutoff*
You specified an inner cutoff for a Coulombic table that is longer
than the global cutoff. Probably not what you wanted.
*Temperature for MSST is not for group all*
User-assigned temperature to MSST fix does not compute temperature for
all atoms. Since MSST computes a global pressure, the kinetic energy
contribution from the temperature is assumed to also be for all atoms.
Thus the pressure used by MSST could be inaccurate.
*Temperature for NPT is not for group all*
User-assigned temperature to NPT fix does not compute temperature for
all atoms. Since NPT computes a global pressure, the kinetic energy
contribution from the temperature is assumed to also be for all atoms.
Thus the pressure used by NPT could be inaccurate.
*Temperature for fix modify is not for group all*
The temperature compute is being used with a pressure calculation
which does operate on group all, so this may be inconsistent.
*Temperature for thermo pressure is not for group all*
User-assigned temperature to thermo via the thermo\_modify command does
not compute temperature for all atoms. Since thermo computes a global
pressure, the kinetic energy contribution from the temperature is
assumed to also be for all atoms. Thus the pressure printed by thermo
could be inaccurate.
*The fix ave/spatial command has been replaced by the more flexible fix ave/chunk and compute chunk/atom commands -- fix ave/spatial will be removed in the summer of 2015*
Self-explanatory.
*The minimizer does not re-orient dipoles when using fix efield*
This means that only the atom coordinates will be minimized,
not the orientation of the dipoles.
*Too many common neighbors in CNA %d times*
More than the maximum # of neighbors was found multiple times. This
was unexpected.
*Too many inner timesteps in fix ttm*
Self-explanatory.
*Too many neighbors in CNA for %d atoms*
More than the maximum # of neighbors was found multiple times. This
was unexpected.
*Triclinic box skew is large*
The displacement in a skewed direction is normally required to be less
than half the box length in that dimension. E.g. the xy tilt must be
between -half and +half of the x box length. You have relaxed the
constraint using the box tilt command, but the warning means that a
LAMMPS simulation may be inefficient as a result.
*Use special bonds = 0,1,1 with bond style fene*
Most FENE models need this setting for the special\_bonds command.
*Use special bonds = 0,1,1 with bond style fene/expand*
Most FENE models need this setting for the special\_bonds command.
*Using a many-body potential with bonds/angles/dihedrals and special\_bond exclusions*
This is likely not what you want to do. The exclusion settings will
eliminate neighbors in the neighbor list, which the many-body potential
needs to calculated its terms correctly.
*Using compute temp/deform with inconsistent fix deform remap option*
Fix nvt/sllod assumes deforming atoms have a velocity profile provided
by "remap v" or "remap none" as a fix deform option.
*Using compute temp/deform with no fix deform defined*
This is probably an error, since it makes little sense to use
compute temp/deform in this case.
*Using fix srd with box deformation but no SRD thermostat*
The deformation will heat the SRD particles so this can
be dangerous.
*Using kspace solver on system with no charge*
Self-explanatory.
*Using largest cut-off for lj/long/dipole/long long long*
Self-explanatory.
*Using largest cutoff for buck/long/coul/long*
Self-explanatory.
*Using largest cutoff for lj/long/coul/long*
Self-explanatory.
*Using largest cutoff for pair\_style lj/long/tip4p/long*
Self-explanatory.
*Using package gpu without any pair style defined*
Self-explanatory.
*Using pair potential shift with pair\_modify compute no*
The shift effects will thus not be computed.
*Using pair tail corrections with nonperiodic system*
This is probably a bogus thing to do, since tail corrections are
computed by integrating the density of a periodic system out to
infinity.
*Using pair tail corrections with pair\_modify compute no*
The tail corrections will thus not be computed.
*pair style reax is now deprecated and will soon be retired. Users should switch to pair\_style reax/c*
Self-explanatory.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

235
doc/src/Examples.rst Normal file
View File

@ -0,0 +1,235 @@
Example scripts
===============
The LAMMPS distribution includes an examples sub-directory with many
sample problems. Many are 2d models that run quickly and are
straightforward to visualize, requiring at most a couple of minutes to
run on a desktop machine. Each problem has an input script (in.\*) and
produces a log file (log.\*) when it runs. Some use a data file
(data.\*) of initial coordinates as additional input. A few sample log
file run on different machines and different numbers of processors are
included in the directories to compare your answers to. E.g. a log
file like log.date.crack.foo.P means the "crack" example was run on P
processors of machine "foo" on that date (i.e. with that version of
LAMMPS).
Many of the input files have commented-out lines for creating dump
files and image files.
If you uncomment the :doc:`dump <dump>` command in the input script, a
text dump file will be produced, which can be animated by various
`visualization programs <http://lammps.sandia.gov/viz.html>`_.
If you uncomment the :doc:`dump image <dump>` command in the input
script, and assuming you have built LAMMPS with a JPG library, JPG
snapshot images will be produced when the simulation runs. They can
be quickly post-processed into a movie using commands described on the
:doc:`dump image <dump_image>` doc page.
Animations of many of the examples can be viewed on the Movies section
of the `LAMMPS web site <lws_>`_.
There are two kinds of sub-directories in the examples dir. Lowercase
dirs contain one or a few simple, quick-to-run problems. Uppercase
dirs contain up to several complex scripts that illustrate a
particular kind of simulation method or model. Some of these run for
longer times, e.g. to measure a particular quantity.
Lists of both kinds of directories are given below.
----------
Lowercase directories
---------------------
+-------------+------------------------------------------------------------------+
| accelerate | run with various acceleration options (OpenMP, GPU, Phi) |
+-------------+------------------------------------------------------------------+
| airebo | polyethylene with AIREBO potential |
+-------------+------------------------------------------------------------------+
| atm | Axilrod-Teller-Muto potential example |
+-------------+------------------------------------------------------------------+
| balance | dynamic load balancing, 2d system |
+-------------+------------------------------------------------------------------+
| body | body particles, 2d system |
+-------------+------------------------------------------------------------------+
| cmap | CMAP 5-body contributions to CHARMM force field |
+-------------+------------------------------------------------------------------+
| colloid | big colloid particles in a small particle solvent, 2d system |
+-------------+------------------------------------------------------------------+
| comb | models using the COMB potential |
+-------------+------------------------------------------------------------------+
| controller | use of fix controller as a thermostat |
+-------------+------------------------------------------------------------------+
| coreshell | core/shell model using CORESHELL package |
+-------------+------------------------------------------------------------------+
| crack | crack propagation in a 2d solid |
+-------------+------------------------------------------------------------------+
| deposit | deposit atoms and molecules on a surface |
+-------------+------------------------------------------------------------------+
| dipole | point dipolar particles, 2d system |
+-------------+------------------------------------------------------------------+
| dreiding | methanol via Dreiding FF |
+-------------+------------------------------------------------------------------+
| eim | NaCl using the EIM potential |
+-------------+------------------------------------------------------------------+
| ellipse | ellipsoidal particles in spherical solvent, 2d system |
+-------------+------------------------------------------------------------------+
| flow | Couette and Poiseuille flow in a 2d channel |
+-------------+------------------------------------------------------------------+
| friction | frictional contact of spherical asperities between 2d surfaces |
+-------------+------------------------------------------------------------------+
| gcmc | Grand Canonical Monte Carlo (GCMC) via the fix gcmc command |
+-------------+------------------------------------------------------------------+
| granregion | use of fix wall/region/gran as boundary on granular particles |
+-------------+------------------------------------------------------------------+
| hugoniostat | Hugoniostat shock dynamics |
+-------------+------------------------------------------------------------------+
| hyper | global and local hyperdynamics of diffusion on Pt surface |
+-------------+------------------------------------------------------------------+
| indent | spherical indenter into a 2d solid |
+-------------+------------------------------------------------------------------+
| kim | use of potentials from the `OpenKIM Repository <openkim_>`_ |
+-------------+------------------------------------------------------------------+
| latte | examples for using fix latte for DFTB via the LATTE library |
+-------------+------------------------------------------------------------------+
| meam | MEAM test for SiC and shear (same as shear examples) |
+-------------+------------------------------------------------------------------+
| melt | rapid melt of 3d LJ system |
+-------------+------------------------------------------------------------------+
| message | demos for LAMMPS client/server coupling with the MESSAGE package |
+-------------+------------------------------------------------------------------+
| micelle | self-assembly of small lipid-like molecules into 2d bilayers |
+-------------+------------------------------------------------------------------+
| min | energy minimization of 2d LJ melt |
+-------------+------------------------------------------------------------------+
| mscg | parameterize a multi-scale coarse-graining (MSCG) model |
+-------------+------------------------------------------------------------------+
| msst | MSST shock dynamics |
+-------------+------------------------------------------------------------------+
| nb3b | use of non-bonded 3-body harmonic pair style |
+-------------+------------------------------------------------------------------+
| neb | nudged elastic band (NEB) calculation for barrier finding |
+-------------+------------------------------------------------------------------+
| nemd | non-equilibrium MD of 2d sheared system |
+-------------+------------------------------------------------------------------+
| obstacle | flow around two voids in a 2d channel |
+-------------+------------------------------------------------------------------+
| peptide | dynamics of a small solvated peptide chain (5-mer) |
+-------------+------------------------------------------------------------------+
| peri | Peridynamic model of cylinder impacted by indenter |
+-------------+------------------------------------------------------------------+
| pour | pouring of granular particles into a 3d box, then chute flow |
+-------------+------------------------------------------------------------------+
| prd | parallel replica dynamics of vacancy diffusion in bulk Si |
+-------------+------------------------------------------------------------------+
| python | using embedded Python in a LAMMPS input script |
+-------------+------------------------------------------------------------------+
| qeq | use of the QEQ package for charge equilibration |
+-------------+------------------------------------------------------------------+
| rdf-adf | computing radial and angle distribution functions for water |
+-------------+------------------------------------------------------------------+
| reax | RDX and TATB models using the ReaxFF |
+-------------+------------------------------------------------------------------+
| rigid | rigid bodies modeled as independent or coupled |
+-------------+------------------------------------------------------------------+
| shear | sideways shear applied to 2d solid, with and without a void |
+-------------+------------------------------------------------------------------+
| snap | NVE dynamics for BCC tantalum crystal using SNAP potential |
+-------------+------------------------------------------------------------------+
| srd | stochastic rotation dynamics (SRD) particles as solvent |
+-------------+------------------------------------------------------------------+
| streitz | use of Streitz/Mintmire potential with charge equilibration |
+-------------+------------------------------------------------------------------+
| tad | temperature-accelerated dynamics of vacancy diffusion in bulk Si |
+-------------+------------------------------------------------------------------+
| threebody | regression test input for a variety of manybody potentials |
+-------------+------------------------------------------------------------------+
| vashishta | use of the Vashishta potential |
+-------------+------------------------------------------------------------------+
| voronoi | Voronoi tesselation via compute voronoi/atom command |
+-------------+------------------------------------------------------------------+
Here is how you can run and visualize one of the sample problems:
.. parsed-literal::
cd indent
cp ../../src/lmp_linux . # copy LAMMPS executable to this dir
lmp_linux -in in.indent # run the problem
Running the simulation produces the files *dump.indent* and
*log.lammps*\ . You can visualize the dump file of snapshots with a
variety of 3rd-party tools highlighted on the
`Visualization <http://lammps.sandia.gov/viz.html>`_ page of the LAMMPS
web site.
If you uncomment the :doc:`dump image <dump_image>` line(s) in the input
script a series of JPG images will be produced by the run (assuming
you built LAMMPS with JPG support; see the
:doc:`Build\_settings <Build_settings>` doc page for details). These can
be viewed individually or turned into a movie or animated by tools
like ImageMagick or QuickTime or various Windows-based tools. See the
:doc:`dump image <dump_image>` doc page for more details. E.g. this
Imagemagick command would create a GIF file suitable for viewing in a
browser.
.. parsed-literal::
% convert -loop 1 \*.jpg foo.gif
----------
Uppercase directories
---------------------
+------------+--------------------------------------------------------------------------------------------------+
| ASPHERE | various aspherical particle models, using ellipsoids, rigid bodies, line/triangle particles, etc |
+------------+--------------------------------------------------------------------------------------------------+
| COUPLE | examples of how to use LAMMPS as a library |
+------------+--------------------------------------------------------------------------------------------------+
| DIFFUSE | compute diffusion coefficients via several methods |
+------------+--------------------------------------------------------------------------------------------------+
| ELASTIC | compute elastic constants at zero temperature |
+------------+--------------------------------------------------------------------------------------------------+
| ELASTIC\_T | compute elastic constants at finite temperature |
+------------+--------------------------------------------------------------------------------------------------+
| HEAT | compute thermal conductivity for LJ and water via fix ehex |
+------------+--------------------------------------------------------------------------------------------------+
| KAPPA | compute thermal conductivity via several methods |
+------------+--------------------------------------------------------------------------------------------------+
| MC | using LAMMPS in a Monte Carlo mode to relax the energy of a system |
+------------+--------------------------------------------------------------------------------------------------+
| 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 |
+------------+--------------------------------------------------------------------------------------------------+
Nearly all of these directories have README files which give more
details on how to understand and use their contents.
The USER directory has a large number of sub-directories which
correspond by name to a USER package. They contain scripts that
illustrate how to use the command(s) provided in that package. Many
of the sub-directories have their own README files which give further
instructions. See the :doc:`Packages\_details <Packages_details>` doc
page for more info on specific USER packages.
.. _openkim: https://openkim.org
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

106
doc/src/Howto.rst Normal file
View File

@ -0,0 +1,106 @@
Howto discussions
*****************
These doc pages describe how to perform various tasks with LAMMPS,
both for users and developers. The
`glossary <http://lammps.sandia.gov>`_ website page also lists MD
terminology with links to corresponding LAMMPS manual pages. The
example input scripts included in the examples dir of the LAMMPS
distribution and highlighted on the :doc:`Examples <Examples>` doc page
also show how to setup and run various kinds of simulations.
Tutorials howto
===============
.. toctree::
:name: tutorials
:maxdepth: 1
Howto_github
Howto_pylammps
Howto_bash
General howto
=============
.. toctree::
:name: general_howto
:maxdepth: 1
Howto_restart
Howto_viz
Howto_multiple
Howto_replica
Howto_library
Howto_couple
Howto_client_server
Settings howto
==============
.. toctree::
:name: settings
:maxdepth: 1
Howto_2d
Howto_triclinic
Howto_thermostat
Howto_barostat
Howto_walls
Howto_nemd
Howto_dispersion
Analysis howto
==============
.. toctree::
:name: analysis
:maxdepth: 1
Howto_output
Howto_chunk
Howto_temperature
Howto_elastic
Howto_kappa
Howto_viscosity
Howto_diffusion
Force fields howto
==================
.. toctree::
:name: force
:maxdepth: 1
Howto_bioFF
Howto_tip3p
Howto_tip4p
Howto_spc
Packages howto
==============
.. toctree::
:name: packages
:maxdepth: 1
Howto_spherical
Howto_granular
Howto_body
Howto_polarizable
Howto_coreshell
Howto_drude
Howto_drude2
Howto_manifold
Howto_spins
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

48
doc/src/Howto_2d.rst Normal file
View File

@ -0,0 +1,48 @@
2d simulations
==============
Use the :doc:`dimension <dimension>` command to specify a 2d simulation.
Make the simulation box periodic in z via the :doc:`boundary <boundary>`
command. This is the default.
If using the :doc:`create box <create_box>` command to define a
simulation box, set the z dimensions narrow, but finite, so that the
create\_atoms command will tile the 3d simulation box with a single z
plane of atoms - e.g.
.. parsed-literal::
:doc:`create box <create_box>` 1 -10 10 -10 10 -0.25 0.25
If using the :doc:`read data <read_data>` command to read in a file of
atom coordinates, set the "zlo zhi" values to be finite but narrow,
similar to the create\_box command settings just described. For each
atom in the file, assign a z coordinate so it falls inside the
z-boundaries of the box - e.g. 0.0.
Use the :doc:`fix enforce2d <fix_enforce2d>` command as the last
defined fix to insure that the z-components of velocities and forces
are zeroed out every timestep. The reason to make it the last fix is
so that any forces induced by other fixes will be zeroed out.
Many of the example input scripts included in the LAMMPS distribution
are for 2d models.
.. note::
Some models in LAMMPS treat particles as finite-size spheres, as
opposed to point particles. See the :doc:`atom\_style sphere <atom_style>` and :doc:`fix nve/sphere <fix_nve_sphere>`
commands for details. By default, for 2d simulations, such particles
will still be modeled as 3d spheres, not 2d discs (circles), meaning
their moment of inertia will be that of a sphere. If you wish to
model them as 2d discs, see the :doc:`set density/disc <set>` command
and the *disc* option for the :doc:`fix nve/sphere <fix_nve_sphere>`,
:doc:`fix nvt/sphere <fix_nvt_sphere>`, :doc:`fix nph/sphere <fix_nph_sphere>`, :doc:`fix npt/sphere <fix_npt_sphere>`
commands.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

68
doc/src/Howto_barostat.rst Normal file
View File

@ -0,0 +1,68 @@
Barostats
=========
Barostatting means controlling the pressure in an MD simulation.
:doc:`Thermostatting <Howto_thermostat>` means controlling the
temperature of the particles. Since the pressure includes a kinetic
component due to particle velocities, both these operations require
calculation of the temperature. Typically a target temperature (T)
and/or pressure (P) is specified by the user, and the thermostat or
barostat attempts to equilibrate the system to the requested T and/or
P.
Barostatting in LAMMPS is performed by :doc:`fixes <fix>`. Two
barostatting methods are currently available: Nose-Hoover (npt and
nph) and Berendsen:
* :doc:`fix npt <fix_nh>`
* :doc:`fix npt/sphere <fix_npt_sphere>`
* :doc:`fix npt/asphere <fix_npt_asphere>`
* :doc:`fix nph <fix_nh>`
* :doc:`fix press/berendsen <fix_press_berendsen>`
The :doc:`fix npt <fix_nh>` commands include a Nose-Hoover thermostat
and barostat. :doc:`Fix nph <fix_nh>` is just a Nose/Hoover barostat;
it does no thermostatting. Both :doc:`fix nph <fix_nh>` and :doc:`fix press/berendsen <fix_press_berendsen>` can be used in conjunction
with any of the thermostatting fixes.
As with the :doc:`thermostats <Howto_thermostat>`, :doc:`fix npt <fix_nh>`
and :doc:`fix nph <fix_nh>` only use translational motion of the
particles in computing T and P and performing thermo/barostatting.
:doc:`Fix npt/sphere <fix_npt_sphere>` and :doc:`fix npt/asphere <fix_npt_asphere>` thermo/barostat using not only
translation velocities but also rotational velocities for spherical
and aspherical particles.
All of the barostatting fixes use the :doc:`compute pressure <compute_pressure>` compute to calculate a current
pressure. By default, this compute is created with a simple :doc:`compute temp <compute_temp>` (see the last argument of the :doc:`compute pressure <compute_pressure>` command), which is used to calculated
the kinetic component of the pressure. The barostatting fixes can
also use temperature computes that remove bias for the purpose of
computing the kinetic component which contributes to the current
pressure. See the doc pages for the individual fixes and for the
:doc:`fix\_modify <fix_modify>` command for instructions on how to assign
a temperature or pressure compute to a barostatting fix.
.. note::
As with the thermostats, the Nose/Hoover methods (:doc:`fix npt <fix_nh>` and :doc:`fix nph <fix_nh>`) perform time integration.
:doc:`Fix press/berendsen <fix_press_berendsen>` does NOT, so it should
be used with one of the constant NVE fixes or with one of the NVT
fixes.
Thermodynamic output, which can be setup via the
:doc:`thermo\_style <thermo_style>` command, often includes pressure
values. As explained on the doc page for the
:doc:`thermo\_style <thermo_style>` command, the default pressure is
setup by the thermo command itself. It is NOT the pressure associated
with any barostatting fix you have defined or with any compute you
have defined that calculates a pressure. The doc pages for the
barostatting fixes explain the ID of the pressure compute they create.
Thus if you want to view these pressures, you need to specify them
explicitly via the :doc:`thermo\_style custom <thermo_style>` command.
Or you can use the :doc:`thermo\_modify <thermo_modify>` command to
re-define what pressure compute is used for default thermodynamic
output.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

291
doc/src/Howto_bash.rst Normal file
View File

@ -0,0 +1,291 @@
Using LAMMPS with Bash on Windows
=================================
**written by Richard Berger**
----------
Starting with Windows 10 you can install Linux tools directly in Windows. This
allows you to compile LAMMPS following the same procedure as on a real Ubuntu
Linux installation. Software can be easily installed using the package manager
via apt-get and all files are accessible in both the Windows Explorer and your
Linux shell (bash). This avoids switching to a different operating system or
installing a virtual machine. Everything runs on Windows.
Installing Bash on Windows
--------------------------
Prerequisites
^^^^^^^^^^^^^
* Windows 10 (64bit only)
* Latest updates installed
Enable developer mode
^^^^^^^^^^^^^^^^^^^^^
You enable this feature by first opening Windows Settings and enabling
Developer mode. Go to the Windows settings and search for "developer". This
will allow you to install software which comes from outside of the Windows
Store. You might be prompted to reboot your compute. Please do so.
.. image:: JPG/bow_tutorial_01_small.png
:target: JPG/bow_tutorial_01.png
.. image:: JPG/bow_tutorial_02_small.png
:target: JPG/bow_tutorial_02.png
.. image:: JPG/bow_tutorial_03_small.png
:target: JPG/bow_tutorial_03.png
Install Windows Subsystem for Linux
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Next you must ensure that the Window Subsystem for Linux is installed. Again,
search for "enable windows features" in the Settings dialog. This opens a
dialog with a list of features you can install. Add a checkmark to Windows
Subsystem for Linux (Beta) and press OK.
.. image:: JPG/bow_tutorial_04_small.png
:target: JPG/bow_tutorial_04.png
.. image:: JPG/bow_tutorial_05.png
:target: JPG/bow_tutorial_05.png
Install Bash for Windows
^^^^^^^^^^^^^^^^^^^^^^^^
After installation completes, type "bash" in the Windows Start menu search.
Select the first found option. This will launch a command-line window which
will prompt you about installing Ubuntu on Windows. Confirm with "y" and press
enter. This will then download Ubuntu for Windows.
.. image:: JPG/bow_tutorial_06.png
.. image:: JPG/bow_tutorial_07.png
During installation, you will be asked for a new password. This will be used
for installing new software and running commands with sudo.
.. image:: JPG/bow_tutorial_08.png
Type exit to close the command-line window.
Go to the Start menu and type "bash" again. This time you will see a "Bash on
Ubuntu on Windows" Icon. Start this program.
.. image:: JPG/bow_tutorial_09.png
Congratulations, you have installed **Bash on Ubuntu on Windows**\ .
.. image:: JPG/bow_tutorial_10.png
----------
Compiling LAMMPS in Bash on Windows
-----------------------------------
The installation of LAMMPS in this environment is identical to working inside
of a real Ubuntu Linux installation. At the time writing, it uses Ubuntu 16.04.
Installing prerequisite packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
First upgrade all existing packages using
.. parsed-literal::
sudo apt update
sudo apt upgrade -y
Next install the following packages, which include compilers and libraries
needed for various LAMMPS features:
.. parsed-literal::
sudo apt install -y build-essential ccache gfortran openmpi-bin libopenmpi-dev libfftw3-dev libjpeg-dev libpng12-dev python-dev python-virtualenv libblas-dev liblapack-dev libhdf5-serial-dev hdf5-tools
Files in Ubuntu on Windows
^^^^^^^^^^^^^^^^^^^^^^^^^^
When you launch "Bash on Ubuntu on Windows" you will start out in your Linux
user home directory /home/\ **username**\ . You can access your Windows user directory
using the /mnt/c/Users/\ **username** folder.
Download LAMMPS
^^^^^^^^^^^^^^^
Obtain a copy of the LAMMPS code and go into it using "cd"
Option 1: Downloading LAMMPS tarball using wget
"""""""""""""""""""""""""""""""""""""""""""""""
.. parsed-literal::
wget http://lammps.sandia.gov/tars/lammps-stable.tar.gz
tar xvzf lammps-stable.tar.gz
cd lammps-31Mar17
Option 2: Obtaining LAMMPS code from GitHub
"""""""""""""""""""""""""""""""""""""""""""
.. parsed-literal::
git clone https://github.com/lammps/lammps.git
cd lammps
Compiling LAMMPS
^^^^^^^^^^^^^^^^
At this point you can compile LAMMPS like on Ubuntu Linux.
Compiling serial version
""""""""""""""""""""""""
.. parsed-literal::
cd src/
make -j 4 serial
This will create an executable called lmp\_serial in the src/ directory
Compiling MPI version
"""""""""""""""""""""
.. parsed-literal::
cd src/
make -j 4 mpi
This will create an executable called lmp\_mpi in the src/ directory
----------
Finally, please note the absolute path of your src folder. You can get this using
.. parsed-literal::
pwd
or
.. parsed-literal::
echo $PWD
To run any examples you need the location of the executable. For now, let us
save this location in a temporary variable
.. parsed-literal::
LAMMPS_DIR=$PWD
----------
Running an example script
^^^^^^^^^^^^^^^^^^^^^^^^^
Once compiled you can execute some of the LAMMPS examples. Switch into the
examples/melt folder
.. parsed-literal::
cd ../examples/melt
The full path of the serial executable is $LAMMPS\_DIR/lmp\_serial, while the mpi
version is $LAMMPS\_DIR/lmp\_mpi. You can run the melt example with either
version as follows:
.. parsed-literal::
$LAMMPS_DIR/lmp_serial -in in.melt
or
.. parsed-literal::
mpirun -np 4 $LAMMPS_DIR/lmp_mpi -in in.melt
Note the use of our variable $LAMMPS\_DIR, which expands into the full path of
the LAMMPS src folder we saved earlier.
Adding your executable directory to your PATH
"""""""""""""""""""""""""""""""""""""""""""""
You can avoid having to type the full path of your LAMMPS binary by adding its
parent folder to the PATH environment variable as follows:
.. parsed-literal::
export PATH=$LAMMPS_DIR:$PATH
Input scripts can then be run like this:
.. parsed-literal::
lmp_serial -in in.melt
or
.. parsed-literal::
mpirun -np 4 lmp_mpi -in in.melt
However, this PATH variable will not persist if you close your bash window.
To persist this setting edit the $HOME/.bashrc file using your favorite editor
and add this line
.. parsed-literal::
export PATH=/full/path/to/your/lammps/src:$PATH
**Example:**
For an executable lmp\_serial with a full path
.. parsed-literal::
/home/richard/lammps/src/lmp_serial
the PATH variable should be
.. parsed-literal::
export PATH=/home/richard/lammps/src:$PATH
.. note::
This should give you a jump start when trying to run LAMMPS on Windows.
To become effective in this environment I encourage you to look into Linux
tutorials explaining Bash and Basic Unix commands (e.g., `Linux Journey <https://linuxjourney.com>`_)
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

151
doc/src/Howto_bioFF.rst Normal file
View File

@ -0,0 +1,151 @@
CHARMM, AMBER, COMPASS, and DREIDING force fields
=================================================
A force field has 2 parts: the formulas that define it and the
coefficients used for a particular system. Here we only discuss
formulas implemented in LAMMPS that correspond to formulas commonly
used in the CHARMM, AMBER, COMPASS, and DREIDING force fields. Setting
coefficients is done either from special sections in an input data file
via the :doc:`read\_data <read_data>` command or in the input script with
commands like :doc:`pair\_coeff <pair_coeff>` or
:doc:`bond\_coeff <bond_coeff>` and so on. See the :doc:`Tools <Tools>` doc
page for additional tools that can use CHARMM, AMBER, or Materials
Studio generated files to assign force field coefficients and convert
their output into LAMMPS input.
See :ref:`(MacKerell) <howto-MacKerell>` for a description of the CHARMM force
field. See :ref:`(Cornell) <howto-Cornell>` for a description of the AMBER
force field. See :ref:`(Sun) <howto-Sun>` for a description of the COMPASS
force field.
.. _charmm: http://www.scripps.edu/brooks
.. _amber: http://amber.scripps.edu
The interaction styles listed below compute force field formulas that
are consistent with common options in CHARMM or AMBER. See each
command's documentation for the formula it computes.
* :doc:`bond\_style <bond_harmonic>` harmonic
* :doc:`angle\_style <angle_charmm>` charmm
* :doc:`dihedral\_style <dihedral_charmm>` charmmfsh
* :doc:`dihedral\_style <dihedral_charmm>` charmm
* :doc:`pair\_style <pair_charmm>` lj/charmmfsw/coul/charmmfsh
* :doc:`pair\_style <pair_charmm>` lj/charmmfsw/coul/long
* :doc:`pair\_style <pair_charmm>` lj/charmm/coul/charmm
* :doc:`pair\_style <pair_charmm>` lj/charmm/coul/charmm/implicit
* :doc:`pair\_style <pair_charmm>` lj/charmm/coul/long
* :doc:`special\_bonds <special_bonds>` charmm
* :doc:`special\_bonds <special_bonds>` amber
.. note::
For CHARMM, newer *charmmfsw* or *charmmfsh* styles were released
in March 2017. We recommend they be used instead of the older *charmm*
styles. See discussion of the differences on the :doc:`pair charmm <pair_charmm>` and :doc:`dihedral charmm <dihedral_charmm>` doc
pages.
COMPASS is a general force field for atomistic simulation of common
organic molecules, inorganic small molecules, and polymers which was
developed using ab initio and empirical parameterization techniques.
See the :doc:`Tools <Tools>` doc page for the msi2lmp tool for creating
LAMMPS template input and data files from BIOVIA's Materials Studio
files. Please note that the msi2lmp tool is very old and largely
unmaintained, so it does not support all features of Materials Studio
provided force field files, especially additions during the last decade.
You should watch the output carefully and compare results, where
possible. See :ref:`(Sun) <howto-Sun>` for a description of the COMPASS force
field.
These interaction styles listed below compute force field formulas that
are consistent with the COMPASS force field. See each command's
documentation for the formula it computes.
* :doc:`bond\_style <bond_class2>` class2
* :doc:`angle\_style <angle_class2>` class2
* :doc:`dihedral\_style <dihedral_class2>` class2
* :doc:`improper\_style <improper_class2>` class2
* :doc:`pair\_style <pair_class2>` lj/class2
* :doc:`pair\_style <pair_class2>` lj/class2/coul/cut
* :doc:`pair\_style <pair_class2>` lj/class2/coul/long
* :doc:`special\_bonds <special_bonds>` lj/coul 0 0 1
DREIDING is a generic force field developed by the `Goddard group <http://www.wag.caltech.edu>`_ at Caltech and is useful for
predicting structures and dynamics of organic, biological and main-group
inorganic molecules. The philosophy in DREIDING is to use general force
constants and geometry parameters based on simple hybridization
considerations, rather than individual force constants and geometric
parameters that depend on the particular combinations of atoms involved
in the bond, angle, or torsion terms. DREIDING has an :doc:`explicit hydrogen bond term <pair_hbond_dreiding>` to describe interactions involving a
hydrogen atom on very electronegative atoms (N, O, F).
See :ref:`(Mayo) <howto-Mayo>` for a description of the DREIDING force field
The interaction styles listed below compute force field formulas that
are consistent with the DREIDING force field. See each command's
documentation for the formula it computes.
* :doc:`bond\_style <bond_harmonic>` harmonic
* :doc:`bond\_style <bond_morse>` morse
* :doc:`angle\_style <angle_harmonic>` harmonic
* :doc:`angle\_style <angle_cosine>` cosine
* :doc:`angle\_style <angle_cosine_periodic>` cosine/periodic
* :doc:`dihedral\_style <dihedral_charmm>` charmm
* :doc:`improper\_style <improper_umbrella>` umbrella
* :doc:`pair\_style <pair_buck>` buck
* :doc:`pair\_style <pair_buck>` buck/coul/cut
* :doc:`pair\_style <pair_buck>` buck/coul/long
* :doc:`pair\_style <pair_lj>` lj/cut
* :doc:`pair\_style <pair_lj>` lj/cut/coul/cut
* :doc:`pair\_style <pair_lj>` lj/cut/coul/long
* :doc:`pair\_style <pair_hbond_dreiding>` hbond/dreiding/lj
* :doc:`pair\_style <pair_hbond_dreiding>` hbond/dreiding/morse
* :doc:`special\_bonds <special_bonds>` dreiding
----------
.. _howto-MacKerell:
**(MacKerell)** MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field,
Fischer, Gao, Guo, Ha, et al, J Phys Chem, 102, 3586 (1998).
.. _howto-Cornell:
**(Cornell)** Cornell, Cieplak, Bayly, Gould, Merz, Ferguson,
Spellmeyer, Fox, Caldwell, Kollman, JACS 117, 5179-5197 (1995).
.. _howto-Sun:
**(Sun)** Sun, J. Phys. Chem. B, 102, 7338-7364 (1998).
.. _howto-Mayo:
**(Mayo)** Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909
(1990).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

519
doc/src/Howto_body.rst Normal file
View File

@ -0,0 +1,519 @@
Body particles
==============
**Overview:**
In LAMMPS, body particles are generalized finite-size particles.
Individual body particles can represent complex entities, such as
surface meshes of discrete points, collections of sub-particles,
deformable objects, etc. Note that other kinds of finite-size
spherical and aspherical particles are also supported by LAMMPS, such
as spheres, ellipsoids, line segments, and triangles, but they are
simpler entities that body particles. See the :doc:`Howto spherical <Howto_spherical>` doc page for a general overview of all
these particle types.
Body particles are used via the :doc:`atom\_style body <atom_style>`
command. It takes a body style as an argument. The current body
styles supported by LAMMPS are as follows. The name in the first
column is used as the *bstyle* argument for the :doc:`atom\_style body <atom_style>` command.
+----------------------+---------------------------------------------------+
| *nparticle* | rigid body with N sub-particles |
+----------------------+---------------------------------------------------+
| *rounded/polygon* | 2d polygons with N vertices |
+----------------------+---------------------------------------------------+
| *rounded/polyhedron* | 3d polyhedra with N vertices, E edges and F faces |
+----------------------+---------------------------------------------------+
The body style determines what attributes are stored for each body and
thus how they can be used to compute pairwise body/body or
bond/non-body (point particle) interactions. More details of each
style are described below.
More styles may be added in the future. See the :doc:`Modify body <Modify_body>` doc page for details on how to add a new body
style to the code.
----------
**When to use body particles:**
You should not use body particles to model a rigid body made of
simpler particles (e.g. point, sphere, ellipsoid, line segment,
triangular particles), if the interaction between pairs of rigid
bodies is just the summation of pairwise interactions between the
simpler particles. LAMMPS already supports this kind of model via the
:doc:`fix rigid <fix_rigid>` command. Any of the numerous pair styles
that compute interactions between simpler particles can be used. The
:doc:`fix rigid <fix_rigid>` command time integrates the motion of the
rigid bodies. All of the standard LAMMPS commands for thermostatting,
adding constraints, performing output, etc will operate as expected on
the simple particles.
By contrast, when body particles are used, LAMMPS treats an entire
body as a single particle for purposes of computing pairwise
interactions, building neighbor lists, migrating particles between
processors, output of particles to a dump file, etc. This means that
interactions between pairs of bodies or between a body and non-body
(point) particle need to be encoded in an appropriate pair style. If
such a pair style were to mimic the :doc:`fix rigid <fix_rigid>` model,
it would need to loop over the entire collection of interactions
between pairs of simple particles within the two bodies, each time a
single body/body interaction was computed.
Thus it only makes sense to use body particles and develop such a pair
style, when particle/particle interactions are more complex than what
the :doc:`fix rigid <fix_rigid>` command can already calculate. For
example, consider particles with one or more of the following
attributes:
* represented by a surface mesh
* represented by a collection of geometric entities (e.g. planes + spheres)
* deformable
* internal stress that induces fragmentation
For these models, the interaction between pairs of particles is likely
to be more complex than the summation of simple pairwise interactions.
An example is contact or frictional forces between particles with
planar surfaces that inter-penetrate. Likewise, the body particle may
store internal state, such as a stress tensor used to compute a
fracture criterion.
These are additional LAMMPS commands that can be used with body
particles of different styles
+------------------------------------------------+-----------------------------------------------------+
| :doc:`fix nve/body <fix_nve_body>` | integrate motion of a body particle in NVE ensemble |
+------------------------------------------------+-----------------------------------------------------+
| :doc:`fix nvt/body <fix_nvt_body>` | ditto for NVT ensemble |
+------------------------------------------------+-----------------------------------------------------+
| :doc:`fix npt/body <fix_npt_body>` | ditto for NPT ensemble |
+------------------------------------------------+-----------------------------------------------------+
| :doc:`fix nph/body <fix_nph_body>` | ditto for NPH ensemble |
+------------------------------------------------+-----------------------------------------------------+
| :doc:`compute body/local <compute_body_local>` | store sub-particle attributes of a body particle |
+------------------------------------------------+-----------------------------------------------------+
| :doc:`compute temp/body <compute_temp_body>` | compute temperature of body particles |
+------------------------------------------------+-----------------------------------------------------+
| :doc:`dump local <dump>` | output sub-particle attributes of a body particle |
+------------------------------------------------+-----------------------------------------------------+
| :doc:`dump image <dump_image>` | output body particle attributes as an image |
+------------------------------------------------+-----------------------------------------------------+
The pair styles defined for use with specific body styles are listed
in the sections below.
----------
**Specifics of body style nparticle:**
The *nparticle* body style represents body particles as a rigid body
with a variable number N of sub-particles. It is provided as a
vanilla, prototypical example of a body particle, although as
mentioned above, the :doc:`fix rigid <fix_rigid>` command already
duplicates its functionality.
The atom\_style body command for this body style takes two additional
arguments:
.. parsed-literal::
atom_style body nparticle Nmin Nmax
Nmin = minimum # of sub-particles in any body in the system
Nmax = maximum # of sub-particles in any body in the system
The Nmin and Nmax arguments are used to bound the size of data
structures used internally by each particle.
When the :doc:`read\_data <read_data>` command reads a data file for this
body style, the following information must be provided for each entry
in the *Bodies* section of the data file:
.. parsed-literal::
atom-ID 1 M
N
ixx iyy izz ixy ixz iyz
x1 y1 z1
...
xN yN zN
where M = 6 + 3\*N, and N is the number of sub-particles in the body
particle.
The integer line has a single value N. The floating point line(s)
list 6 moments of inertia followed by the coordinates of the N
sub-particles (x1 to zN) as 3N values. These values can be listed on
as many lines as you wish; see the :doc:`read\_data <read_data>` command
for more details.
The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the
values consistent with the current orientation of the rigid body
around its center of mass. The values are with respect to the
simulation box XYZ axes, not with respect to the principal axes of the
rigid body itself. LAMMPS performs the latter calculation internally.
The coordinates of each sub-particle are specified as its x,y,z
displacement from the center-of-mass of the body particle. The
center-of-mass position of the particle is specified by the x,y,z
values in the *Atoms* section of the data file, as is the total mass
of the body particle.
The :doc:`pair\_style body/nparticle <pair_body_nparticle>` command can be used
with this body style to compute body/body and body/non-body interactions.
For output purposes via the :doc:`compute body/local <compute_body_local>` and :doc:`dump local <dump>`
commands, this body style produces one datum for each of the N
sub-particles in a body particle. The datum has 3 values:
.. parsed-literal::
1 = x position of sub-particle
2 = y position of sub-particle
3 = z position of sub-particle
These values are the current position of the sub-particle within the
simulation domain, not a displacement from the center-of-mass (COM) of
the body particle itself. These values are calculated using the
current COM and orientation of the body particle.
For images created by the :doc:`dump image <dump_image>` command, if the
*body* keyword is set, then each body particle is drawn as a
collection of spheres, one for each sub-particle. The size of each
sphere is determined by the *bflag1* parameter for the *body* keyword.
The *bflag2* argument is ignored.
----------
**Specifics of body style rounded/polygon:**
The *rounded/polygon* body style represents body particles as a 2d
polygon with a variable number of N vertices. This style can only be
used for 2d models; see the :doc:`boundary <boundary>` command. See the
"pair\_style body/rounded/polygon" doc page for a diagram of two
squares with rounded circles at the vertices. Special cases for N = 1
(circle) and N = 2 (rod with rounded ends) can also be specified.
One use of this body style is for 2d discrete element models, as
described in :ref:`Fraige <body-Fraige>`.
Similar to body style *nparticle*\ , the atom\_style body command for
this body style takes two additional arguments:
.. parsed-literal::
atom_style body rounded/polygon Nmin Nmax
Nmin = minimum # of vertices in any body in the system
Nmax = maximum # of vertices in any body in the system
The Nmin and Nmax arguments are used to bound the size of data
structures used internally by each particle.
When the :doc:`read\_data <read_data>` command reads a data file for this
body style, the following information must be provided for each entry
in the *Bodies* section of the data file:
.. parsed-literal::
atom-ID 1 M
N
ixx iyy izz ixy ixz iyz
x1 y1 z1
...
xN yN zN
i j j k k ...
diameter
where M = 6 + 3\*N + 2\*N + 1, and N is the number of vertices in the
body particle.
The integer line has a single value N. The floating point line(s)
list 6 moments of inertia followed by the coordinates of the N
vertices (x1 to zN) as 3N values (with z = 0.0 for each), followed by
2N vertex indices corresponding to the end points of the N edges,
followed by a single diameter value = the rounded diameter of the
circle that surrounds each vertex. The diameter value can be different
for each body particle. These floating-point values can be listed on
as many lines as you wish; see the :doc:`read\_data <read_data>` command
for more details.
The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the
values consistent with the current orientation of the rigid body
around its center of mass. The values are with respect to the
simulation box XYZ axes, not with respect to the principal axes of the
rigid body itself. LAMMPS performs the latter calculation internally.
The coordinates of each vertex are specified as its x,y,z displacement
from the center-of-mass of the body particle. The center-of-mass
position of the particle is specified by the x,y,z values in the
*Atoms* section of the data file.
For example, the following information would specify a square particle
whose edge length is sqrt(2) and rounded diameter is 1.0. The
orientation of the square is aligned with the xy coordinate axes which
is consistent with the 6 moments of inertia: ixx iyy izz ixy ixz iyz =
1 1 4 0 0 0. Note that only Izz matters in 2D simulations.
.. parsed-literal::
3 1 27
4
1 1 4 0 0 0
-0.7071 -0.7071 0
-0.7071 0.7071 0
0.7071 0.7071 0
0.7071 -0.7071 0
0 1
1 2
2 3
3 0
1.0
A rod in 2D, whose length is 4.0, mass 1.0, rounded at two ends
by circles of diameter 0.5, is specified as follows:
.. parsed-literal::
1 1 13
2
1 1 1.33333 0 0 0
-2 0 0
2 0 0
0.5
A disk, whose diameter is 3.0, mass 1.0, is specified as follows:
.. parsed-literal::
1 1 10
1
1 1 4.5 0 0 0
0 0 0
3.0
The :doc:`pair\_style body/rounded/polygon <pair_body_rounded_polygon>`
command can be used with this body style to compute body/body
interactions. The :doc:`fix wall/body/polygon <fix_wall_body_polygon>`
command can be used with this body style to compute the interaction of
body particles with a wall.
----------
**Specifics of body style rounded/polyhedron:**
The *rounded/polyhedron* body style represents body particles as a 3d
polyhedron with a variable number of N vertices, E edges and F faces.
This style can only be used for 3d models; see the
:doc:`boundary <boundary>` command. See the "pair\_style
body/rounded/polygon" doc page for a diagram of a two 2d squares with
rounded circles at the vertices. A 3d cube with rounded spheres at
the 8 vertices and 12 rounded edges would be similar. Special cases
for N = 1 (sphere) and N = 2 (rod with rounded ends) can also be
specified.
This body style is for 3d discrete element models, as described in
:ref:`Wang <body-Wang>`.
Similar to body style *rounded/polygon*\ , the atom\_style body command
for this body style takes two additional arguments:
.. parsed-literal::
atom_style body rounded/polyhedron Nmin Nmax
Nmin = minimum # of vertices in any body in the system
Nmax = maximum # of vertices in any body in the system
The Nmin and Nmax arguments are used to bound the size of data
structures used internally by each particle.
When the :doc:`read\_data <read_data>` command reads a data file for this
body style, the following information must be provided for each entry
in the *Bodies* section of the data file:
.. parsed-literal::
atom-ID 3 M
N E F
ixx iyy izz ixy ixz iyz
x1 y1 z1
...
xN yN zN
0 1
1 2
2 3
...
0 1 2 -1
0 2 3 -1
...
1 2 3 4
diameter
where M = 6 + 3\*N + 2\*E + 4\*F + 1, and N is the number of vertices in
the body particle, E = number of edges, F = number of faces.
The integer line has three values: number of vertices (N), number of
edges (E) and number of faces (F). The floating point line(s) list 6
moments of inertia followed by the coordinates of the N vertices (x1
to zN) as 3N values, followed by 2N vertex indices corresponding to
the end points of the E edges, then 4\*F vertex indices defining F
faces. The last value is the diameter value = the rounded diameter of
the sphere that surrounds each vertex. The diameter value can be
different for each body particle. These floating-point values can be
listed on as many lines as you wish; see the
:doc:`read\_data <read_data>` command for more details. Because the
maximum number of vertices per face is hard-coded to be 4
(i.e. quadrilaterals), faces with more than 4 vertices need to be
split into triangles or quadrilaterals. For triangular faces, the
last vertex index should be set to -1.
The ordering of the 4 vertices within a face should follow
the right-hand rule so that the normal vector of the face points
outwards from the center of mass.
The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the
values consistent with the current orientation of the rigid body
around its center of mass. The values are with respect to the
simulation box XYZ axes, not with respect to the principal axes of the
rigid body itself. LAMMPS performs the latter calculation internally.
The coordinates of each vertex are specified as its x,y,z displacement
from the center-of-mass of the body particle. The center-of-mass
position of the particle is specified by the x,y,z values in the
*Atoms* section of the data file.
For example, the following information would specify a cubic particle
whose edge length is 2.0 and rounded diameter is 0.5.
The orientation of the cube is aligned with the xyz coordinate axes
which is consistent with the 6 moments of inertia: ixx iyy izz ixy ixz
iyz = 0.667 0.667 0.667 0 0 0.
.. parsed-literal::
1 3 79
8 12 6
0.667 0.667 0.667 0 0 0
1 1 1
1 -1 1
-1 -1 1
-1 1 1
1 1 -1
1 -1 -1
-1 -1 -1
-1 1 -1
0 1
1 2
2 3
3 0
4 5
5 6
6 7
7 4
0 4
1 5
2 6
3 7
0 1 2 3
4 5 6 7
0 1 5 4
1 2 6 5
2 3 7 6
3 0 4 7
0.5
A rod in 3D, whose length is 4.0, mass 1.0 and rounded at two ends
by circles of diameter 0.5, is specified as follows:
.. parsed-literal::
1 1 13
2
0 1.33333 1.33333 0 0 0
-2 0 0
2 0 0
0.5
A sphere whose diameter is 3.0 and mass 1.0, is specified as follows:
.. parsed-literal::
1 1 10
1
0.9 0.9 0.9 0 0 0
0 0 0
3.0
The :doc:`pair\_style body/rounded/polhedron <pair_body_rounded_polyhedron>` command can
be used with this body style to compute body/body interactions. The
:doc:`fix wall/body/polyhedron <fix_wall_body_polygon>` command can be
used with this body style to compute the interaction of body particles
with a wall.
----------
For output purposes via the :doc:`compute body/local <compute_body_local>` and :doc:`dump local <dump>`
commands, this body style produces one datum for each of the N
sub-particles in a body particle. The datum has 3 values:
.. parsed-literal::
1 = x position of vertex
2 = y position of vertex
3 = z position of vertex
These values are the current position of the vertex within the
simulation domain, not a displacement from the center-of-mass (COM) of
the body particle itself. These values are calculated using the
current COM and orientation of the body particle.
For images created by the :doc:`dump image <dump_image>` command, if the
*body* keyword is set, then each body particle is drawn as a polygon
consisting of N line segments. Note that the line segments are drawn
between the N vertices, which does not correspond exactly to the
physical extent of the body (because the :doc:`pair\_style rounded/polygon <pair_body_rounded_polygon>` defines finite-size
spheres at those point and the line segments between the spheres are
tangent to the spheres). The drawn diameter of each line segment is
determined by the *bflag1* parameter for the *body* keyword. The
*bflag2* argument is ignored.
----------
.. _body-Fraige:
**(Fraige)** F. Y. Fraige, P. A. Langston, A. J. Matchett, J. Dodds,
Particuology, 6, 455 (2008).
.. _body-Wang:
**(Wang)** J. Wang, H. S. Yu, P. A. Langston, F. Y. Fraige, Granular
Matter, 13, 1 (2011).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

219
doc/src/Howto_chunk.rst Normal file
View File

@ -0,0 +1,219 @@
Use chunks to calculate system properties
=========================================
In LAMMS, "chunks" are collections of atoms, as defined by the
:doc:`compute chunk/atom <compute_chunk_atom>` command, which assigns
each atom to a chunk ID (or to no chunk at all). The number of chunks
and the assignment of chunk IDs to atoms can be static or change over
time. Examples of "chunks" are molecules or spatial bins or atoms
with similar values (e.g. coordination number or potential energy).
The per-atom chunk IDs can be used as input to two other kinds of
commands, to calculate various properties of a system:
* :doc:`fix ave/chunk <fix_ave_chunk>`
* any of the :doc:`compute \*/chunk <compute>` commands
Here a brief overview for each of the 4 kinds of chunk-related commands
is provided. Then some examples are given of how to compute different
properties with chunk commands.
Compute chunk/atom command:
---------------------------
This compute can assign atoms to chunks of various styles. Only atoms
in the specified group and optional specified region are assigned to a
chunk. Here are some possible chunk definitions:
+---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
| atoms in same molecule | chunk ID = molecule ID |
+---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
| atoms of same atom type | chunk ID = atom type |
+---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
| all atoms with same atom property (charge, radius, etc) | chunk ID = output of compute property/atom |
+---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
| atoms in same cluster | chunk ID = output of :doc:`compute cluster/atom <compute_cluster_atom>` command |
+---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
| atoms in same spatial bin | chunk ID = bin ID |
+---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
| atoms in same rigid body | chunk ID = molecule ID used to define rigid bodies |
+---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
| atoms with similar potential energy | chunk ID = output of :doc:`compute pe/atom <compute_pe_atom>` |
+---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
| atoms with same local defect structure | chunk ID = output of :doc:`compute centro/atom <compute_centro_atom>` or :doc:`compute coord/atom <compute_coord_atom>` command |
+---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
Note that chunk IDs are integer values, so for atom properties or
computes that produce a floating point value, they will be truncated
to an integer. You could also use the compute in a variable that
scales the floating point value to spread it across multiple integers.
Spatial bins can be of various kinds, e.g. 1d bins = slabs, 2d bins =
pencils, 3d bins = boxes, spherical bins, cylindrical bins.
This compute also calculates the number of chunks *Nchunk*\ , which is
used by other commands to tally per-chunk data. *Nchunk* can be a
static value or change over time (e.g. the number of clusters). The
chunk ID for an individual atom can also be static (e.g. a molecule
ID), or dynamic (e.g. what spatial bin an atom is in as it moves).
Note that this compute allows the per-atom output of other
:doc:`computes <compute>`, :doc:`fixes <fix>`, and
:doc:`variables <variable>` to be used to define chunk IDs for each
atom. This means you can write your own compute or fix to output a
per-atom quantity to use as chunk ID. See the :doc:`Modify <Modify>`
doc pages for info on how to do this. You can also define a :doc:`per-atom variable <variable>` in the input script that uses a formula to
generate a chunk ID for each atom.
Fix ave/chunk command:
----------------------
This fix takes the ID of a :doc:`compute chunk/atom <compute_chunk_atom>` command as input. For each chunk,
it then sums one or more specified per-atom values over the atoms in
each chunk. The per-atom values can be any atom property, such as
velocity, force, charge, potential energy, kinetic energy, stress,
etc. Additional keywords are defined for per-chunk properties like
density and temperature. More generally any per-atom value generated
by other :doc:`computes <compute>`, :doc:`fixes <fix>`, and :doc:`per-atom variables <variable>`, can be summed over atoms in each chunk.
Similar to other averaging fixes, this fix allows the summed per-chunk
values to be time-averaged in various ways, and output to a file. The
fix produces a global array as output with one row of values per
chunk.
Compute \*/chunk commands:
--------------------------
The following computes operate on chunks of atoms to produce per-chunk
values. Any compute whose style name ends in "/chunk" is in this
category:
* :doc:`compute com/chunk <compute_com_chunk>`
* :doc:`compute gyration/chunk <compute_gyration_chunk>`
* :doc:`compute inertia/chunk <compute_inertia_chunk>`
* :doc:`compute msd/chunk <compute_msd_chunk>`
* :doc:`compute property/chunk <compute_property_chunk>`
* :doc:`compute temp/chunk <compute_temp_chunk>`
* :doc:`compute torque/chunk <compute_vcm_chunk>`
* :doc:`compute vcm/chunk <compute_vcm_chunk>`
They each take the ID of a :doc:`compute chunk/atom <compute_chunk_atom>` command as input. As their names
indicate, they calculate the center-of-mass, radius of gyration,
moments of inertia, mean-squared displacement, temperature, torque,
and velocity of center-of-mass for each chunk of atoms. The :doc:`compute property/chunk <compute_property_chunk>` command can tally the
count of atoms in each chunk and extract other per-chunk properties.
The reason these various calculations are not part of the :doc:`fix ave/chunk command <fix_ave_chunk>`, is that each requires a more
complicated operation than simply summing and averaging over per-atom
values in each chunk. For example, many of them require calculation
of a center of mass, which requires summing mass\*position over the
atoms and then dividing by summed mass.
All of these computes produce a global vector or global array as
output, wih one or more values per chunk. The output can be used in
various ways:
* As input to the :doc:`fix ave/time <fix_ave_time>` command, which can
write the values to a file and optionally time average them.
* As input to the :doc:`fix ave/histo <fix_ave_histo>` command to
histogram values across chunks. E.g. a histogram of cluster sizes or
molecule diffusion rates.
* As input to special functions of :doc:`equal-style variables <variable>`, like sum() and max() and ave(). E.g. to
find the largest cluster or fastest diffusing molecule or average
radius-of-gyration of a set of molecules (chunks).
Other chunk commands:
---------------------
* :doc:`compute chunk/spread/atom <compute_chunk_spread_atom>`
* :doc:`compute reduce/chunk <compute_reduce_chunk>`
The :doc:`compute chunk/spread/atom <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 <dump>`. Or for using an atom's
associated chunk value in an :doc:`atom-style variable <variable>`. Or
as input to the :doc:`fix ave/chunk <fix_ave_chunk>` command to
spatially average per-chunk values calculated by a per-chunk compute.
The :doc:`compute reduce/chunk <compute_reduce_chunk>` command reduces a
peratom value across the atoms in each chunk to produce a value per
chunk. When used with the :doc:`compute chunk/spread/atom <compute_chunk_spread_atom>` command it can
create peratom values that induce a new set of chunks with a second
:doc:`compute chunk/atom <compute_chunk_atom>` command.
Example calculations with chunks
--------------------------------
Here are examples using chunk commands to calculate various
properties:
(1) Average velocity in each of 1000 2d spatial bins:
.. parsed-literal::
compute cc1 all chunk/atom bin/2d x 0.0 0.1 y lower 0.01 units reduced
fix 1 all ave/chunk 100 10 1000 cc1 vx vy file tmp.out
(2) Temperature in each spatial bin, after subtracting a flow
velocity:
.. parsed-literal::
compute cc1 all chunk/atom bin/2d x 0.0 0.1 y lower 0.1 units reduced
compute vbias all temp/profile 1 0 0 y 10
fix 1 all ave/chunk 100 10 1000 cc1 temp bias vbias file tmp.out
(3) Center of mass of each molecule:
.. parsed-literal::
compute cc1 all chunk/atom molecule
compute myChunk all com/chunk cc1
fix 1 all ave/time 100 1 100 c_myChunk[\*] file tmp.out mode vector
(4) Total force on each molecule and ave/max across all molecules:
.. parsed-literal::
compute cc1 all chunk/atom molecule
fix 1 all ave/chunk 1000 1 1000 cc1 fx fy fz file tmp.out
variable xave equal ave(f_1[2])
variable xmax equal max(f_1[2])
thermo 1000
thermo_style custom step temp v_xave v_xmax
(5) Histogram of cluster sizes:
.. parsed-literal::
compute cluster all cluster/atom 1.0
compute cc1 all chunk/atom c_cluster compress yes
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 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 <compute_chunk_spread_atom>` command doc page.
(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 <compute_reduce_chunk>` 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 <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 <compute_chunk_spread_atom>`
command doc page.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

135
doc/src/Howto_client_server.rst Normal file
View File

@ -0,0 +1,135 @@
Using LAMMPS in client/server mode
==================================
Client/server coupling of two codes is where one code is the "client"
and sends request messages to a "server" code. The server responds to
each request with a reply message. This enables the two codes to work
in tandem to perform a simulation. LAMMPS can act as either a client
or server code.
Some advantages of client/server coupling are that the two codes run
as stand-alone executables; they are not linked together. Thus
neither code needs to have a library interface. This often makes it
easier to run the two codes on different numbers of processors. If a
message protocol (format and content) is defined for a particular kind
of simulation, then in principle any code that implements the
client-side protocol can be used in tandem with any code that
implements the server-side protocol, without the two codes needing to
know anything more specific about each other.
A simple example of client/server coupling is where LAMMPS is the
client code performing MD timestepping. Each timestep it sends a
message to a server quantum code containing current coords of all the
atoms. The quantum code computes energy and forces based on the
coords. It returns them as a message to LAMMPS, which completes the
timestep.
Alternate methods for code coupling with LAMMPS are described on
the :doc:`Howto couple <Howto_couple>` doc page.
LAMMPS support for client/server coupling is in its :ref:`MESSAGE package <PKG-MESSAGE>` which implements several
commands that enable LAMMPS to act as a client or server, as discussed
below. The MESSAGE package also wraps a client/server library called
CSlib which enables two codes to exchange messages in different ways,
either via files, sockets, or MPI. The CSlib is provided with LAMMPS
in the lib/message dir. The CSlib has its own
`website <http://cslib.sandia.gov>`_ with documentation and test
programs.
.. note::
For client/server coupling to work between LAMMPS and another
code, the other code also has to use the CSlib. This can sometimes be
done without any modifications to the other code by simply wrapping it
with a Python script that exchanges CSlib messages with LAMMPS and
prepares input for or processes output from the other code. The other
code also has to implement a matching protocol for the format and
content of messages that LAMMPS exchanges with it.
These are the commands currently in the MESSAGE package for two
protocols, MD and MC (Monte Carlo). New protocols can easily be
defined and added to this directory, where LAMMPS acts as either the
client or server.
* :doc:`message <message>`
* :doc:`fix client md <fix_client_md>` = LAMMPS is a client for running MD
* :doc:`server md <server_md>` = LAMMPS is a server for computing MD forces
* :doc:`server mc <server_mc>` = LAMMPS is a server for computing a Monte Carlo energy
The server doc files give details of the message protocols
for data that is exchanged between the client and server.
These example directories illustrate how to use LAMMPS as either a
client or server code:
* examples/message
* examples/COUPLE/README
* examples/COUPLE/lammps\_mc
* examples/COUPLE/lammps\_vasp
The examples/message dir couples a client instance of LAMMPS to a
server instance of LAMMPS.
The lammps\_mc dir shows how to couple LAMMPS as a server to a simple
Monte Carlo client code as the driver.
The lammps\_vasp dir shows how to couple LAMMPS as a client code
running MD timestepping to VASP acting as a server providing quantum
DFT forces, through a Python wrapper script on VASP.
Here is how to launch a client and server code together for any of the
4 modes of message exchange that the :doc:`message <message>` command
and the CSlib support. Here LAMMPS is used as both the client and
server code. Another code could be substituted for either.
The examples below show launching both codes from the same window (or
batch script), using the "&" character to launch the first code in the
background. For all modes except *mpi/one*\ , you could also launch the
codes in separate windows on your desktop machine. It does not
matter whether you launch the client or server first.
In these examples either code can be run on one or more processors.
If running in a non-MPI mode (file or zmq) you can launch a code on a
single processor without using mpirun.
IMPORTANT: If you run in mpi/two mode, you must launch both codes via
mpirun, even if one or both of them runs on a single processor. This
is so that MPI can figure out how to connect both MPI processes
together to exchange MPI messages between them.
For message exchange in *file*\ , *zmq*\ , or *mpi/two* modes:
.. parsed-literal::
% mpirun -np 1 lmp_mpi -log log.client < in.client &
% mpirun -np 2 lmp_mpi -log log.server < in.server
% mpirun -np 4 lmp_mpi -log log.client < in.client &
% mpirun -np 1 lmp_mpi -log log.server < in.server
% mpirun -np 2 lmp_mpi -log log.client < in.client &
% mpirun -np 4 lmp_mpi -log log.server < in.server
For message exchange in *mpi/one* mode:
Launch both codes in a single mpirun command:
.. parsed-literal::
mpirun -np 2 lmp_mpi -mpicolor 0 -in in.message.client -log log.client : -np 4 lmp_mpi -mpicolor 1 -in in.message.server -log log.server
The two -np values determine how many procs the client and the server
run on.
A LAMMPS executable run in this manner must use the -mpicolor color
command-line option as their its option, where color is an integer
label that will be used to distinguish one executable from another in
the multiple executables that the mpirun command launches. In this
example the client was colored with a 0, and the server with a 1.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

271
doc/src/Howto_coreshell.rst Normal file
View File

@ -0,0 +1,271 @@
Adiabatic core/shell model
==========================
The adiabatic core-shell model by :ref:`Mitchell and Fincham <MitchellFincham>` is a simple method for adding polarizability
to a system. In order to mimic the electron shell of an ion, a
satellite particle is attached to it. This way the ions are split into
a core and a shell where the latter is meant to react to the
electrostatic environment inducing polarizability. See the :doc:`Howto polarizable <Howto_polarizable>` doc page for a discussion of all
the polarizable models available in LAMMPS.
Technically, shells are attached to the cores by a spring force f =
k\*r where k is a parameterized spring constant and r is the distance
between the core and the shell. The charges of the core and the shell
add up to the ion charge, thus q(ion) = q(core) + q(shell). This
setup introduces the ion polarizability (alpha) given by
alpha = q(shell)\^2 / k. In a
similar fashion the mass of the ion is distributed on the core and the
shell with the core having the larger mass.
To run this model in LAMMPS, :doc:`atom\_style <atom_style>` *full* can
be used since atom charge and bonds are needed. Each kind of
core/shell pair requires two atom types and a bond type. The core and
shell of a core/shell pair should be bonded to each other with a
harmonic bond that provides the spring force. For example, a data file
for NaCl, as found in examples/coreshell, has this format:
.. parsed-literal::
432 atoms # core and shell atoms
216 bonds # number of core/shell springs
4 atom types # 2 cores and 2 shells for Na and Cl
2 bond types
0.0 24.09597 xlo xhi
0.0 24.09597 ylo yhi
0.0 24.09597 zlo zhi
Masses # core/shell mass ratio = 0.1
1 20.690784 # Na core
2 31.90500 # Cl core
3 2.298976 # Na shell
4 3.54500 # Cl shell
Atoms
1 1 2 1.5005 0.00000000 0.00000000 0.00000000 # core of core/shell pair 1
2 1 4 -2.5005 0.00000000 0.00000000 0.00000000 # shell of core/shell pair 1
3 2 1 1.5056 4.01599500 4.01599500 4.01599500 # core of core/shell pair 2
4 2 3 -0.5056 4.01599500 4.01599500 4.01599500 # shell of core/shell pair 2
(...)
Bonds # Bond topology for spring forces
1 2 1 2 # spring for core/shell pair 1
2 2 3 4 # spring for core/shell pair 2
(...)
Non-Coulombic (e.g. Lennard-Jones) pairwise interactions are only
defined between the shells. Coulombic interactions are defined
between all cores and shells. If desired, additional bonds can be
specified between cores.
The :doc:`special\_bonds <special_bonds>` command should be used to
turn-off the Coulombic interaction within core/shell pairs, since that
interaction is set by the bond spring. This is done using the
:doc:`special\_bonds <special_bonds>` command with a 1-2 weight = 0.0,
which is the default value. It needs to be considered whether one has
to adjust the :doc:`special\_bonds <special_bonds>` weighting according
to the molecular topology since the interactions of the shells are
bypassed over an extra bond.
Note that this core/shell implementation does not require all ions to
be polarized. One can mix core/shell pairs and ions without a
satellite particle if desired.
Since the core/shell model permits distances of r = 0.0 between the
core and shell, a pair style with a "cs" suffix needs to be used to
implement a valid long-range Coulombic correction. Several such pair
styles are provided in the CORESHELL package. See :doc:`this doc page <pair_cs>` for details. All of the core/shell enabled pair
styles require the use of a long-range Coulombic solver, as specified
by the :doc:`kspace\_style <kspace_style>` command. Either the PPPM or
Ewald solvers can be used.
For the NaCL example problem, these pair style and bond style settings
are used:
.. parsed-literal::
pair_style born/coul/long/cs 20.0 20.0
pair_coeff \* \* 0.0 1.000 0.00 0.00 0.00
pair_coeff 3 3 487.0 0.23768 0.00 1.05 0.50 #Na-Na
pair_coeff 3 4 145134.0 0.23768 0.00 6.99 8.70 #Na-Cl
pair_coeff 4 4 405774.0 0.23768 0.00 72.40 145.40 #Cl-Cl
bond_style harmonic
bond_coeff 1 63.014 0.0
bond_coeff 2 25.724 0.0
When running dynamics with the adiabatic core/shell model, the
following issues should be considered. The relative motion of
the core and shell particles corresponds to the polarization,
hereby an instantaneous relaxation of the shells is approximated
and a fast core/shell spring frequency ensures a nearly constant
internal kinetic energy during the simulation.
Thermostats can alter this polarization behavior, by scaling the
internal kinetic energy, meaning the shell will not react freely to
its electrostatic environment.
Therefore it is typically desirable to decouple the relative motion of
the core/shell pair, which is an imaginary degree of freedom, from the
real physical system. To do that, the :doc:`compute temp/cs <compute_temp_cs>` command can be used, in conjunction with
any of the thermostat fixes, such as :doc:`fix nvt <fix_nh>` or :doc:`fix langevin <fix_langevin>`. This compute uses the center-of-mass velocity
of the core/shell pairs to calculate a temperature, and insures that
velocity is what is rescaled for thermostatting purposes. This
compute also works for a system with both core/shell pairs and
non-polarized ions (ions without an attached satellite particle). The
:doc:`compute temp/cs <compute_temp_cs>` command requires input of two
groups, one for the core atoms, another for the shell atoms.
Non-polarized ions which might also be included in the treated system
should not be included into either of these groups, they are taken
into account by the *group-ID* (2nd argument) of the compute. The
groups can be defined using the :doc:`group *type*\ <group>` command.
Note that to perform thermostatting using this definition of
temperature, the :doc:`fix modify temp <fix_modify>` command should be
used to assign the compute to the thermostat fix. Likewise the
:doc:`thermo\_modify temp <thermo_modify>` command can be used to make
this temperature be output for the overall system.
For the NaCl example, this can be done as follows:
.. parsed-literal::
group cores type 1 2
group shells type 3 4
compute CSequ all temp/cs cores shells
fix thermoberendsen all temp/berendsen 1427 1427 0.4 # thermostat for the true physical system
fix thermostatequ all nve # integrator as needed for the berendsen thermostat
fix_modify thermoberendsen temp CSequ
thermo_modify temp CSequ # output of center-of-mass derived temperature
The pressure for the core/shell system is computed via the regular
LAMMPS convention by :ref:`treating the cores and shells as individual particles <MitchellFincham2>`. For the thermo output of the pressure
as well as for the application of a barostat, it is necessary to
use an additional :doc:`pressure <compute_pressure>` compute based on
the default :doc:`temperature <compute_temp>` and specifying it as a
second argument in :doc:`fix modify <fix_modify>` and
:doc:`thermo\_modify <thermo_modify>` resulting in:
.. parsed-literal::
(...)
compute CSequ all temp/cs cores shells
compute thermo_press_lmp all pressure thermo_temp # pressure for individual particles
thermo_modify temp CSequ press thermo_press_lmp # modify thermo to regular pressure
fix press_bar all npt temp 300 300 0.04 iso 0 0 0.4
fix_modify press_bar temp CSequ press thermo_press_lmp # pressure modification for correct kinetic scalar
If :doc:`compute temp/cs <compute_temp_cs>` is used, the decoupled
relative motion of the core and the shell should in theory be
stable. However numerical fluctuation can introduce a small
momentum to the system, which is noticeable over long trajectories.
Therefore it is recommendable to use the :doc:`fix momentum <fix_momentum>` command in combination with :doc:`compute temp/cs <compute_temp_cs>` when equilibrating the system to
prevent any drift.
When initializing the velocities of a system with core/shell pairs, it
is also desirable to not introduce energy into the relative motion of
the core/shell particles, but only assign a center-of-mass velocity to
the pairs. This can be done by using the *bias* keyword of the
:doc:`velocity create <velocity>` command and assigning the :doc:`compute temp/cs <compute_temp_cs>` command to the *temp* keyword of the
:doc:`velocity <velocity>` command, e.g.
.. parsed-literal::
velocity all create 1427 134 bias yes temp CSequ
velocity all scale 1427 temp CSequ
To maintain the correct polarizability of the core/shell pairs, the
kinetic energy of the internal motion shall remain nearly constant.
Therefore the choice of spring force and mass ratio need to ensure
much faster relative motion of the 2 atoms within the core/shell pair
than their center-of-mass velocity. This allows the shells to
effectively react instantaneously to the electrostatic environment and
limits energy transfer to or from the core/shell oscillators.
This fast movement also dictates the timestep that can be used.
The primary literature of the adiabatic core/shell model suggests that
the fast relative motion of the core/shell pairs only allows negligible
energy transfer to the environment.
The mentioned energy transfer will typically lead to a small drift
in total energy over time. This internal energy can be monitored
using the :doc:`compute chunk/atom <compute_chunk_atom>` and :doc:`compute temp/chunk <compute_temp_chunk>` commands. The internal kinetic
energies of each core/shell pair can then be summed using the sum()
special function of the :doc:`variable <variable>` command. Or they can
be time/averaged and output using the :doc:`fix ave/time <fix_ave_time>`
command. To use these commands, each core/shell pair must be defined
as a "chunk". If each core/shell pair is defined as its own molecule,
the molecule ID can be used to define the chunks. If cores are bonded
to each other to form larger molecules, the chunks can be identified
by the :doc:`fix property/atom <fix_property_atom>` via assigning a
core/shell ID to each atom using a special field in the data file read
by the :doc:`read\_data <read_data>` command. This field can then be
accessed by the :doc:`compute property/atom <compute_property_atom>`
command, to use as input to the :doc:`compute chunk/atom <compute_chunk_atom>` command to define the core/shell
pairs as chunks.
For example if core/shell pairs are the only molecules:
.. parsed-literal::
read_data NaCl_CS_x0.1_prop.data
compute prop all property/atom molecule
compute cs_chunk all chunk/atom c_prop
compute cstherm all temp/chunk cs_chunk temp internal com yes cdof 3.0 # note the chosen degrees of freedom for the core/shell pairs
fix ave_chunk all ave/time 10 1 10 c_cstherm file chunk.dump mode vector
For example if core/shell pairs and other molecules are present:
.. parsed-literal::
fix csinfo all property/atom i_CSID # property/atom command
read_data NaCl_CS_x0.1_prop.data fix csinfo NULL CS-Info # atom property added in the data-file
compute prop all property/atom i_CSID
(...)
The additional section in the date file would be formatted like this:
.. parsed-literal::
CS-Info # header of additional section
1 1 # column 1 = atom ID, column 2 = core/shell ID
2 1
3 2
4 2
5 3
6 3
7 4
8 4
(...)
----------
.. _MitchellFincham:
**(Mitchell and Fincham)** Mitchell, Fincham, J Phys Condensed Matter,
5, 1031-1038 (1993).
.. _MitchellFincham2:
**(Fincham)** Fincham, Mackrodt and Mitchell, J Phys Condensed Matter,
6, 393-404 (1994).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

125
doc/src/Howto_couple.rst Normal file
View File

@ -0,0 +1,125 @@
Coupling LAMMPS to other codes
==============================
LAMMPS is designed to allow it to be coupled to other codes. For
example, a quantum mechanics code might compute forces on a subset of
atoms and pass those forces to LAMMPS. Or a continuum finite element
(FE) simulation might use atom positions as boundary conditions on FE
nodal points, compute a FE solution, and return interpolated forces on
MD atoms.
LAMMPS can be coupled to other codes in at least 4 ways. Each has
advantages and disadvantages, which you'll have to think about in the
context of your application.
----------
(1) Define a new :doc:`fix <fix>` command that calls the other code. In
this scenario, LAMMPS is the driver code. During its timestepping,
the fix is invoked, and can make library calls to the other code,
which has been linked to LAMMPS as a library. This is the way the
`POEMS <poems_>`_ package that performs constrained rigid-body motion on
groups of atoms is hooked to LAMMPS. See the :doc:`fix poems <fix_poems>` command for more details. See the
:doc:`Modify <Modify>` doc pages for info on how to add a new fix to
LAMMPS.
.. _poems: http://www.rpi.edu/~anderk5/lab
----------
(2) Define a new LAMMPS command that calls the other code. This is
conceptually similar to method (1), but in this case LAMMPS and the
other code are on a more equal footing. Note that now the other code
is not called during the timestepping of a LAMMPS run, but between
runs. The LAMMPS input script can be used to alternate LAMMPS runs
with calls to the other code, invoked via the new command. The
:doc:`run <run>` command facilitates this with its *every* option, which
makes it easy to run a few steps, invoke the command, run a few steps,
invoke the command, etc.
In this scenario, the other code can be called as a library, as in
(1), or it could be a stand-alone code, invoked by a system() call
made by the command (assuming your parallel machine allows one or more
processors to start up another program). In the latter case the
stand-alone code could communicate with LAMMPS through files that the
command writes and reads.
See the :doc:`Modify command <Modify_command>` doc page for info on how
to add a new command to LAMMPS.
----------
(3) Use LAMMPS as a library called by another code. In this case the
other code is the driver and calls LAMMPS as needed. Or a wrapper
code could link and call both LAMMPS and another code as libraries.
Again, the :doc:`run <run>` command has options that allow it to be
invoked with minimal overhead (no setup or clean-up) if you wish to do
multiple short runs, driven by another program.
Examples of driver codes that call LAMMPS as a library are included in
the examples/COUPLE directory of the LAMMPS distribution; see
examples/COUPLE/README for more details:
* simple: simple driver programs in C++ and C which invoke LAMMPS as a
library
* lammps\_quest: coupling of LAMMPS and `Quest <quest_>`_, to run classical
MD with quantum forces calculated by a density functional code
* lammps\_spparks: coupling of LAMMPS and `SPPARKS <spparks_>`_, to couple
a kinetic Monte Carlo model for grain growth using MD to calculate
strain induced across grain boundaries
.. _quest: http://dft.sandia.gov/Quest
.. _spparks: http://www.sandia.gov/~sjplimp/spparks.html
The :doc:`Build basics <Build_basics>` doc page describes how to build
LAMMPS as a library. Once this is done, you can interface with LAMMPS
either via C++, C, Fortran, or Python (or any other language that
supports a vanilla C-like interface). For example, from C++ you could
create one (or more) "instances" of LAMMPS, pass it an input script to
process, or execute individual commands, all by invoking the correct
class methods in LAMMPS. From C or Fortran you can make function
calls to do the same things. See the :doc:`Python <Python_head>` doc
pages for a description of the Python wrapper provided with LAMMPS
that operates through the LAMMPS library interface.
The files src/library.cpp and library.h contain the C-style interface
to LAMMPS. See the :doc:`Howto library <Howto_library>` doc page for a
description of the interface and how to extend it for your needs.
Note that the lammps\_open() function that creates an instance of
LAMMPS takes an MPI communicator as an argument. This means that
instance of LAMMPS will run on the set of processors in the
communicator. Thus the calling code can run LAMMPS on all or a subset
of processors. For example, a wrapper script might decide to
alternate between LAMMPS and another code, allowing them both to run
on all the processors. Or it might allocate half the processors to
LAMMPS and half to the other code and run both codes simultaneously
before syncing them up periodically. Or it might instantiate multiple
instances of LAMMPS to perform different calculations.
----------
(4) Couple LAMMPS with another code in a client/server mode. This is
described on the :doc:`Howto client/server <Howto_client_server>` doc
page.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

32
doc/src/Howto_diffusion.rst Normal file
View File

@ -0,0 +1,32 @@
Calculate diffusion coefficients
================================
The diffusion coefficient D of a material can be measured in at least
2 ways using various options in LAMMPS. See the examples/DIFFUSE
directory for scripts that implement the 2 methods discussed here for
a simple Lennard-Jones fluid model.
The first method is to measure the mean-squared displacement (MSD) of
the system, via the :doc:`compute msd <compute_msd>` command. The slope
of the MSD versus time is proportional to the diffusion coefficient.
The instantaneous MSD values can be accumulated in a vector via the
:doc:`fix vector <fix_vector>` command, and a line fit to the vector to
compute its slope via the :doc:`variable slope <variable>` function, and
thus extract D.
The second method is to measure the velocity auto-correlation function
(VACF) of the system, via the :doc:`compute vacf <compute_vacf>`
command. The time-integral of the VACF is proportional to the
diffusion coefficient. The instantaneous VACF values can be
accumulated in a vector via the :doc:`fix vector <fix_vector>` command,
and time integrated via the :doc:`variable trap <variable>` function,
and thus extract D.
----------
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

105
doc/src/Howto_dispersion.rst Normal file
View File

@ -0,0 +1,105 @@
Long-range dispersion settings
==============================
The PPPM method computes interactions by splitting the pair potential
into two parts, one of which is computed in a normal pairwise fashion,
the so-called real-space part, and one of which is computed using the
Fourier transform, the so called reciprocal-space or kspace part. For
both parts, the potential is not computed exactly but is approximated.
Thus, there is an error in both parts of the computation, the
real-space and the kspace error. The just mentioned facts are true
both for the PPPM for Coulomb as well as dispersion interactions. The
deciding difference - and also the reason why the parameters for
pppm/disp have to be selected with more care - is the impact of the
errors on the results: The kspace error of the PPPM for Coulomb and
dispersion interaction and the real-space error of the PPPM for
Coulomb interaction have the character of noise. In contrast, the
real-space error of the PPPM for dispersion has a clear physical
interpretation: the underprediction of cohesion. As a consequence, the
real-space error has a much stronger effect than the kspace error on
simulation results for pppm/disp. Parameters must thus be chosen in a
way that this error is much smaller than the kspace error.
When using pppm/disp and not making any specifications on the PPPM
parameters via the kspace modify command, parameters will be tuned
such that the real-space error and the kspace error are equal. This
will result in simulations that are either inaccurate or slow, both of
which is not desirable. For selecting parameters for the pppm/disp
that provide fast and accurate simulations, there are two approaches,
which both have their up- and downsides.
The first approach is to set desired real-space an kspace accuracies
via the *kspace\_modify force/disp/real* and *kspace\_modify
force/disp/kspace* commands. Note that the accuracies have to be
specified in force units and are thus dependent on the chosen unit
settings. For real units, 0.0001 and 0.002 seem to provide reasonable
accurate and efficient computations for the real-space and kspace
accuracies. 0.002 and 0.05 work well for most systems using lj
units. PPPM parameters will be generated based on the desired
accuracies. The upside of this approach is that it usually provides a
good set of parameters and will work for both the *kspace\_modify diff
ad* and *kspace\_modify diff ik* options. The downside of the method
is that setting the PPPM parameters will take some time during the
initialization of the simulation.
The second approach is to set the parameters for the pppm/disp
explicitly using the *kspace\_modify mesh/disp*, *kspace\_modify
order/disp*, and *kspace\_modify gewald/disp* commands. This approach
requires a more experienced user who understands well the impact of
the choice of parameters on the simulation accuracy and
performance. This approach provides a fast initialization of the
simulation. However, it is sensitive to errors: A combination of
parameters that will perform well for one system might result in
far-from-optimal conditions for other simulations. For example,
parameters that provide accurate and fast computations for
all-atomistic force fields can provide insufficient accuracy or
united-atomistic force fields (which is related to that the latter
typically have larger dispersion coefficients).
To avoid inaccurate or inefficient simulations, the pppm/disp stops
simulations with an error message if no action is taken to control the
PPPM parameters. If the automatic parameter generation is desired and
real-space and kspace accuracies are desired to be equal, this error
message can be suppressed using the *kspace\_modify disp/auto yes*
command.
A reasonable approach that combines the upsides of both methods is to
make the first run using the *kspace\_modify force/disp/real* and
*kspace\_modify force/disp/kspace* commands, write down the PPPM
parameters from the output, and specify these parameters using the
second approach in subsequent runs (which have the same composition,
force field, and approximately the same volume).
Concerning the performance of the pppm/disp there are two more things
to consider. The first is that when using the pppm/disp, the cutoff
parameter does no longer affect the accuracy of the simulation
(subject to that gewald/disp is adjusted when changing the cutoff).
The performance can thus be increased by examining different values
for the cutoff parameter. A lower bound for the cutoff is only set by
the truncation error of the repulsive term of pair potentials.
The second is that the mixing rule of the pair style has an impact on
the computation time when using the pppm/disp. Fastest computations
are achieved when using the geometric mixing rule. Using the
arithmetic mixing rule substantially increases the computational cost.
The computational overhead can be reduced using the *kspace\_modify
mix/disp geom* and *kspace\_modify splittol* commands. The first
command simply enforces geometric mixing of the dispersion
coefficients in kspace computations. This introduces some error in
the computations but will also significantly speed-up the
simulations. The second keyword sets the accuracy with which the
dispersion coefficients are approximated using a matrix factorization
approach. This may result in better accuracy then using the first
command, but will usually also not provide an equally good increase of
efficiency.
Finally, pppm/disp can also be used when no mixing rules apply.
This can be achieved using the *kspace\_modify mix/disp none* command.
Note that the code does not check automatically whether any mixing
rule is fulfilled. If mixing rules do not apply, the user will have
to specify this command explicitly.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

72
doc/src/Howto_drude.rst Normal file
View File

@ -0,0 +1,72 @@
Drude induced dipoles
=====================
The thermalized Drude model represents induced dipoles by a pair of
charges (the core atom and the Drude particle) connected by a harmonic
spring. See the :doc:`Howto polarizable <Howto_polarizable>` doc page
for a discussion of all the polarizable models available in LAMMPS.
The Drude model has a number of features aimed at its use in
molecular systems (:ref:`Lamoureux and Roux <howto-Lamoureux>`):
* Thermostatting of the additional degrees of freedom associated with the
induced dipoles at very low temperature, in terms of the reduced
coordinates of the Drude particles with respect to their cores. This
makes the trajectory close to that of relaxed induced dipoles.
* Consistent definition of 1-2 to 1-4 neighbors. A core-Drude particle
pair represents a single (polarizable) atom, so the special screening
factors in a covalent structure should be the same for the core and
the Drude particle. Drude particles have to inherit the 1-2, 1-3, 1-4
special neighbor relations from their respective cores.
* Stabilization of the interactions between induced dipoles. Drude
dipoles on covalently bonded atoms interact too strongly due to the
short distances, so an atom may capture the Drude particle of a
neighbor, or the induced dipoles within the same molecule may align
too much. To avoid this, damping at short range can be done by Thole
functions (for which there are physical grounds). This Thole damping
is applied to the point charges composing the induced dipole (the
charge of the Drude particle and the opposite charge on the core, not
to the total charge of the core atom).
A detailed tutorial covering the usage of Drude induced dipoles in
LAMMPS is on the :doc:`Howto drude2e <Howto_drude2>` doc page.
As with the core-shell model, the cores and Drude particles should
appear in the data file as standard atoms. The same holds for the
springs between them, which are described by standard harmonic bonds.
The nature of the atoms (core, Drude particle or non-polarizable) is
specified via the :doc:`fix drude <fix_drude>` command. The special
list of neighbors is automatically refactored to account for the
equivalence of core and Drude particles as regards special 1-2 to 1-4
screening. It may be necessary to use the *extra/special/per/atom*
keyword of the :doc:`read\_data <read_data>` command. If using :doc:`fix shake <fix_shake>`, make sure no Drude particle is in this fix
group.
There are two ways to thermostat the Drude particles at a low
temperature: use either :doc:`fix langevin/drude <fix_langevin_drude>`
for a Langevin thermostat, or :doc:`fix drude/transform/\* <fix_drude_transform>` for a Nose-Hoover
thermostat. The former requires use of the command :doc:`comm\_modify vel yes <comm_modify>`. The latter requires two separate integration
fixes like *nvt* or *npt*\ . The correct temperatures of the reduced
degrees of freedom can be calculated using the :doc:`compute temp/drude <compute_temp_drude>`. This requires also to use the
command *comm\_modify vel yes*.
Short-range damping of the induced dipole interactions can be achieved
using Thole functions through the :doc:`pair style thole <pair_thole>` in :doc:`pair\_style hybrid/overlay <pair_hybrid>`
with a Coulomb pair style. It may be useful to use *coul/long/cs* or
similar from the CORESHELL package if the core and Drude particle come
too close, which can cause numerical issues.
----------
.. _howto-Lamoureux:
**(Lamoureux and Roux)** G. Lamoureux, B. Roux, J. Chem. Phys 119, 3025 (2003)
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

542
doc/src/Howto_drude2.rst Normal file
View File

@ -0,0 +1,542 @@
Tutorial for Thermalized Drude oscillators in LAMMPS
====================================================
This tutorial explains how to use Drude oscillators in LAMMPS to
simulate polarizable systems using the USER-DRUDE package. As an
illustration, the input files for a simulation of 250 phenol molecules
are documented. First of all, LAMMPS has to be compiled with the
USER-DRUDE package activated. Then, the data file and input scripts
have to be modified to include the Drude dipoles and how to handle
them.
----------
**Overview of Drude induced dipoles**
Polarizable atoms acquire an induced electric dipole moment under the
action of an external electric field, for example the electric field
created by the surrounding particles. Drude oscillators represent
these dipoles by two fixed charges: the core (DC) and the Drude
particle (DP) bound by a harmonic potential. The Drude particle can be
thought of as the electron cloud whose center can be displaced from
the position of the corresponding nucleus.
The sum of the masses of a core-Drude pair should be the mass of the
initial (unsplit) atom, :math:`m_C + m_D = m`. The sum of their charges
should be the charge of the initial (unsplit) atom, :math:`q_C + q_D = q`.
A harmonic potential between the core and Drude partners should be
present, with force constant :math:`k_D` and an equilibrium distance of
zero. The (half-)stiffness of the :doc:`harmonic bond <bond_harmonic>`
:math:`K_D = k_D/2` and the Drude charge :math:`q_D` are related to the atom
polarizability :math:`\alpha` by
.. math::
\begin{equation} K_D = \frac 1 2\, \frac {q_D^2} \alpha\end{equation}
Ideally, the mass of the Drude particle should be small, and the
stiffness of the harmonic bond should be large, so that the Drude
particle remains close ot the core. The values of Drude mass, Drude
charge, and force constant can be chosen following different
strategies, as in the following examples of polarizable force
fields:
* :ref:`Lamoureux and Roux <Lamoureux2>` suggest adopting a global half-stiffness, :math:`K_D` = 500 kcal/(mol Ang :math:`{}^2`) - which corresponds to a force constant :math:`k_D` = 4184 kJ/(mol Ang :math:`{}^2`) - for all types of core-Drude bond, a global mass :math:`m_D` = 0.4 g/mol (or u) for all types of Drude particles, and to calculate the Drude charges for individual atom types from the atom polarizabilities using equation (1). This choice is followed in the polarizable CHARMM force field.
* Alternately :ref:`Schroeder and Steinhauser <Schroeder>` suggest adopting a global charge :math:`q_D` = -1.0e and a global mass :math:`m_D` = 0.1 g/mol (or u) for all Drude particles, and to calculate the force constant for each type of core-Drude bond from equation (1). The timesteps used by these authors are between 0.5 and 2 fs, with the degrees of freedom of the Drude oscillators kept cold at 1 K.
* In both these force fields hydrogen atoms are treated as non-polarizable.
The motion of of the Drude particles can be calculated by minimizing
the energy of the induced dipoles at each timestep, by an iterative,
self-consistent procedure. The Drude particles can be massless and
therefore do not contribute to the kinetic energy. However, the
relaxed method is computational slow. An extended-lagrangian method
can be used to calculate the positions of the Drude particles, but
this requires them to have mass. It is important in this case to
decouple the degrees of freedom associated with the Drude oscillators
from those of the normal atoms. Thermalizing the Drude dipoles at
temperatures comparable to the rest of the simulation leads to several
problems (kinetic energy transfer, very short timestep, etc.), which
can be remedied by the "cold Drude" technique (:ref:`Lamoureux and Roux <Lamoureux2>`).
Two closely related models are used to represent polarization through
"charges on a spring": the core-shell model and the Drude
model. Although the basic idea is the same, the core-shell model is
normally used for ionic/crystalline materials, whereas the Drude model
is normally used for molecular systems and fluid states. In ionic
crystals the symmetry around each ion and the distance between them
are such that the core-shell model is sufficiently stable. But to be
applicable to molecular/covalent systems the Drude model includes two
important features:
#. The possibility to thermostat the additional degrees of freedom associated with the induced dipoles at very low temperature, in terms of the reduced coordinates of the Drude particles with respect to their cores. This makes the trajectory close to that of relaxed induced dipoles.
#. The Drude dipoles on covalently bonded atoms interact too strongly due to the short distances, so an atom may capture the Drude particle (shell) of a neighbor, or the induced dipoles within the same molecule may align too much. To avoid this, damping at short of the interactions between the point charges composing the induced dipole can be done by :ref:`Thole <Thole2>` functions.
----------
**Preparation of the data file**
The data file is similar to a standard LAMMPS data file for
*atom\_style full*. The DPs and the *harmonic bonds* connecting them
to their DC should appear in the data file as normal atoms and bonds.
You can use the *polarizer* tool (Python script distributed with the
USER-DRUDE package) to convert a non-polarizable data file (here
*data.102494.lmp*\ ) to a polarizable data file (\ *data-p.lmp*\ )
.. parsed-literal::
polarizer -q -f phenol.dff data.102494.lmp data-p.lmp
This will automatically insert the new atoms and bonds.
The masses and charges of DCs and DPs are computed
from *phenol.dff*\ , as well as the DC-DP bond constants. The file
*phenol.dff* contains the polarizabilities of the atom types
and the mass of the Drude particles, for instance:
.. parsed-literal::
# units: kJ/mol, A, deg
# kforce is in the form k/2 r_D\^2
# type m_D/u q_D/e k_D alpha/A3 thole
OH 0.4 -1.0 4184.0 0.63 0.67
CA 0.4 -1.0 4184.0 1.36 2.51
CAI 0.4 -1.0 4184.0 1.09 2.51
The hydrogen atoms are absent from this file, so they will be treated
as non-polarizable atoms. In the non-polarizable data file
*data.102494.lmp*\ , atom names corresponding to the atom type numbers
have to be specified as comments at the end of lines of the *Masses*
section. You probably need to edit it to add these names. It should
look like
.. parsed-literal::
Masses
1 12.011 # CAI
2 12.011 # CA
3 15.999 # OH
4 1.008 # HA
5 1.008 # HO
----------
**Basic input file**
The atom style should be set to (or derive from) *full*\ , so that you
can define atomic charges and molecular bonds, angles, dihedrals...
The *polarizer* tool also outputs certain lines related to the input
script (the use of these lines will be explained below). In order for
LAMMPS to recognize that you are using Drude oscillators, you should
use the fix *drude*\ . The command is
.. parsed-literal::
fix DRUDE all drude C C C N N D D D
The N, C, D following the *drude* keyword have the following meaning:
There is one tag for each atom type. This tag is C for DCs, D for DPs
and N for non-polarizable atoms. Here the atom types 1 to 3 (C and O
atoms) are DC, atom types 4 and 5 (H atoms) are non-polarizable and
the atom types 6 to 8 are the newly created DPs.
By recognizing the fix *drude*\ , LAMMPS will find and store matching
DC-DP pairs and will treat DP as equivalent to their DC in the
*special bonds* relations. It may be necessary to extend the space
for storing such special relations. In this case extra space should
be reserved by using the *extra/special/per/atom* keyword of either
the :doc:`read\_data <read_data>` or :doc:`create\_box <create_box>`
command. With our phenol, there is 1 more special neighbor for which
space is required. Otherwise LAMMPS crashes and gives the required
value.
.. parsed-literal::
read_data data-p.lmp extra/special/per/atom 1
Let us assume we want to run a simple NVT simulation at 300 K. Note
that Drude oscillators need to be thermalized at a low temperature in
order to approximate a self-consistent field (SCF), therefore it is not
possible to simulate an NVE ensemble with this package. Since dipoles
are approximated by a charged DC-DP pair, the *pair\_style* must
include Coulomb interactions, for instance *lj/cut/coul/long* with
*kspace\_style pppm*. For example, with a cutoff of 10. and a precision
1.e-4:
.. parsed-literal::
pair_style lj/cut/coul/long 10.0
kspace_style pppm 1.0e-4
As compared to the non-polarizable input file, *pair\_coeff* lines need
to be added for the DPs. Since the DPs have no Lennard-Jones
interactions, their *epsilon* is 0. so the only *pair\_coeff* line
that needs to be added is
.. parsed-literal::
pair_coeff \* 6\* 0.0 0.0 # All-DPs
Now for the thermalization, the simplest choice is to use the :doc:`fix langevin/drude <fix_langevin_drude>`.
.. parsed-literal::
fix LANG all langevin/drude 300. 100 12435 1. 20 13977
This applies a Langevin thermostat at temperature 300. to the centers
of mass of the DC-DP pairs, with relaxation time 100 and with random
seed 12345. This fix applies also a Langevin thermostat at temperature
1. to the relative motion of the DPs around their DCs, with relaxation
time 20 and random seed 13977. Only the DCs and non-polarizable
atoms need to be in this fix's group. LAMMPS will thermostat the DPs
together with their DC. For this, ghost atoms need to know their
velocities. Thus you need to add the following command:
.. parsed-literal::
comm_modify vel yes
In order to avoid that the center of mass of the whole system
drifts due to the random forces of the Langevin thermostat on DCs, you
can add the *zero yes* option at the end of the fix line.
If the fix *shake* is used to constrain the C-H bonds, it should be
invoked after the fix *langevin/drude* for more accuracy.
.. parsed-literal::
fix SHAKE ATOMS shake 0.0001 20 0 t 4 5
.. note::
The group of the fix *shake* must not include the DPs. If the
group *ATOMS* is defined by non-DPs atom types, you could use
Since the fix *langevin/drude* does not perform time integration (just
modification of forces but no position/velocity updates), the fix
*nve* should be used in conjunction.
.. parsed-literal::
fix NVE all nve
Finally, do not forget to update the atom type elements if you use
them in a *dump\_modify ... element ...* command, by adding the element
type of the DPs. Here for instance
.. parsed-literal::
dump DUMP all custom 10 dump.lammpstrj id mol type element x y z ix iy iz
dump_modify DUMP element C C O H H D D D
The input file should now be ready for use!
You will notice that the global temperature *thermo\_temp* computed by
LAMMPS is not 300. K as wanted. This is because LAMMPS treats DPs as
standard atoms in his default compute. If you want to output the
temperatures of the DC-DP pair centers of mass and of the DPs relative
to their DCs, you should use the :doc:`compute temp\_drude <compute_temp_drude>`
.. parsed-literal::
compute TDRUDE all temp/drude
And then output the correct temperatures of the Drude oscillators
using *thermo\_style custom* with respectively *c\_TDRUDE[1]* and
*c\_TDRUDE[2]*. These should be close to 300.0 and 1.0 on average.
.. parsed-literal::
thermo_style custom step temp c_TDRUDE[1] c_TDRUDE[2]
----------
**Thole screening**
Dipolar interactions represented by point charges on springs may not
be stable, for example if the atomic polarizability is too high for
instance, a DP can escape from its DC and be captured by another DC,
which makes the force and energy diverge and the simulation
crash. Even without reaching this extreme case, the correlation
between nearby dipoles on the same molecule may be exaggerated. Often,
special bond relations prevent bonded neighboring atoms to see the
charge of each other's DP, so that the problem does not always appear.
It is possible to use screened dipole-dipole interactions by using the
:doc:`*pair\_style thole* <pair_thole>`. This is implemented as a
correction to the Coulomb pair\_styles, which dampens at short distance
the interactions between the charges representing the induced dipoles.
It is to be used as *hybrid/overlay* with any standard *coul* pair
style. In our example, we would use
.. parsed-literal::
pair_style hybrid/overlay lj/cut/coul/long 10.0 thole 2.6 10.0
This tells LAMMPS that we are using two pair\_styles. The first one is
as above (\ *lj/cut/coul/long 10.0*\ ). The second one is a *thole*
pair\_style with default screening factor 2.6 (:ref:`Noskov <Noskov2>`) and
cutoff 10.0.
Since *hybrid/overlay* does not support mixing rules, the interaction
coefficients of all the pairs of atom types with i < j should be
explicitly defined. The output of the *polarizer* script can be used
to complete the *pair\_coeff* section of the input file. In our
example, this will look like:
.. parsed-literal::
pair_coeff 1 1 lj/cut/coul/long 0.0700 3.550
pair_coeff 1 2 lj/cut/coul/long 0.0700 3.550
pair_coeff 1 3 lj/cut/coul/long 0.1091 3.310
pair_coeff 1 4 lj/cut/coul/long 0.0458 2.985
pair_coeff 2 2 lj/cut/coul/long 0.0700 3.550
pair_coeff 2 3 lj/cut/coul/long 0.1091 3.310
pair_coeff 2 4 lj/cut/coul/long 0.0458 2.985
pair_coeff 3 3 lj/cut/coul/long 0.1700 3.070
pair_coeff 3 4 lj/cut/coul/long 0.0714 2.745
pair_coeff 4 4 lj/cut/coul/long 0.0300 2.420
pair_coeff \* 5 lj/cut/coul/long 0.0000 0.000
pair_coeff \* 6\* lj/cut/coul/long 0.0000 0.000
pair_coeff 1 1 thole 1.090 2.510
pair_coeff 1 2 thole 1.218 2.510
pair_coeff 1 3 thole 0.829 1.590
pair_coeff 1 6 thole 1.090 2.510
pair_coeff 1 7 thole 1.218 2.510
pair_coeff 1 8 thole 0.829 1.590
pair_coeff 2 2 thole 1.360 2.510
pair_coeff 2 3 thole 0.926 1.590
pair_coeff 2 6 thole 1.218 2.510
pair_coeff 2 7 thole 1.360 2.510
pair_coeff 2 8 thole 0.926 1.590
pair_coeff 3 3 thole 0.630 0.670
pair_coeff 3 6 thole 0.829 1.590
pair_coeff 3 7 thole 0.926 1.590
pair_coeff 3 8 thole 0.630 0.670
pair_coeff 6 6 thole 1.090 2.510
pair_coeff 6 7 thole 1.218 2.510
pair_coeff 6 8 thole 0.829 1.590
pair_coeff 7 7 thole 1.360 2.510
pair_coeff 7 8 thole 0.926 1.590
pair_coeff 8 8 thole 0.630 0.670
For the *thole* pair style the coefficients are
#. the atom polarizability in units of cubic length
#. the screening factor of the Thole function (optional, default value
specified by the pair\_style command)
#. the cutoff (optional, default value defined by the pair\_style command)
The special neighbors have charge-charge and charge-dipole
interactions screened by the *coul* factors of the *special\_bonds*
command (0.0, 0.0, and 0.5 in the example above). Without using the
pair\_style *thole*\ , dipole-dipole interactions are screened by the
same factor. By using the pair\_style *thole*\ , dipole-dipole
interactions are screened by Thole's function, whatever their special
relationship (except within each DC-DP pair of course). Consider for
example 1-2 neighbors: using the pair\_style *thole*\ , their dipoles
will see each other (despite the *coul* factor being 0.) and the
interactions between these dipoles will be damped by Thole's function.
----------
**Thermostats and barostats**
Using a Nose-Hoover barostat with the *langevin/drude* thermostat is
straightforward using fix *nph* instead of *nve*\ . For example:
.. parsed-literal::
fix NPH all nph iso 1. 1. 500
It is also possible to use a Nose-Hoover instead of a Langevin
thermostat. This requires to use :doc:`\ *fix drude/transform*\ <fix_drude_transform>` just before and after the
time integration fixes. The *fix drude/transform/direct* converts the
atomic masses, positions, velocities and forces into a reduced
representation, where the DCs transform into the centers of mass of
the DC-DP pairs and the DPs transform into their relative position
with respect to their DC. The *fix drude/transform/inverse* performs
the reverse transformation. For a NVT simulation, with the DCs and
atoms at 300 K and the DPs at 1 K relative to their DC one would use
.. parsed-literal::
fix DIRECT all drude/transform/direct
fix NVT1 ATOMS nvt temp 300. 300. 100
fix NVT2 DRUDES nvt temp 1. 1. 20
fix INVERSE all drude/transform/inverse
For our phenol example, the groups would be defined as
.. parsed-literal::
group ATOMS type 1 2 3 4 5 # DCs and non-polarizable atoms
group CORES type 1 2 3 # DCs
group DRUDES type 6 7 8 # DPs
Note that with the fixes *drude/transform*\ , it is not required to
specify *comm\_modify vel yes* because the fixes do it anyway (several
times and for the forces also). To avoid the flying ice cube artifact
:ref:`(Lamoureux) <Lamoureux2>`, where the atoms progressively freeze and the
center of mass of the whole system drifts faster and faster, the *fix
momentum* can be used. For instance:
.. parsed-literal::
fix MOMENTUM all momentum 100 linear 1 1 1
It is a bit more tricky to run a NPT simulation with Nose-Hoover
barostat and thermostat. First, the volume should be integrated only
once. So the fix for DCs and atoms should be *npt* while the fix for
DPs should be *nvt* (or vice versa). Second, the *fix npt* computes a
global pressure and thus a global temperature whatever the fix group.
We do want the pressure to correspond to the whole system, but we want
the temperature to correspond to the fix group only. We must then use
the *fix\_modify* command for this. In the end, the block of
instructions for thermostatting and barostatting will look like
.. parsed-literal::
compute TATOMS ATOMS temp
fix DIRECT all drude/transform/direct
fix NPT ATOMS npt temp 300. 300. 100 iso 1. 1. 500
fix_modify NPT temp TATOMS press thermo_press
fix NVT DRUDES nvt temp 1. 1. 20
fix INVERSE all drude/transform/inverse
----------
**Rigid bodies**
You may want to simulate molecules as rigid bodies (but polarizable).
Common cases are water models such as :ref:`SWM4-NDP <SWM4-NDP>`, which is a
kind of polarizable TIP4P water. The rigid bodies and the DPs should
be integrated separately, even with the Langevin thermostat. Let us
review the different thermostats and ensemble combinations.
NVT ensemble using Langevin thermostat:
.. parsed-literal::
comm_modify vel yes
fix LANG all langevin/drude 300. 100 12435 1. 20 13977
fix RIGID ATOMS rigid/nve/small molecule
fix NVE DRUDES nve
NVT ensemble using Nose-Hoover thermostat:
.. parsed-literal::
fix DIRECT all drude/transform/direct
fix RIGID ATOMS rigid/nvt/small molecule temp 300. 300. 100
fix NVT DRUDES nvt temp 1. 1. 20
fix INVERSE all drude/transform/inverse
NPT ensemble with Langevin thermostat:
.. parsed-literal::
comm_modify vel yes
fix LANG all langevin/drude 300. 100 12435 1. 20 13977
fix RIGID ATOMS rigid/nph/small molecule iso 1. 1. 500
fix NVE DRUDES nve
NPT ensemble using Nose-Hoover thermostat:
.. parsed-literal::
compute TATOM ATOMS temp
fix DIRECT all drude/transform/direct
fix RIGID ATOMS rigid/npt/small molecule temp 300. 300. 100 iso 1. 1. 500
fix_modify RIGID temp TATOM press thermo_press
fix NVT DRUDES nvt temp 1. 1. 20
fix INVERSE all drude/transform/inverse
----------
.. _Lamoureux2:
**(Lamoureux)** Lamoureux and Roux, J Chem Phys, 119, 3025-3039 (2003)
.. _Schroeder:
**(Schroeder)** Schroeder and Steinhauser, J Chem Phys, 133,
154511 (2010).
.. _Jiang2:
**(Jiang)** Jiang, Hardy, Phillips, MacKerell, Schulten, and Roux,
J Phys Chem Lett, 2, 87-92 (2011).
.. _Thole2:
**(Thole)** Chem Phys, 59, 341 (1981).
.. _Noskov2:
**(Noskov)** Noskov, Lamoureux and Roux, J Phys Chem B, 109, 6705 (2005).
.. _SWM4-NDP:
**(SWM4-NDP)** Lamoureux, Harder, Vorobyov, Roux, MacKerell, Chem Phys
Let, 418, 245-249 (2006)
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

49
doc/src/Howto_elastic.rst Normal file
View File

@ -0,0 +1,49 @@
Calculate elastic constants
===========================
Elastic constants characterize the stiffness of a material. The formal
definition is provided by the linear relation that holds between the
stress and strain tensors in the limit of infinitesimal deformation.
In tensor notation, this is expressed as s\_ij = C\_ijkl \* e\_kl, where
the repeated indices imply summation. s\_ij are the elements of the
symmetric stress tensor. e\_kl are the elements of the symmetric strain
tensor. C\_ijkl are the elements of the fourth rank tensor of elastic
constants. In three dimensions, this tensor has 3\^4=81 elements. Using
Voigt notation, the tensor can be written as a 6x6 matrix, where C\_ij
is now the derivative of s\_i w.r.t. e\_j. Because s\_i is itself a
derivative w.r.t. e\_i, it follows that C\_ij is also symmetric, with at
most 7\*6/2 = 21 distinct elements.
At zero temperature, it is easy to estimate these derivatives by
deforming the simulation box in one of the six directions using the
:doc:`change\_box <change_box>` command and measuring the change in the
stress tensor. A general-purpose script that does this is given in the
examples/elastic directory described on the :doc:`Examples <Examples>`
doc page.
Calculating elastic constants at finite temperature is more
challenging, because it is necessary to run a simulation that performs
time averages of differential properties. One way to do this is to
measure the change in average stress tensor in an NVT simulations when
the cell volume undergoes a finite deformation. In order to balance
the systematic and statistical errors in this method, the magnitude of
the deformation must be chosen judiciously, and care must be taken to
fully equilibrate the deformed cell before sampling the stress
tensor. Another approach is to sample the triclinic cell fluctuations
that occur in an NPT simulation. This method can also be slow to
converge and requires careful post-processing :ref:`(Shinoda) <Shinoda1>`
----------
.. _Shinoda1:
**(Shinoda)** Shinoda, Shiga, and Mikami, Phys Rev B, 69, 134103 (2004).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

499
doc/src/Howto_github.rst Normal file
View File

@ -0,0 +1,499 @@
LAMMPS GitHub tutorial
======================
**written by Stefan Paquay**
----------
This document describes the process of how to use GitHub to integrate
changes or additions you have made to LAMMPS into the official LAMMPS
distribution. It uses the process of updating this very tutorial as
an example to describe the individual steps and options. You need to
be familiar with git and you may want to have a look at the
`Git book <http://git-scm.com/book/>`_ to reacquaint yourself with some
of the more advanced git features used below.
As of fall 2016, submitting contributions to LAMMPS via pull requests
on GitHub is the preferred option for integrating contributed features
or improvements to LAMMPS, as it significantly reduces the amount of
work required by the LAMMPS developers. Consequently, creating a pull
request will increase your chances to have your contribution included
and will reduce the time until the integration is complete. For more
information on the requirements to have your code included into LAMMPS
please see the :doc:`Modify contribute <Modify_contribute>` doc page.
----------
**Making an account**
First of all, you need a GitHub account. This is fairly simple, just
go to `GitHub <https://github.com>`_ and create an account by clicking
the "Sign up for GitHub" button. Once your account is created, you
can sign in by clicking the button in the top left and filling in your
username or e-mail address and password.
----------
**Forking the repository**
To get changes into LAMMPS, you need to first fork the `lammps/lammps`
repository on GitHub. At the time of writing, *master* is the preferred
target branch. Thus go to `LAMMPS on GitHub <https://github.com/lammps/lammps>`_
and make sure branch is set to "master", as shown in the figure below.
.. image:: JPG/tutorial_branch.png
:align: center
If it is not, use the button to change it to *master*\ . Once it is, use the
fork button to create a fork.
.. image:: JPG/tutorial_fork.png
:align: center
This will create a fork (which is essentially a copy, but uses less
resources) of the LAMMPS repository under your own GitHub account. You
can make changes in this fork and later file *pull requests* to allow
the upstream repository to merge changes from your own fork into the one
we just forked from (or others that were forked from the same repository).
At the same time, you can set things up, so you can include changes from
upstream into your repository and thus keep it in sync with the ongoing
LAMMPS development.
----------
**Adding changes to your own fork**
Additions to the upstream version of LAMMPS are handled using *feature
branches*\ . For every new feature, a so-called feature branch is
created, which contains only those modification relevant to one specific
feature. For example, adding a single fix would consist of creating a
branch with only the fix header and source file and nothing else. It is
explained in more detail here: `feature branch workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow>`_.
**Feature branches**
First of all, create a clone of your version on github on your local
machine via HTTPS:
.. parsed-literal::
$ git clone https://github.com/<your user name>/lammps.git <some name>
or, if you have set up your GitHub account for using SSH keys, via SSH:
.. parsed-literal::
$ git clone git@github.com:<your user name>/lammps.git
You can find the proper URL by clicking the "Clone or download"-button:
.. image:: JPG/tutorial_https_block.png
:align: center
The above command copies ("clones") the git repository to your local
machine to a directory with the name you chose. If none is given, it will
default to "lammps". Typical names are "mylammps" or something similar.
You can use this local clone to make changes and
test them without interfering with the repository on GitHub.
To pull changes from upstream into this copy, you can go to the directory
and use git pull:
.. parsed-literal::
$ cd mylammps
$ git checkout master
$ git pull https://github.com/lammps/lammps
You can also add this URL as a remote:
.. parsed-literal::
$ git remote add lammps_upstream https://www.github.com/lammps/lammps
At this point, you typically make a feature branch from the updated master
branch for the feature you want to work on. This tutorial contains the
workflow that updated this tutorial, and hence we will call the branch
"github-tutorial-update":
.. parsed-literal::
$ git checkout -b github-tutorial-update master
Now that we have changed branches, we can make our changes to our local
repository. Just remember that if you want to start working on another,
unrelated feature, you should switch branches!
**After changes are made**
After everything is done, add the files to the branch and commit them:
.. parsed-literal::
$ git add doc/src/Howto_github.txt
$ git add doc/src/JPG/tutorial\*.png
.. warning::
Do not use *git commit -a* (or *git add -A*\ ). The -a
flag (or -A flag) will automatically include \_all\\_ modified or new files
and that is rarely the behavior you want. It can easily lead to
accidentally adding unrelated and unwanted changes into the repository.
Instead it is preferable to explicitly use *git add*\ , *git rm*\ , *git mv*
for adding, removing, renaming individual files, respectively, and then
*git commit* to finalize the commit. Carefully check all pending
changes with *git status* before committing them. If you find doing
this on the command line too tedious, consider using a GUI, for example
the one included in git distributions written in Tk, i.e. use *git gui*
(on some Linux distributions it may be required to install an additional
package to use it).
After adding all files, the change set can be committed with some
useful message that explains the change.
.. parsed-literal::
$ git commit -m 'Finally updated the github tutorial'
After the commit, the changes can be pushed to the same branch on GitHub:
.. parsed-literal::
$ git push
Git will ask you for your user name and password on GitHub if you have
not configured anything. If your local branch is not present on GitHub yet,
it will ask you to add it by running
.. parsed-literal::
$ git push --set-upstream origin github-tutorial-update
If you correctly type your user name and
password, the feature branch should be added to your fork on GitHub.
If you want to make really sure you push to the right repository
(which is good practice), you can provide it explicitly:
.. parsed-literal::
$ git push origin
or using an explicit URL:
.. parsed-literal::
$ git push git@github.com:Pakketeretet2/lammps.git
----------
**Filing a pull request**
Up to this point in the tutorial, all changes were to *your* clones of
LAMMPS. Eventually, however, you want this feature to be included into
the official LAMMPS version. To do this, you will want to file a pull
request by clicking on the "New pull request" button:
.. image:: JPG/tutorial_new_pull_request.png
:align: center
Make sure that the current branch is set to the correct one, which, in
this case, is "github-tutorial-update". If done correctly, the only
changes you will see are those that were made on this branch.
This will open up a new window that lists changes made to the
repository. If you are just adding new files, there is not much to do,
but I suppose merge conflicts are to be resolved here if there are
changes in existing files. If all changes can automatically be merged,
green text at the top will say so and you can click the "Create pull
request" button, see image.
.. image:: JPG/tutorial_create_new_pull_request1.png
:align: center
Before creating the pull request, make sure the short title is accurate
and add a comment with details about your pull request. Here you write
what your modifications do and why they should be incorporated upstream.
Note the checkbox that says "Allow edits from maintainers".
This is checked by default checkbox (although in my version of Firefox, only the checkmark is visible):
.. image:: JPG/tutorial_edits_maintainers.png
:align: center
If it is checked, maintainers can immediately add their own edits to the
pull request. This helps the inclusion of your branch significantly, as
simple/trivial changes can be added directly to your pull request branch
by the LAMMPS maintainers. The alternative would be that they make
changes on their own version of the branch and file a reverse pull
request to you. Just leave this box checked unless you have a very good
reason not to.
Now just write some nice comments and click on "Create pull request".
.. image:: JPG/tutorial_create_new_pull_request2.png
:align: center
----------
**After filing a pull request**
.. note::
When you submit a pull request (or ask for a pull request) for the
first time, you will receive an invitation to become a LAMMPS project
collaborator. Please accept this invite as being a collaborator will
simplify certain administrative tasks and will probably speed up the
merging of your feature, too.
You will notice that after filing the pull request, some checks are
performed automatically:
.. image:: JPG/tutorial_automated_checks.png
:align: center
If all is fine, you will see this:
.. image:: JPG/tutorial_automated_checks_passed.png
:align: center
If any of the checks are failing, your pull request will not be
processed, as your changes may break compilation for certain
configurations or may not merge cleanly. It is your responsibility
to remove the reason(s) for the failed test(s). If you need help
with this, please contact the LAMMPS developers by adding a comment
explaining your problems with resolving the failed tests.
A few further interesting things (can) happen to pull requests before
they are included.
**Additional changes**
First of all, any additional changes you push into your branch in your
repository will automatically become part of the pull request:
.. image:: JPG/tutorial_additional_changes.png
:align: center
This means you can add changes that should be part of the feature after
filing the pull request, which is useful in case you have forgotten
them, or if a developer has requested that something needs to be changed
before the feature can be accepted into the official LAMMPS version.
After each push, the automated checks are run again.
**Labels**
LAMMPS developers may add labels to your pull request to assign it to
categories (mostly for bookkeeping purposes), but a few of them are
important: needs\_work, work\_in\_progress, test-for-regression, and
full-regression-test. The first two indicate, that your pull request
is not considered to be complete. With "needs\_work" the burden is on
exclusively on you; while "work\_in\_progress" can also mean, that a
LAMMPS developer may want to add changes. Please watch the comments
to the pull requests. The two "test" labels are used to trigger
extended tests before the code is merged. This is sometimes done by
LAMMPS developers, if they suspect that there may be some subtle
side effects from your changes. It is not done by default, because
those tests are very time consuming.
**Reviews**
As of Summer 2018, a pull request needs at least 1 approving review
from a LAMMPS developer with write access to the repository.
In case your changes touch code that certain developers are associated
with, they are auto-requested by the GitHub software. Those associations
are set in the file
`.github/CODEOWNERS <https://github.com/lammps/lammps/blob/master/.github/CODEOWNERS>`_
Thus if you want to be automatically notified to review when anybody
changes files or packages, that you have contributed to LAMMPS, you can
add suitable patterns to that file, or a LAMMPS developer may add you.
Otherwise, you can also manually request reviews from specific developers,
or LAMMPS developers - in their assessment of your pull request - may
determine who else should be reviewing your contribution and add that person.
Through reviews, LAMMPS developers also may request specific changes from you.
If those are not addressed, your pull requests cannot be merged.
**Assignees**
There is an assignee property for pull requests. If the request has not
been reviewed by any developer yet, it is not assigned to anyone. After
revision, a developer can choose to assign it to either a) you, b) a
LAMMPS developer (including him/herself) or c) Axel Kohlmeyer (akohlmey).
* Case a) happens if changes are required on your part
* Case b) means that at the moment, it is being tested and reviewed by a
LAMMPS developer with the expectation that some changes would be required.
After the review, the developer can choose to implement changes directly
or suggest them to you.
* Case c) means that the pull request has been assigned to the developer
overseeing the merging of pull requests into the master branch.
In this case, Axel assigned the tutorial to Steve:
.. image:: JPG/tutorial_steve_assignee.png
:align: center
**Edits from LAMMPS maintainers**
If you allowed edits from maintainers (the default), any LAMMPS
maintainer can add changes to your pull request. In this case, both
Axel and Richard made changes to the tutorial:
.. image:: JPG/tutorial_changes_others.png
:align: center
**Reverse pull requests**
Sometimes, however, you might not feel comfortable having other people
push changes into your own branch, or maybe the maintainers are not sure
their idea was the right one. In such a case, they can make changes,
reassign you as the assignee, and file a "reverse pull request", i.e.
file a pull request in your GitHub repository to include changes in the
branch, that you have submitted as a pull request yourself. In that
case, you can choose to merge their changes back into your branch,
possibly make additional changes or corrections and proceed from there.
It looks something like this:
.. image:: JPG/tutorial_reverse_pull_request.png
:align: center
For some reason, the highlighted button didn't work in my case, but I
can go to my own repository and merge the pull request from there:
.. image:: JPG/tutorial_reverse_pull_request2.png
:align: center
Be sure to check the changes to see if you agree with them by clicking
on the tab button:
.. image:: JPG/tutorial_reverse_pull_request3.png
:align: center
In this case, most of it is changes in the markup and a short rewrite of
Axel's explanation of the "git gui" and "git add" commands.
.. image:: JPG/tutorial_reverse_pull_request4.png
:align: center
Because the changes are OK with us, we are going to merge by clicking on
"Merge pull request". After a merge it looks like this:
.. image:: JPG/tutorial_reverse_pull_request5.png
:align: center
Now, since in the meantime our local text for the tutorial also changed,
we need to pull Axel's change back into our branch, and merge them:
.. parsed-literal::
$ git add Howto_github.txt
$ git add JPG/tutorial_reverse_pull_request\*.png
$ git commit -m "Updated text and images on reverse pull requests"
$ git pull
In this case, the merge was painless because git could auto-merge:
.. image:: JPG/tutorial_reverse_pull_request6.png
:align: center
With Axel's changes merged in and some final text updates, our feature
branch is now perfect as far as we are concerned, so we are going to
commit and push again:
.. parsed-literal::
$ git add Howto_github.txt
$ git add JPG/tutorial_reverse_pull_request6.png
$ git commit -m "Merged Axel's suggestions and updated text"
$ git push git@github.com:Pakketeretet2/lammps
This merge also shows up on the lammps GitHub page:
.. image:: JPG/tutorial_reverse_pull_request7.png
:align: center
----------
**After a merge**
When everything is fine, the feature branch is merged into the master branch:
.. image:: JPG/tutorial_merged.png
:align: center
Now one question remains: What to do with the feature branch that got
merged into upstream?
It is in principle safe to delete them from your own fork. This helps
keep it a bit more tidy. Note that you first have to switch to another
branch!
.. parsed-literal::
$ git checkout master
$ git pull master
$ git branch -d github-tutorial-update
If you do not pull first, it is not really a problem but git will warn
you at the next statement that you are deleting a local branch that
was not yet fully merged into HEAD. This is because git does not yet
know your branch just got merged into LAMMPS upstream. If you
first delete and then pull, everything should still be fine.
Finally, if you delete the branch locally, you might want to push this
to your remote(s) as well:
.. parsed-literal::
$ git push origin :github-tutorial-update
**Recent changes in the workflow**
Some changes to the workflow are not captured in this tutorial. For
example, in addition to the master branch, to which all new features
should be submitted, there is now also an "unstable" and a "stable"
branch; these have the same content as "master", but are only updated
after a patch release or stable release was made.
Furthermore, the naming of the patches now follow the pattern
"patch\_<Day><Month><Year>" to simplify comparisons between releases.
Finally, all patches and submissions are subject to automatic testing
and code checks to make sure they at the very least compile.
A discussion of the LAMMPS developer GitHub workflow can be found in the file
`doc/github-development-workflow.md <https://github.com/lammps/lammps/blob/master/doc/github-development-workflow.md>`_
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

55
doc/src/Howto_granular.rst Normal file
View File

@ -0,0 +1,55 @@
Granular models
===============
Granular system are composed of spherical particles with a diameter,
as opposed to point particles. This means they have an angular
velocity and torque can be imparted to them to cause them to rotate.
To run a simulation of a granular model, you will want to use
the following commands:
* :doc:`atom\_style sphere <atom_style>`
* :doc:`fix nve/sphere <fix_nve_sphere>`
* :doc:`fix gravity <fix_gravity>`
This compute
* :doc:`compute erotate/sphere <compute_erotate_sphere>`
calculates rotational kinetic energy which can be :doc:`output with thermodynamic info <Howto_output>`.
Use one of these 3 pair potentials, which compute forces and torques
between interacting pairs of particles:
* :doc:`pair\_style <pair_style>` gran/history
* :doc:`pair\_style <pair_style>` gran/no\_history
* :doc:`pair\_style <pair_style>` gran/hertzian
These commands implement fix options specific to granular systems:
* :doc:`fix freeze <fix_freeze>`
* :doc:`fix pour <fix_pour>`
* :doc:`fix viscous <fix_viscous>`
* :doc:`fix wall/gran <fix_wall_gran>`
The fix style *freeze* zeroes both the force and torque of frozen
atoms, and should be used for granular system instead of the fix style
*setforce*\ .
For computational efficiency, you can eliminate needless pairwise
computations between frozen atoms by using this command:
* :doc:`neigh\_modify <neigh_modify>` exclude
.. note::
By default, for 2d systems, granular particles are still modeled
as 3d spheres, not 2d discs (circles), meaning their moment of inertia
will be the same as in 3d. If you wish to model granular particles in
2d as 2d discs, see the note on this topic on the :doc:`Howto 2d <Howto_2d>`
doc page, where 2d simulations are discussed.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

86
doc/src/Howto_kappa.rst Normal file
View File

@ -0,0 +1,86 @@
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 <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 <Howto_thermostat>`, 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 <howto-Ikeshoji>` and
:ref:`Wirnsberger et al <howto-Wirnsberger>` for details of this idea. Note
that thermostatting fixes such as :doc:`fix nvt <fix_nh>`, :doc:`fix langevin <fix_langevin>`, and :doc:`fix temp/rescale <fix_temp_rescale>` store the cumulative energy they
add/subtract.
Alternatively, as a second method, the :doc:`fix heat <fix_heat>` or
:doc:`fix ehex <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 <fix_ave_chunk>` and :doc:`compute ke/atom <compute_ke_atom>` commands.
The third method is to perform a reverse non-equilibrium MD simulation
using the :doc:`fix thermal/conductivity <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 <fix_ave_chunk>` and :doc:`compute ke/atom <compute_ke_atom>` commands. The fix tallies the
cumulative energy transfer that it performs. See the :doc:`fix thermal/conductivity <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 <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 <fix_ave_correlate>` command to calculate the needed
auto-correlation. See the doc page for the :doc:`compute heat/flux <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

227
doc/src/Howto_library.rst Normal file
View File

@ -0,0 +1,227 @@
Library interface to LAMMPS
===========================
As described on the :doc:`Build basics <Build_basics>` doc page, LAMMPS
can be built as a library, so that it can be called by another code,
used in a :doc:`coupled manner <Howto_couple>` with other codes, or
driven through a :doc:`Python interface <Python_head>`.
All of these methodologies use a C-style interface to LAMMPS that is
provided in the files src/library.cpp and src/library.h. The
functions therein have a C-style argument list, but contain C++ code
you could write yourself in a C++ application that was invoking LAMMPS
directly. The C++ code in the functions illustrates how to invoke
internal LAMMPS operations. Note that LAMMPS classes are defined
within a LAMMPS namespace (LAMMPS\_NS) if you use them from another C++
application.
The examples/COUPLE and python/examples directories have example C++
and C and Python codes which show how a driver code can link to LAMMPS
as a library, run LAMMPS on a subset of processors, grab data from
LAMMPS, change it, and put it back into LAMMPS.
The file src/library.cpp contains the following functions for creating
and destroying an instance of LAMMPS and sending it commands to
execute. See the documentation in the src/library.cpp file for
details.
.. note::
You can write code for additional functions as needed to define
how your code talks to LAMMPS and add them to src/library.cpp and
src/library.h, as well as to the :doc:`Python interface <Python_head>`.
The added functions can access or change any internal LAMMPS data you
wish.
.. parsed-literal::
void lammps_open(int, char \*\*, MPI_Comm, void \*\*)
void lammps_open_no_mpi(int, char \*\*, void \*\*)
void lammps_close(void \*)
int lammps_version(void \*)
void lammps_file(void \*, char \*)
char \*lammps_command(void \*, char \*)
void lammps_commands_list(void \*, int, char \*\*)
void lammps_commands_string(void \*, char \*)
void lammps_free(void \*)
The lammps\_open() function is used to initialize LAMMPS, passing in a
list of strings as if they were :doc:`command-line arguments <Run_options>` when LAMMPS is run in stand-alone mode
from the command line, and a MPI communicator for LAMMPS to run under.
It returns a ptr to the LAMMPS object that is created, and which is
used in subsequent library calls. The lammps\_open() function can be
called multiple times, to create multiple instances of LAMMPS.
LAMMPS will run on the set of processors in the communicator. This
means the calling code can run LAMMPS on all or a subset of
processors. For example, a wrapper script might decide to alternate
between LAMMPS and another code, allowing them both to run on all the
processors. Or it might allocate half the processors to LAMMPS and
half to the other code and run both codes simultaneously before
syncing them up periodically. Or it might instantiate multiple
instances of LAMMPS to perform different calculations.
The lammps\_open\_no\_mpi() function is similar except that no MPI
communicator is passed from the caller. Instead, MPI\_COMM\_WORLD is
used to instantiate LAMMPS, and MPI is initialized if necessary.
The lammps\_close() function is used to shut down an instance of LAMMPS
and free all its memory.
The lammps\_version() function can be used to determined the specific
version of the underlying LAMMPS code. This is particularly useful
when loading LAMMPS as a shared library via dlopen(). The code using
the library interface can than use this information to adapt to
changes to the LAMMPS command syntax between versions. The returned
LAMMPS version code is an integer (e.g. 2 Sep 2015 results in
20150902) that grows with every new LAMMPS version.
The lammps\_file(), lammps\_command(), lammps\_commands\_list(), and
lammps\_commands\_string() functions are used to pass one or more
commands to LAMMPS to execute, the same as if they were coming from an
input script.
Via these functions, the calling code can read or generate a series of
LAMMPS commands one or multiple at a time and pass it through the library
interface to setup a problem and then run it in stages. The caller
can interleave the command function calls with operations it performs,
calls to extract information from or set information within LAMMPS, or
calls to another code's library.
The lammps\_file() function passes the filename of an input script.
The lammps\_command() function passes a single command as a string.
The lammps\_commands\_list() function passes multiple commands in a
char\*\* list. In both lammps\_command() and lammps\_commands\_list(),
individual commands may or may not have a trailing newline. The
lammps\_commands\_string() function passes multiple commands
concatenated into one long string, separated by newline characters.
In both lammps\_commands\_list() and lammps\_commands\_string(), a single
command can be spread across multiple lines, if the last printable
character of all but the last line is "&", the same as if the lines
appeared in an input script.
The lammps\_free() function is a clean-up function to free memory that
the library allocated previously via other function calls. See
comments in src/library.cpp file for which other functions need this
clean-up.
The file src/library.cpp also contains these functions for extracting
information from LAMMPS and setting value within LAMMPS. Again, see
the documentation in the src/library.cpp file for details, including
which quantities can be queried by name:
.. parsed-literal::
int lammps_extract_setting(void \*, char \*)
void \*lammps_extract_global(void \*, char \*)
void lammps_extract_box(void \*, double \*, double \*,
double \*, double \*, double \*, int \*, int \*)
void \*lammps_extract_atom(void \*, char \*)
void \*lammps_extract_compute(void \*, char \*, int, int)
void \*lammps_extract_fix(void \*, char \*, int, int, int, int)
void \*lammps_extract_variable(void \*, char \*, char \*)
The extract\_setting() function returns info on the size
of data types (e.g. 32-bit or 64-bit atom IDs) used
by the LAMMPS executable (a compile-time choice).
The other extract functions return a pointer to various global or
per-atom quantities stored in LAMMPS or to values calculated by a
compute, fix, or variable. The pointer returned by the
extract\_global() function can be used as a permanent reference to a
value which may change. For the extract\_atom() method, see the
extract() method in the src/atom.cpp file for a list of valid per-atom
properties. New names could easily be added if the property you want
is not listed. For the other extract functions, the underlying
storage may be reallocated as LAMMPS runs, so you need to re-call the
function to assure a current pointer or returned value(s).
.. parsed-literal::
double lammps_get_thermo(void \*, char \*)
int lammps_get_natoms(void \*)
int lammps_set_variable(void \*, char \*, char \*)
void lammps_reset_box(void \*, double \*, double \*, double, double, double)
The lammps\_get\_thermo() function returns the current value of a thermo
keyword as a double precision value.
The lammps\_get\_natoms() function returns the total number of atoms in
the system and can be used by the caller to allocate memory for the
lammps\_gather\_atoms() and lammps\_scatter\_atoms() functions.
The lammps\_set\_variable() function can set an existing string-style
variable to a new string value, so that subsequent LAMMPS commands can
access the variable.
The lammps\_reset\_box() function resets the size and shape of the
simulation box, e.g. as part of restoring a previously extracted and
saved state of a simulation.
.. parsed-literal::
void lammps_gather_atoms(void \*, char \*, int, int, void \*)
void lammps_gather_atoms_concat(void \*, char \*, int, int, void \*)
void lammps_gather_atoms_subset(void \*, char \*, int, int, int, int \*, void \*)
void lammps_scatter_atoms(void \*, char \*, int, int, void \*)
void lammps_scatter_atoms_subset(void \*, char \*, int, int, int, int \*, void \*)
The gather functions collect peratom info of the requested type (atom
coords, atom types, forces, etc) from all processors, and returns the
same vector of values to each calling processor. The scatter
functions do the inverse. They distribute a vector of peratom values,
passed by all calling processors, to individual atoms, which may be
owned by different processors.
.. warning::
These functions are not compatible with the
-DLAMMPS\_BIGBIG setting when compiling LAMMPS. Dummy functions
that result in an error message and abort will be substituted
instead of resulting in random crashes and memory corruption.
The lammps\_gather\_atoms() function does this for all N atoms in the
system, ordered by atom ID, from 1 to N. The
lammps\_gather\_atoms\_concat() function does it for all N atoms, but
simply concatenates the subset of atoms owned by each processor. The
resulting vector is not ordered by atom ID. Atom IDs can be requested
by the same function if the caller needs to know the ordering. The
lammps\_gather\_subset() function allows the caller to request values
for only a subset of atoms (identified by ID).
For all 3 gather function, per-atom image flags can be retrieved in 2 ways.
If the count is specified as 1, they are returned
in a packed format with all three image flags stored in a single integer.
If the count is specified as 3, the values are unpacked into xyz flags
by the library before returning them.
The lammps\_scatter\_atoms() function takes a list of values for all N
atoms in the system, ordered by atom ID, from 1 to N, and assigns
those values to each atom in the system. The
lammps\_scatter\_atoms\_subset() function takes a subset of IDs as an
argument and only scatters those values to the owning atoms.
.. parsed-literal::
void lammps_create_atoms(void \*, int, tagint \*, int \*, double \*, double \*,
imageint \*, int)
The lammps\_create\_atoms() function takes a list of N atoms as input
with atom types and coords (required), an optionally atom IDs and
velocities and image flags. It uses the coords of each atom to assign
it as a new atom to the processor that owns it. This function is
useful to add atoms to a simulation or (in tandem with
lammps\_reset\_box()) to restore a previously extracted and saved state
of a simulation. Additional properties for the new atoms can then be
assigned via the lammps\_scatter\_atoms() or lammps\_extract\_atom()
functions.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

57
doc/src/Howto_manifold.rst Normal file
View File

@ -0,0 +1,57 @@
Manifolds (surfaces)
====================
**Overview:**
This doc page is not about a LAMMPS input script command, but about
manifolds, which are generalized surfaces, as defined and used by the
USER-MANIFOLD package, to track particle motion on the manifolds. See
the src/USER-MANIFOLD/README file for more details about the package
and its commands.
Below is a list of currently supported manifolds by the USER-MANIFOLD
package, their parameters and a short description of them. The
parameters listed here are in the same order as they should be passed
to the relevant fixes.
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| *manifold* | *parameters* | *equation* | *description* |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| cylinder | R | x\^2 + y\^2 - R\^2 = 0 | Cylinder along z-axis, axis going through (0,0,0) |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| cylinder\_dent | R l a | x\^2 + y\^2 - r(z)\^2 = 0, r(x) = R if \| z \| > l, r(z) = R - a\*(1 + cos(z/l))/2 otherwise | A cylinder with a dent around z = 0 |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| dumbbell | a A B c | -( x\^2 + y\^2 ) + (a\^2 - z\^2/c\^2) \* ( 1 + (A\*sin(B\*z\^2))\^4) = 0 | A dumbbell |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| ellipsoid | a b c | (x/a)\^2 + (y/b)\^2 + (z/c)\^2 = 0 | An ellipsoid |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| gaussian\_bump | A l rc1 rc2 | if( x < rc1) -z + A \* exp( -x\^2 / (2 l\^2) ); else if( x < rc2 ) -z + a + b\*x + c\*x\^2 + d\*x\^3; else z | A Gaussian bump at x = y = 0, smoothly tapered to a flat plane z = 0. |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| plane | a b c x0 y0 z0 | a\*(x-x0) + b\*(y-y0) + c\*(z-z0) = 0 | A plane with normal (a,b,c) going through point (x0,y0,z0) |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| plane\_wiggle | a w | z - a\*sin(w\*x) = 0 | A plane with a sinusoidal modulation on z along x. |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| sphere | R | x\^2 + y\^2 + z\^2 - R\^2 = 0 | A sphere of radius R |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| supersphere | R q | \| x \|\^q + \| y \|\^q + \| z \|\^q - R\^q = 0 | A supersphere of hyperradius R |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| spine | a, A, B, B2, c | -(x\^2 + y\^2) + (a\^2 - z\^2/f(z)\^2)\*(1 + (A\*sin(g(z)\*z\^2))\^4), f(z) = c if z > 0, 1 otherwise; g(z) = B if z > 0, B2 otherwise | An approximation to a dendritic spine |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| spine\_two | a, A, B, B2, c | -(x\^2 + y\^2) + (a\^2 - z\^2/f(z)\^2)\*(1 + (A\*sin(g(z)\*z\^2))\^2), f(z) = c if z > 0, 1 otherwise; g(z) = B if z > 0, B2 otherwise | Another approximation to a dendritic spine |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| thylakoid | wB LB lB | Various, see :ref:`(Paquay) <Paquay1>` | A model grana thylakoid consisting of two block-like compartments connected by a bridge of width wB, length LB and taper length lB |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
| torus | R r | (R - sqrt( x\^2 + y\^2 ) )\^2 + z\^2 - r\^2 | A torus with large radius R and small radius r, centered on (0,0,0) |
+----------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+
.. _Paquay1:
**(Paquay)** Paquay and Kusters, Biophys. J., 110, 6, (2016).
preprint available at `arXiv:1411.3019 <http://arxiv.org/abs/1411.3019/>`_.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

103
doc/src/Howto_multiple.rst Normal file
View File

@ -0,0 +1,103 @@
Run multiple simulations from one input script
==============================================
This can be done in several ways. See the documentation for
individual commands for more details on how these examples work.
If "multiple simulations" means continue a previous simulation for
more timesteps, then you simply use the :doc:`run <run>` command
multiple times. For example, this script
.. parsed-literal::
units lj
atom_style atomic
read_data data.lj
run 10000
run 10000
run 10000
run 10000
run 10000
would run 5 successive simulations of the same system for a total of
50,000 timesteps.
If you wish to run totally different simulations, one after the other,
the :doc:`clear <clear>` command can be used in between them to
re-initialize LAMMPS. For example, this script
.. parsed-literal::
units lj
atom_style atomic
read_data data.lj
run 10000
clear
units lj
atom_style atomic
read_data data.lj.new
run 10000
would run 2 independent simulations, one after the other.
For large numbers of independent simulations, you can use
:doc:`variables <variable>` and the :doc:`next <next>` and
:doc:`jump <jump>` commands to loop over the same input script
multiple times with different settings. For example, this
script, named in.polymer
.. parsed-literal::
variable d index run1 run2 run3 run4 run5 run6 run7 run8
shell cd $d
read_data data.polymer
run 10000
shell cd ..
clear
next d
jump in.polymer
would run 8 simulations in different directories, using a data.polymer
file in each directory. The same concept could be used to run the
same system at 8 different temperatures, using a temperature variable
and storing the output in different log and dump files, for example
.. parsed-literal::
variable a loop 8
variable t index 0.8 0.85 0.9 0.95 1.0 1.05 1.1 1.15
log log.$a
read data.polymer
velocity all create $t 352839
fix 1 all nvt $t $t 100.0
dump 1 all atom 1000 dump.$a
run 100000
clear
next t
next a
jump in.polymer
All of the above examples work whether you are running on 1 or
multiple processors, but assumed you are running LAMMPS on a single
partition of processors. LAMMPS can be run on multiple partitions via
the :doc:`-partition command-line switch <Run_options>`.
In the last 2 examples, if LAMMPS were run on 3 partitions, the same
scripts could be used if the "index" and "loop" variables were
replaced with *universe*\ -style variables, as described in the
:doc:`variable <variable>` command. Also, the "next t" and "next a"
commands would need to be replaced with a single "next a t" command.
With these modifications, the 8 simulations of each script would run
on the 3 partitions one after the other until all were finished.
Initially, 3 simulations would be started simultaneously, one on each
partition. When one finished, that partition would then start
the 4th simulation, and so forth, until all 8 were completed.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

60
doc/src/Howto_nemd.rst Normal file
View File

@ -0,0 +1,60 @@
NEMD simulations
================
Non-equilibrium molecular dynamics or NEMD simulations are typically
used to measure a fluid's rheological properties such as viscosity.
In LAMMPS, such simulations can be performed by first setting up a
non-orthogonal simulation box (see the preceding Howto section).
A shear strain can be applied to the simulation box at a desired
strain rate by using the :doc:`fix deform <fix_deform>` command. The
:doc:`fix nvt/sllod <fix_nvt_sllod>` command can be used to thermostat
the sheared fluid and integrate the SLLOD equations of motion for the
system. Fix nvt/sllod uses :doc:`compute temp/deform <compute_temp_deform>` to compute a thermal temperature
by subtracting out the streaming velocity of the shearing atoms. The
velocity profile or other properties of the fluid can be monitored via
the :doc:`fix ave/chunk <fix_ave_chunk>` command.
.. note::
A recent (2017) book by :ref:`(Daivis and Todd) <Daivis-nemd>`
discusses use of the SLLOD method and non-equilibrium MD (NEMD)
thermostatting generally, for both simple and complex fluids,
e.g. molecular systems. The latter can be tricky to do correctly.
As discussed in the previous section on non-orthogonal simulation
boxes, the amount of tilt or skew that can be applied is limited by
LAMMPS for computational efficiency to be 1/2 of the parallel box
length. However, :doc:`fix deform <fix_deform>` can continuously strain
a box by an arbitrary amount. As discussed in the :doc:`fix deform <fix_deform>` command, when the tilt value reaches a limit,
the box is flipped to the opposite limit which is an equivalent tiling
of periodic space. The strain rate can then continue to change as
before. In a long NEMD simulation these box re-shaping events may
occur many times.
In a NEMD simulation, the "remap" option of :doc:`fix deform <fix_deform>` should be set to "remap v", since that is what
:doc:`fix nvt/sllod <fix_nvt_sllod>` assumes to generate a velocity
profile consistent with the applied shear strain rate.
An alternative method for calculating viscosities is provided via the
:doc:`fix viscosity <fix_viscosity>` command.
NEMD simulations can also be used to measure transport properties of a fluid
through a pore or channel. Simulations of steady-state flow can be performed
using the :doc:`fix flow/gauss <fix_flow_gauss>` command.
----------
.. _Daivis-nemd:
**(Daivis and Todd)** Daivis and Todd, Nonequilibrium Molecular Dynamics (book),
Cambridge University Press, https://doi.org/10.1017/9781139017848, (2017).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

349
doc/src/Howto_output.rst Normal file
View File

@ -0,0 +1,349 @@
Output from LAMMPS (thermo, dumps, computes, fixes, variables)
==============================================================
There are four basic kinds of LAMMPS output:
* :doc:`Thermodynamic output <thermo_style>`, which is a list
of quantities printed every few timesteps to the screen and logfile.
* :doc:`Dump files <dump>`, which contain snapshots of atoms and various
per-atom values and are written at a specified frequency.
* Certain fixes can output user-specified quantities to files: :doc:`fix ave/time <fix_ave_time>` for time averaging, :doc:`fix ave/chunk <fix_ave_chunk>` for spatial or other averaging, and :doc:`fix print <fix_print>` for single-line output of
:doc:`variables <variable>`. Fix print can also output to the
screen.
* :doc:`Restart files <restart>`.
A simulation prints one set of thermodynamic output and (optionally)
restart files. It can generate any number of dump files and fix
output files, depending on what :doc:`dump <dump>` and :doc:`fix <fix>`
commands you specify.
As discussed below, LAMMPS gives you a variety of ways to determine
what quantities are computed and printed when the thermodynamics,
dump, or fix commands listed above perform output. Throughout this
discussion, note that users can also :doc:`add their own computes and fixes to LAMMPS <Modify>` which can then generate values that can then be
output with these commands.
The following sub-sections discuss different LAMMPS command related
to output and the kind of data they operate on and produce:
* :ref:`Global/per-atom/local data <global>`
* :ref:`Scalar/vector/array data <scalar>`
* :ref:`Thermodynamic output <thermo>`
* :ref:`Dump file output <dump>`
* :ref:`Fixes that write output files <fixoutput>`
* :ref:`Computes that process output quantities <computeoutput>`
* :ref:`Fixes that process output quantities <fixprocoutput>`
* :ref:`Computes that generate values to output <compute>`
* :ref:`Fixes that generate values to output <fix>`
* :ref:`Variables that generate values to output <variable>`
* :ref:`Summary table of output options and data flow between commands <table>`
.. _global:
Global/per-atom/local data
---------------------------------------
Various output-related commands work with three different styles of
data: global, per-atom, or local. A global datum is one or more
system-wide values, e.g. the temperature of the system. A per-atom
datum is one or more values per atom, e.g. the kinetic energy of each
atom. Local datums are calculated by each processor based on the
atoms it owns, but there may be zero or more per atom, e.g. a list of
bond distances.
.. _scalar:
Scalar/vector/array data
-------------------------------------
Global, per-atom, and local datums can each come in three kinds: a
single scalar value, a vector of values, or a 2d array of values. The
doc page for a "compute" or "fix" or "variable" that generates data
will specify both the style and kind of data it produces, e.g. a
per-atom vector.
When a quantity is accessed, as in many of the output commands
discussed below, it can be referenced via the following bracket
notation, where ID in this case is the ID of a compute. The leading
"c\_" would be replaced by "f\_" for a fix, or "v\_" for a variable:
+-------------+--------------------------------------------+
| c\_ID | entire scalar, vector, or array |
+-------------+--------------------------------------------+
| c\_ID[I] | one element of vector, one column of array |
+-------------+--------------------------------------------+
| c\_ID[I][J] | one element of array |
+-------------+--------------------------------------------+
In other words, using one bracket reduces the dimension of the data
once (vector -> scalar, array -> vector). Using two brackets reduces
the dimension twice (array -> scalar). Thus a command that uses
scalar values as input can typically also process elements of a vector
or array.
.. _thermo:
Thermodynamic output
---------------------------------
The frequency and format of thermodynamic output is set by the
:doc:`thermo <thermo>`, :doc:`thermo\_style <thermo_style>`, and
:doc:`thermo\_modify <thermo_modify>` commands. The
:doc:`thermo\_style <thermo_style>` command also specifies what values
are calculated and written out. Pre-defined keywords can be specified
(e.g. press, etotal, etc). Three additional kinds of keywords can
also be specified (c\_ID, f\_ID, v\_name), where a :doc:`compute <compute>`
or :doc:`fix <fix>` or :doc:`variable <variable>` provides the value to be
output. In each case, the compute, fix, or variable must generate
global values for input to the :doc:`thermo\_style custom <dump>`
command.
Note that thermodynamic output values can be "extensive" or
"intensive". The former scale with the number of atoms in the system
(e.g. total energy), the latter do not (e.g. temperature). The
setting for :doc:`thermo\_modify norm <thermo_modify>` determines whether
extensive quantities are normalized or not. Computes and fixes
produce either extensive or intensive values; see their individual doc
pages for details. :doc:`Equal-style variables <variable>` produce only
intensive values; you can include a division by "natoms" in the
formula if desired, to make an extensive calculation produce an
intensive result.
.. _dump:
Dump file output
---------------------------
Dump file output is specified by the :doc:`dump <dump>` and
:doc:`dump\_modify <dump_modify>` commands. There are several
pre-defined formats (dump atom, dump xtc, etc).
There is also a :doc:`dump custom <dump>` format where the user
specifies what values are output with each atom. Pre-defined atom
attributes can be specified (id, x, fx, etc). Three additional kinds
of keywords can also be specified (c\_ID, f\_ID, v\_name), where a
:doc:`compute <compute>` or :doc:`fix <fix>` or :doc:`variable <variable>`
provides the values to be output. In each case, the compute, fix, or
variable must generate per-atom values for input to the :doc:`dump custom <dump>` command.
There is also a :doc:`dump local <dump>` format where the user specifies
what local values to output. A pre-defined index keyword can be
specified to enumerate the local values. Two additional kinds of
keywords can also be specified (c\_ID, f\_ID), where a
:doc:`compute <compute>` or :doc:`fix <fix>` or :doc:`variable <variable>`
provides the values to be output. In each case, the compute or fix
must generate local values for input to the :doc:`dump local <dump>`
command.
.. _fixoutput:
Fixes that write output files
---------------------------------------------
Several fixes take various quantities as input and can write output
files: :doc:`fix ave/time <fix_ave_time>`, :doc:`fix ave/chunk <fix_ave_chunk>`, :doc:`fix ave/histo <fix_ave_histo>`,
:doc:`fix ave/correlate <fix_ave_correlate>`, and :doc:`fix print <fix_print>`.
The :doc:`fix ave/time <fix_ave_time>` command enables direct output to
a file and/or time-averaging of global scalars or vectors. The user
specifies one or more quantities as input. These can be global
:doc:`compute <compute>` values, global :doc:`fix <fix>` values, or
:doc:`variables <variable>` of any style except the atom style which
produces per-atom values. Since a variable can refer to keywords used
by the :doc:`thermo\_style custom <thermo_style>` command (like temp or
press) and individual per-atom values, a wide variety of quantities
can be time averaged and/or output in this way. If the inputs are one
or more scalar values, then the fix generate a global scalar or vector
of output. If the inputs are one or more vector values, then the fix
generates a global vector or array of output. The time-averaged
output of this fix can also be used as input to other output commands.
The :doc:`fix ave/chunk <fix_ave_chunk>` command enables direct output
to a file of chunk-averaged per-atom quantities like those output in
dump files. Chunks can represent spatial bins or other collections of
atoms, e.g. individual molecules. The per-atom quantities can be atom
density (mass or number) or atom attributes such as position,
velocity, force. They can also be per-atom quantities calculated by a
:doc:`compute <compute>`, by a :doc:`fix <fix>`, or by an atom-style
:doc:`variable <variable>`. The chunk-averaged output of this fix can
also be used as input to other output commands.
The :doc:`fix ave/histo <fix_ave_histo>` command enables direct output
to a file of histogrammed quantities, which can be global or per-atom
or local quantities. The histogram output of this fix can also be
used as input to other output commands.
The :doc:`fix ave/correlate <fix_ave_correlate>` command enables direct
output to a file of time-correlated quantities, which can be global
values. The correlation matrix output of this fix can also be used as
input to other output commands.
The :doc:`fix print <fix_print>` command can generate a line of output
written to the screen and log file or to a separate file, periodically
during a running simulation. The line can contain one or more
:doc:`variable <variable>` values for any style variable except the
vector or atom styles). As explained above, variables themselves can
contain references to global values generated by :doc:`thermodynamic keywords <thermo_style>`, :doc:`computes <compute>`,
:doc:`fixes <fix>`, or other :doc:`variables <variable>`, or to per-atom
values for a specific atom. Thus the :doc:`fix print <fix_print>`
command is a means to output a wide variety of quantities separate
from normal thermodynamic or dump file output.
.. _computeoutput:
Computes that process output quantities
-----------------------------------------------------------
The :doc:`compute reduce <compute_reduce>` and :doc:`compute reduce/region <compute_reduce>` commands take one or more per-atom
or local vector quantities as inputs and "reduce" them (sum, min, max,
ave) to scalar quantities. These are produced as output values which
can be used as input to other output commands.
The :doc:`compute slice <compute_slice>` command take one or more global
vector or array quantities as inputs and extracts a subset of their
values to create a new vector or array. These are produced as output
values which can be used as input to other output commands.
The :doc:`compute property/atom <compute_property_atom>` command takes a
list of one or more pre-defined atom attributes (id, x, fx, etc) and
stores the values in a per-atom vector or array. These are produced
as output values which can be used as input to other output commands.
The list of atom attributes is the same as for the :doc:`dump custom <dump>` command.
The :doc:`compute property/local <compute_property_local>` command takes
a list of one or more pre-defined local attributes (bond info, angle
info, etc) and stores the values in a local vector or array. These
are produced as output values which can be used as input to other
output commands.
.. _fixprocoutput:
Fixes that process output quantities
--------------------------------------------------------
The :doc:`fix vector <fix_vector>` command can create global vectors as
output from global scalars as input, accumulating them one element at
a time.
The :doc:`fix ave/atom <fix_ave_atom>` command performs time-averaging
of per-atom vectors. The per-atom quantities can be atom attributes
such as position, velocity, force. They can also be per-atom
quantities calculated by a :doc:`compute <compute>`, by a
:doc:`fix <fix>`, or by an atom-style :doc:`variable <variable>`. The
time-averaged per-atom output of this fix can be used as input to
other output commands.
The :doc:`fix store/state <fix_store_state>` command can archive one or
more per-atom attributes at a particular time, so that the old values
can be used in a future calculation or output. The list of atom
attributes is the same as for the :doc:`dump custom <dump>` command,
including per-atom quantities calculated by a :doc:`compute <compute>`,
by a :doc:`fix <fix>`, or by an atom-style :doc:`variable <variable>`.
The output of this fix can be used as input to other output commands.
.. _compute:
Computes that generate values to output
-----------------------------------------------------
Every :doc:`compute <compute>` in LAMMPS produces either global or
per-atom or local values. The values can be scalars or vectors or
arrays of data. These values can be output using the other commands
described in this section. The doc page for each compute command
describes what it produces. Computes that produce per-atom or local
values have the word "atom" or "local" in their style name. Computes
without the word "atom" or "local" produce global values.
.. _fix:
Fixes that generate values to output
----------------------------------------------
Some :doc:`fixes <fix>` in LAMMPS produces either global or per-atom or
local values which can be accessed by other commands. The values can
be scalars or vectors or arrays of data. These values can be output
using the other commands described in this section. The doc page for
each fix command tells whether it produces any output quantities and
describes them.
.. _variable:
Variables that generate values to output
-------------------------------------------------------
:doc:`Variables <variable>` defined in an input script can store one or
more strings. But equal-style, vector-style, and atom-style or
atomfile-style variables generate a global scalar value, global vector
or values, or a per-atom vector, respectively, when accessed. The
formulas used to define these variables can contain references to the
thermodynamic keywords and to global and per-atom data generated by
computes, fixes, and other variables. The values generated by
variables can be used as input to and thus output by the other
commands described in this section.
.. _table:
Summary table of output options and data flow between commands
--------------------------------------------------------------------------
This table summarizes the various commands that can be used for
generating output from LAMMPS. Each command produces output data of
some kind and/or writes data to a file. Most of the commands can take
data from other commands as input. Thus you can link many of these
commands together in pipeline form, where data produced by one command
is used as input to another command and eventually written to the
screen or to a file. Note that to hook two commands together the
output and input data types must match, e.g. global/per-atom/local
data and scalar/vector/array data.
Also note that, as described above, when a command takes a scalar as
input, that could be an element of a vector or array. Likewise a
vector input could be a column of an array.
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| Command | Input | Output |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`thermo\_style custom <thermo_style>` | global scalars | screen, log file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`dump custom <dump>` | per-atom vectors | dump file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`dump local <dump>` | local vectors | dump file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix print <fix_print>` | global scalar from variable | screen, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`print <print>` | global scalar from variable | screen |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`computes <compute>` | N/A | global/per-atom/local scalar/vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fixes <fix>` | N/A | global/per-atom/local scalar/vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`variables <variable>` | global scalars and vectors, per-atom vectors | global scalar and vector, per-atom vector |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`compute reduce <compute_reduce>` | per-atom/local vectors | global scalar/vector |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`compute slice <compute_slice>` | global vectors/arrays | global vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`compute property/atom <compute_property_atom>` | per-atom vectors | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`compute property/local <compute_property_local>` | local vectors | local vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix vector <fix_vector>` | global scalars | global vector |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/atom <fix_ave_atom>` | per-atom vectors | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/time <fix_ave_time>` | global scalars/vectors | global scalar/vector/array, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/chunk <fix_ave_chunk>` | per-atom vectors | global array, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/histo <fix_ave_histo>` | global/per-atom/local scalars and vectors | global array, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/correlate <fix_ave_correlate>` | global scalars | global array, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix store/state <fix_store_state>` | per-atom vectors | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

78
doc/src/Howto_polarizable.rst Normal file
View File

@ -0,0 +1,78 @@
Polarizable models
==================
In polarizable force fields the charge distributions in molecules and
materials respond to their electrostatic environments. Polarizable
systems can be simulated in LAMMPS using three methods:
* the fluctuating charge method, implemented in the :doc:`QEQ <fix_qeq>`
package,
* the adiabatic core-shell method, implemented in the
:doc:`CORESHELL <Howto_coreshell>` package,
* the thermalized Drude dipole method, implemented in the
:doc:`USER-DRUDE <Howto_drude>` package.
The fluctuating charge method calculates instantaneous charges on
interacting atoms based on the electronegativity equalization
principle. It is implemented in the :doc:`fix qeq <fix_qeq>` which is
available in several variants. It is a relatively efficient technique
since no additional particles are introduced. This method allows for
charge transfer between molecules or atom groups. However, because the
charges are located at the interaction sites, off-plane components of
polarization cannot be represented in planar molecules or atom groups.
The two other methods share the same basic idea: polarizable atoms are
split into one core atom and one satellite particle (called shell or
Drude particle) attached to it by a harmonic spring. Both atoms bear
a charge and they represent collectively an induced electric dipole.
These techniques are computationally more expensive than the QEq
method because of additional particles and bonds. These two
charge-on-spring methods differ in certain features, with the
core-shell model being normally used for ionic/crystalline materials,
whereas the so-called Drude model is normally used for molecular
systems and fluid states.
The core-shell model is applicable to crystalline materials where the
high symmetry around each site leads to stable trajectories of the
core-shell pairs. However, bonded atoms in molecules can be so close
that a core would interact too strongly or even capture the Drude
particle of a neighbor. The Drude dipole model is relatively more
complex in order to remedy this and other issues. Specifically, the
Drude model includes specific thermostatting of the core-Drude pairs
and short-range damping of the induced dipoles.
The three polarization methods can be implemented through a
self-consistent calculation of charges or induced dipoles at each
timestep. In the fluctuating charge scheme this is done by the matrix
inversion method in :doc:`fix qeq/point <fix_qeq>`, but for core-shell
or Drude-dipoles the relaxed-dipoles technique would require an slow
iterative procedure. These self-consistent solutions yield accurate
trajectories since the additional degrees of freedom representing
polarization are massless. An alternative is to attribute a mass to
the additional degrees of freedom and perform time integration using
an extended Lagrangian technique. For the fluctuating charge scheme
this is done by :doc:`fix qeq/dynamic <fix_qeq>`, and for the
charge-on-spring models by the methods outlined in the next two
sections. The assignment of masses to the additional degrees of
freedom can lead to unphysical trajectories if care is not exerted in
choosing the parameters of the polarizable models and the simulation
conditions.
In the core-shell model the vibration of the shells is kept faster
than the ionic vibrations to mimic the fast response of the
polarizable electrons. But in molecular systems thermalizing the
core-Drude pairs at temperatures comparable to the rest of the
simulation leads to several problems (kinetic energy transfer, too
short a timestep, etc.) In order to avoid these problems the relative
motion of the Drude particles with respect to their cores is kept
"cold" so the vibration of the core-Drude pairs is very slow,
approaching the self-consistent regime. In both models the
temperature is regulated using the velocities of the center of mass of
core+shell (or Drude) pairs, but in the Drude model the actual
relative core-Drude particle motion is thermostatted separately as
well.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

585
doc/src/Howto_pylammps.rst Normal file
View File

@ -0,0 +1,585 @@
PyLammps Tutorial
=================
.. contents::
Overview
--------
PyLammps is a Python wrapper class which can be created on its own or
use an existing lammps Python object. It creates a simpler,
Python-like interface to common LAMMPS functionality, in contrast to
the lammps.py wrapper on the C-style LAMMPS library interface which is
written using Python ctypes. The lammps.py wrapper is discussed on
the :doc:`Python library <Python_library>` doc page.
Unlike the flat ctypes interface, PyLammps exposes a discoverable API.
It no longer requires knowledge of the underlying C++ code
implementation. Finally, the IPyLammps wrapper builds on top of
PyLammps and adds some additional features for IPython integration
into IPython notebooks, e.g. for embedded visualization output from
dump/image.
Comparison of lammps and PyLammps interfaces
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
lammps.lammps
"""""""""""""
* uses C-Types
* direct memory access to native C++ data
* provides functions to send and receive data to LAMMPS
* requires knowledge of how LAMMPS internally works (C pointers, etc)
lammps.PyLammps
"""""""""""""""
* higher-level abstraction built on top of original C-Types interface
* manipulation of Python objects
* communication with LAMMPS is hidden from API user
* shorter, more concise Python
* better IPython integration, designed for quick prototyping
Quick Start
-----------
System-wide Installation
^^^^^^^^^^^^^^^^^^^^^^^^
Step 1: Building LAMMPS as a shared library
"""""""""""""""""""""""""""""""""""""""""""
To use LAMMPS inside of Python it has to be compiled as shared library. This
library is then loaded by the Python interface. In this example we enable the
MOLECULE package and compile LAMMPS with C++ exceptions, PNG, JPEG and FFMPEG
output support enabled.
Step 1a: For the CMake based build system, the steps are:
.. code-block:: bash
mkdir $LAMMPS_DIR/build-shared
cd $LAMMPS_DIR/build-shared
# MPI, PNG, Jpeg, FFMPEG are auto-detected
cmake ../cmake -DPKG_MOLECULE=yes -DLAMMPS_EXCEPTIONS=yes -DBUILD_LIB=yes -DBUILD_SHARED_LIBS=yes
make
Step 1b: For the legacy, make based build system, the steps are:
.. code-block:: bash
cd $LAMMPS_DIR/src
# add packages if necessary
make yes-MOLECULE
# compile shared library using Makefile
make mpi mode=shlib LMP_INC="-DLAMMPS_PNG -DLAMMPS_JPEG -DLAMMPS_FFMPEG -DLAMMPS_EXCEPTIONS" JPG_LIB="-lpng -ljpeg"
Step 2: Installing the LAMMPS Python package
""""""""""""""""""""""""""""""""""""""""""""
PyLammps is part of the lammps Python package. To install it simply install
that package into your current Python installation with:
.. code-block:: bash
make install-python
.. note::
Recompiling the shared library requires re-installing the Python package
Installation inside of a virtualenv
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can use virtualenv to create a custom Python environment specifically tuned
for your workflow.
Benefits of using a virtualenv
""""""""""""""""""""""""""""""
* isolation of your system Python installation from your development installation
* installation can happen in your user directory without root access (useful for HPC clusters)
* installing packages through pip allows you to get newer versions of packages than e.g., through apt-get or yum package managers (and without root access)
* you can even install specific old versions of a package if necessary
**Prerequisite (e.g. on Ubuntu)**
.. code-block:: bash
apt-get install python-virtualenv
Creating a virtualenv with lammps installed
"""""""""""""""""""""""""""""""""""""""""""
.. code-block:: bash
# create virtualenv named 'testing'
virtualenv $HOME/python/testing
# activate 'testing' environment
source $HOME/python/testing/bin/activate
Now configure and compile the LAMMPS shared library as outlined above.
When using CMake and the shared library has already been build, you
need to re-run CMake to update the location of the python executable
to the location in the virtual environment with:
.. code-block:: bash
cmake . -DPYTHON_EXECUTABLE=$(which python)
# install LAMMPS package in virtualenv
(testing) make install-python
# install other useful packages
(testing) pip install matplotlib jupyter mpi4py
...
# return to original shell
(testing) deactivate
Creating a new instance of PyLammps
-----------------------------------
To create a PyLammps object you need to first import the class from the lammps
module. By using the default constructor, a new *lammps* instance is created.
.. code-block:: Python
from lammps import PyLammps
L = PyLammps()
You can also initialize PyLammps on top of this existing *lammps* object:
.. code-block:: Python
from lammps import lammps, PyLammps
lmp = lammps()
L = PyLammps(ptr=lmp)
Commands
--------
Sending a LAMMPS command with the existing library interfaces is done using
the command method of the lammps object instance.
For instance, let's take the following LAMMPS command:
.. code-block:: LAMMPS
region box block 0 10 0 5 -0.5 0.5
In the original interface this command can be executed with the following
Python code if *L* was a lammps instance:
.. code-block:: Python
L.command("region box block 0 10 0 5 -0.5 0.5")
With the PyLammps interface, any command can be split up into arbitrary parts
separated by white-space, passed as individual arguments to a region method.
.. code-block:: Python
L.region("box block", 0, 10, 0, 5, -0.5, 0.5)
Note that each parameter is set as Python literal floating-point number. In the
PyLammps interface, each command takes an arbitrary parameter list and transparently
merges it to a single command string, separating individual parameters by white-space.
The benefit of this approach is avoiding redundant command calls and easier
parameterization. In the original interface parameterization needed to be done
manually by creating formatted strings.
.. code-block:: Python
L.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi))
In contrast, methods of PyLammps accept parameters directly and will convert
them automatically to a final command string.
.. code-block:: Python
L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi)
System state
------------
In addition to dispatching commands directly through the PyLammps object, it
also provides several properties which allow you to query the system state.
L.system
Is a dictionary describing the system such as the bounding box or number of atoms
L.system.xlo, L.system.xhi
bounding box limits along x-axis
L.system.ylo, L.system.yhi
bounding box limits along y-axis
L.system.zlo, L.system.zhi
bounding box limits along z-axis
L.communication
configuration of communication subsystem, such as the number of threads or processors
L.communication.nthreads
number of threads used by each LAMMPS process
L.communication.nprocs
number of MPI processes used by LAMMPS
L.fixes
List of fixes in the current system
L.computes
List of active computes in the current system
L.dump
List of active dumps in the current system
L.groups
List of groups present in the current system
Working with LAMMPS variables
-----------------------------
LAMMPS variables can be both defined and accessed via the PyLammps interface.
To define a variable you can use the :doc:`variable <variable>` command:
.. code-block:: Python
L.variable("a index 2")
A dictionary of all variables is returned by L.variables
you can access an individual variable by retrieving a variable object from the
L.variables dictionary by name
.. code-block:: Python
a = L.variables['a']
The variable value can then be easily read and written by accessing the value
property of this object.
.. code-block:: Python
print(a.value)
a.value = 4
Retrieving the value of an arbitrary LAMMPS expressions
-------------------------------------------------------
LAMMPS expressions can be immediately evaluated by using the eval method. The
passed string parameter can be any expression containing global thermo values,
variables, compute or fix data.
.. code-block:: Python
result = L.eval("ke") # kinetic energy
result = L.eval("pe") # potential energy
result = L.eval("v_t/2.0")
Accessing atom data
-------------------
All atoms in the current simulation can be accessed by using the L.atoms list.
Each element of this list is an object which exposes its properties (id, type,
position, velocity, force, etc.).
.. code-block:: Python
# access first atom
L.atoms[0].id
L.atoms[0].type
# access second atom
L.atoms[1].position
L.atoms[1].velocity
L.atoms[1].force
Some properties can also be used to set:
.. code-block:: Python
# set position in 2D simulation
L.atoms[0].position = (1.0, 0.0)
# set position in 3D simulation
L.atoms[0].position = (1.0, 0.0, 1.)
Evaluating thermo data
----------------------
Each simulation run usually produces thermo output based on system state,
computes, fixes or variables. The trajectories of these values can be queried
after a run via the L.runs list. This list contains a growing list of run data.
The first element is the output of the first run, the second element that of
the second run.
.. code-block:: Python
L.run(1000)
L.runs[0] # data of first 1000 time steps
L.run(1000)
L.runs[1] # data of second 1000 time steps
Each run contains a dictionary of all trajectories. Each trajectory is
accessible through its thermo name:
.. code-block:: Python
L.runs[0].step # list of time steps in first run
L.runs[0].ke # list of kinetic energy values in first run
Together with matplotlib plotting data out of LAMMPS becomes simple:
import matplotlib.plot as plt
.. code-block:: Python
steps = L.runs[0].step
ke = L.runs[0].ke
plt.plot(steps, ke)
Error handling with PyLammps
----------------------------
Compiling the shared library with C++ exception support provides a better error
handling experience. Without exceptions the LAMMPS code will terminate the
current Python process with an error message. C++ exceptions allow capturing
them on the C++ side and rethrowing them on the Python side. This way you
can handle LAMMPS errors through the Python exception handling mechanism.
.. warning::
Capturing a LAMMPS exception in Python can still mean that the
current LAMMPS process is in an illegal state and must be terminated. It is
advised to save your data and terminate the Python instance as quickly as
possible.
Using PyLammps in IPython notebooks and Jupyter
-----------------------------------------------
If the LAMMPS Python package is installed for the same Python interpreter as
IPython, you can use PyLammps directly inside of an IPython notebook inside of
Jupyter. Jupyter is a powerful integrated development environment (IDE) for
many dynamic languages like Python, Julia and others, which operates inside of
any web browser. Besides auto-completion and syntax highlighting it allows you
to create formatted documents using Markup, mathematical formulas, graphics and
animations intermixed with executable Python code. It is a great format for
tutorials and showcasing your latest research.
To launch an instance of Jupyter simply run the following command inside your
Python environment (this assumes you followed the Quick Start instructions):
.. code-block:: bash
jupyter notebook
IPyLammps Examples
------------------
Examples of IPython notebooks can be found in the python/examples/pylammps
sub-directory. To open these notebooks launch *jupyter notebook* inside this
directory and navigate to one of them. If you compiled and installed
a LAMMPS shared library with exceptions, PNG, JPEG and FFMPEG support
you should be able to rerun all of these notebooks.
Validating a dihedral potential
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This example showcases how an IPython Notebook can be used to compare a simple
LAMMPS simulation of a harmonic dihedral potential to its analytical solution.
Four atoms are placed in the simulation and the dihedral potential is applied on
them using a datafile. Then one of the atoms is rotated along the central axis by
setting its position from Python, which changes the dihedral angle.
.. code-block:: Python
phi = [d \* math.pi / 180 for d in range(360)]
pos = [(1.0, math.cos(p), math.sin(p)) for p in phi]
pe = []
for p in pos:
L.atoms[3].position = p
L.run(0)
pe.append(L.eval("pe"))
By evaluating the potential energy for each position we can verify that
trajectory with the analytical formula. To compare both solutions, we plot
both trajectories over each other using matplotlib, which embeds the generated
plot inside the IPython notebook.
.. image:: JPG/pylammps_dihedral.jpg
:align: center
Running a Monte Carlo relaxation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This second example shows how to use PyLammps to create a 2D Monte Carlo Relaxation
simulation, computing and plotting energy terms and even embedding video output.
Initially, a 2D system is created in a state with minimal energy.
.. image:: JPG/pylammps_mc_minimum.jpg
:align: center
It is then disordered by moving each atom by a random delta.
.. code-block:: Python
random.seed(27848)
deltaperturb = 0.2
for i in range(L.system.natoms):
x, y = L.atoms[i].position
dx = deltaperturb \* random.uniform(-1, 1)
dy = deltaperturb \* random.uniform(-1, 1)
L.atoms[i].position = (x+dx, y+dy)
L.run(0)
.. image:: JPG/pylammps_mc_disordered.jpg
:align: center
Finally, the Monte Carlo algorithm is implemented in Python. It continuously
moves random atoms by a random delta and only accepts certain moves.
.. code-block:: Python
estart = L.eval("pe")
elast = estart
naccept = 0
energies = [estart]
niterations = 3000
deltamove = 0.1
kT = 0.05
natoms = L.system.natoms
for i in range(niterations):
iatom = random.randrange(0, natoms)
current_atom = L.atoms[iatom]
x0, y0 = current_atom.position
dx = deltamove \* random.uniform(-1, 1)
dy = deltamove \* random.uniform(-1, 1)
current_atom.position = (x0+dx, y0+dy)
L.run(1, "pre no post no")
e = L.eval("pe")
energies.append(e)
if e <= elast:
naccept += 1
elast = e
elif random.random() <= math.exp(natoms\*(elast-e)/kT):
naccept += 1
elast = e
else:
current_atom.position = (x0, y0)
The energies of each iteration are collected in a Python list and finally plotted using matplotlib.
.. image:: JPG/pylammps_mc_energies_plot.jpg
:align: center
The IPython notebook also shows how to use dump commands and embed video files
inside of the IPython notebook.
Using PyLammps and mpi4py (Experimental)
----------------------------------------
PyLammps can be run in parallel using mpi4py. This python package can be installed using
.. code-block:: bash
pip install mpi4py
The following is a short example which reads in an existing LAMMPS input file and
executes it in parallel. You can find in.melt in the examples/melt folder.
.. code-block:: Python
from mpi4py import MPI
from lammps import PyLammps
L = PyLammps()
L.file("in.melt")
if MPI.COMM_WORLD.rank == 0:
print("Potential energy: ", L.eval("pe"))
MPI.Finalize()
To run this script (melt.py) in parallel using 4 MPI processes we invoke the
following mpirun command:
.. code-block:: bash
mpirun -np 4 python melt.py
.. warning::
Any command must be executed by all MPI processes. However, evaluations and querying the system state is only available on rank 0.
Feedback and Contributing
-------------------------
If you find this Python interface useful, please feel free to provide feedback
and ideas on how to improve it to Richard Berger (richard.berger@temple.edu). We also
want to encourage people to write tutorial style IPython notebooks showcasing LAMMPS usage
and maybe their latest research results.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

481
doc/src/Howto_pylammps.txt
View File

@ -1,481 +0,0 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Commands_all.html)
:line
PyLammps Tutorial :h3
<!-- RST
.. contents::
END_RST -->
Overview :h4
PyLammps is a Python wrapper class which can be created on its own or
use an existing lammps Python object. It creates a simpler,
Python-like interface to common LAMMPS functionality, in contrast to
the lammps.py wrapper on the C-style LAMMPS library interface which is
written using Python ctypes. The lammps.py wrapper is discussed on
the "Python library"_Python_library.html doc page.
Unlike the flat ctypes interface, PyLammps exposes a discoverable API.
It no longer requires knowledge of the underlying C++ code
implementation. Finally, the IPyLammps wrapper builds on top of
PyLammps and adds some additional features for IPython integration
into IPython notebooks, e.g. for embedded visualization output from
dump/image.
Comparison of lammps and PyLammps interfaces :h5
lammps.lammps :h6
uses C-Types
direct memory access to native C++ data
provides functions to send and receive data to LAMMPS
requires knowledge of how LAMMPS internally works (C pointers, etc) :ul
lammps.PyLammps :h6
higher-level abstraction built on top of original C-Types interface
manipulation of Python objects
communication with LAMMPS is hidden from API user
shorter, more concise Python
better IPython integration, designed for quick prototyping :ul
Quick Start :h4
System-wide Installation :h5
Step 1: Building LAMMPS as a shared library :h6
To use LAMMPS inside of Python it has to be compiled as shared library. This
library is then loaded by the Python interface. In this example we enable the
MOLECULE package and compile LAMMPS with C++ exceptions, PNG, JPEG and FFMPEG
output support enabled.
Step 1a: For the CMake based build system, the steps are:
mkdir $LAMMPS_DIR/build-shared
cd $LAMMPS_DIR/build-shared :pre
# MPI, PNG, Jpeg, FFMPEG are auto-detected
cmake ../cmake -DPKG_MOLECULE=yes -DLAMMPS_EXCEPTIONS=yes -DBUILD_LIB=yes -DBUILD_SHARED_LIBS=yes
make :pre
Step 1b: For the legacy, make based build system, the steps are:
cd $LAMMPS_DIR/src :pre
# add packages if necessary
make yes-MOLECULE :pre
# compile shared library using Makefile
make mpi mode=shlib LMP_INC="-DLAMMPS_PNG -DLAMMPS_JPEG -DLAMMPS_FFMPEG -DLAMMPS_EXCEPTIONS" JPG_LIB="-lpng -ljpeg" :pre
Step 2: Installing the LAMMPS Python package :h6
PyLammps is part of the lammps Python package. To install it simply install
that package into your current Python installation with:
make install-python :pre
NOTE: Recompiling the shared library requires re-installing the Python package
Installation inside of a virtualenv :h5
You can use virtualenv to create a custom Python environment specifically tuned
for your workflow.
Benefits of using a virtualenv :h6
isolation of your system Python installation from your development installation
installation can happen in your user directory without root access (useful for HPC clusters)
installing packages through pip allows you to get newer versions of packages than e.g., through apt-get or yum package managers (and without root access)
you can even install specific old versions of a package if necessary :ul
[Prerequisite (e.g. on Ubuntu)]
apt-get install python-virtualenv :pre
Creating a virtualenv with lammps installed :h6
# create virtualenv named 'testing'
virtualenv $HOME/python/testing :pre
# activate 'testing' environment
source $HOME/python/testing/bin/activate :pre
Now configure and compile the LAMMPS shared library as outlined above.
When using CMake and the shared library has already been build, you
need to re-run CMake to update the location of the python executable
to the location in the virtual environment with:
cmake . -DPYTHON_EXECUTABLE=$(which python) :pre
# install LAMMPS package in virtualenv
(testing) make install-python :pre
# install other useful packages
(testing) pip install matplotlib jupyter mpi4py :pre
... :pre
# return to original shell
(testing) deactivate :pre
Creating a new instance of PyLammps :h4
To create a PyLammps object you need to first import the class from the lammps
module. By using the default constructor, a new {lammps} instance is created.
from lammps import PyLammps
L = PyLammps() :pre
You can also initialize PyLammps on top of this existing {lammps} object:
from lammps import lammps, PyLammps
lmp = lammps()
L = PyLammps(ptr=lmp) :pre
Commands :h4
Sending a LAMMPS command with the existing library interfaces is done using
the command method of the lammps object instance.
For instance, let's take the following LAMMPS command:
region box block 0 10 0 5 -0.5 0.5 :pre
In the original interface this command can be executed with the following
Python code if {L} was a lammps instance:
L.command("region box block 0 10 0 5 -0.5 0.5") :pre
With the PyLammps interface, any command can be split up into arbitrary parts
separated by white-space, passed as individual arguments to a region method.
L.region("box block", 0, 10, 0, 5, -0.5, 0.5) :pre
Note that each parameter is set as Python literal floating-point number. In the
PyLammps interface, each command takes an arbitrary parameter list and transparently
merges it to a single command string, separating individual parameters by white-space.
The benefit of this approach is avoiding redundant command calls and easier
parameterization. In the original interface parameterization needed to be done
manually by creating formatted strings.
L.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi)) :pre
In contrast, methods of PyLammps accept parameters directly and will convert
them automatically to a final command string.
L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi) :pre
System state :h4
In addition to dispatching commands directly through the PyLammps object, it
also provides several properties which allow you to query the system state.
:dlb
L.system :dt
Is a dictionary describing the system such as the bounding box or number of atoms :dd
L.system.xlo, L.system.xhi :dt
bounding box limits along x-axis :dd
L.system.ylo, L.system.yhi :dt
bounding box limits along y-axis :dd
L.system.zlo, L.system.zhi :dt
bounding box limits along z-axis :dd
L.communication :dt
configuration of communication subsystem, such as the number of threads or processors :dd
L.communication.nthreads :dt
number of threads used by each LAMMPS process :dd
L.communication.nprocs :dt
number of MPI processes used by LAMMPS :dd
L.fixes :dt
List of fixes in the current system :dd
L.computes :dt
List of active computes in the current system :dd
L.dump :dt
List of active dumps in the current system :dd
L.groups :dt
List of groups present in the current system :dd
:dle
Working with LAMMPS variables :h4
LAMMPS variables can be both defined and accessed via the PyLammps interface.
To define a variable you can use the "variable"_variable.html command:
L.variable("a index 2") :pre
A dictionary of all variables is returned by L.variables
you can access an individual variable by retrieving a variable object from the
L.variables dictionary by name
a = L.variables\['a'\] :pre
The variable value can then be easily read and written by accessing the value
property of this object.
print(a.value)
a.value = 4 :pre
Retrieving the value of an arbitrary LAMMPS expressions :h4
LAMMPS expressions can be immediately evaluated by using the eval method. The
passed string parameter can be any expression containing global thermo values,
variables, compute or fix data.
result = L.eval("ke") # kinetic energy
result = L.eval("pe") # potential energy :pre
result = L.eval("v_t/2.0") :pre
Accessing atom data :h4
All atoms in the current simulation can be accessed by using the L.atoms list.
Each element of this list is an object which exposes its properties (id, type,
position, velocity, force, etc.).
# access first atom
L.atoms\[0\].id
L.atoms\[0\].type :pre
# access second atom
L.atoms\[1\].position
L.atoms\[1\].velocity
L.atoms\[1\].force :pre
Some properties can also be used to set:
# set position in 2D simulation
L.atoms\[0\].position = (1.0, 0.0) :pre
# set position in 3D simulation
L.atoms\[0\].position = (1.0, 0.0, 1.) :pre
Evaluating thermo data :h4
Each simulation run usually produces thermo output based on system state,
computes, fixes or variables. The trajectories of these values can be queried
after a run via the L.runs list. This list contains a growing list of run data.
The first element is the output of the first run, the second element that of
the second run.
L.run(1000)
L.runs\[0\] # data of first 1000 time steps :pre
L.run(1000)
L.runs\[1\] # data of second 1000 time steps :pre
Each run contains a dictionary of all trajectories. Each trajectory is
accessible through its thermo name:
L.runs\[0\].step # list of time steps in first run
L.runs\[0\].ke # list of kinetic energy values in first run :pre
Together with matplotlib plotting data out of LAMMPS becomes simple:
import matplotlib.plot as plt
steps = L.runs\[0\].step
ke = L.runs\[0\].ke
plt.plot(steps, ke) :pre
Error handling with PyLammps :h4
Compiling the shared library with C++ exception support provides a better error
handling experience. Without exceptions the LAMMPS code will terminate the
current Python process with an error message. C++ exceptions allow capturing
them on the C++ side and rethrowing them on the Python side. This way you
can handle LAMMPS errors through the Python exception handling mechanism.
IMPORTANT NOTE: Capturing a LAMMPS exception in Python can still mean that the
current LAMMPS process is in an illegal state and must be terminated. It is
advised to save your data and terminate the Python instance as quickly as
possible.
Using PyLammps in IPython notebooks and Jupyter :h4
If the LAMMPS Python package is installed for the same Python interpreter as
IPython, you can use PyLammps directly inside of an IPython notebook inside of
Jupyter. Jupyter is a powerful integrated development environment (IDE) for
many dynamic languages like Python, Julia and others, which operates inside of
any web browser. Besides auto-completion and syntax highlighting it allows you
to create formatted documents using Markup, mathematical formulas, graphics and
animations intermixed with executable Python code. It is a great format for
tutorials and showcasing your latest research.
To launch an instance of Jupyter simply run the following command inside your
Python environment (this assumes you followed the Quick Start instructions):
jupyter notebook :pre
IPyLammps Examples :h4
Examples of IPython notebooks can be found in the python/examples/pylammps
sub-directory. To open these notebooks launch {jupyter notebook} inside this
directory and navigate to one of them. If you compiled and installed
a LAMMPS shared library with exceptions, PNG, JPEG and FFMPEG support
you should be able to rerun all of these notebooks.
Validating a dihedral potential :h5
This example showcases how an IPython Notebook can be used to compare a simple
LAMMPS simulation of a harmonic dihedral potential to its analytical solution.
Four atoms are placed in the simulation and the dihedral potential is applied on
them using a datafile. Then one of the atoms is rotated along the central axis by
setting its position from Python, which changes the dihedral angle.
phi = \[d * math.pi / 180 for d in range(360)\] :pre
pos = \[(1.0, math.cos(p), math.sin(p)) for p in phi\] :pre
pe = \[\]
for p in pos:
L.atoms\[3\].position = p
L.run(0)
pe.append(L.eval("pe")) :pre
By evaluating the potential energy for each position we can verify that
trajectory with the analytical formula. To compare both solutions, we plot
both trajectories over each other using matplotlib, which embeds the generated
plot inside the IPython notebook.
:c,image(JPG/pylammps_dihedral.jpg)
Running a Monte Carlo relaxation :h5
This second example shows how to use PyLammps to create a 2D Monte Carlo Relaxation
simulation, computing and plotting energy terms and even embedding video output.
Initially, a 2D system is created in a state with minimal energy.
:c,image(JPG/pylammps_mc_minimum.jpg)
It is then disordered by moving each atom by a random delta.
random.seed(27848)
deltaperturb = 0.2 :pre
for i in range(L.system.natoms):
x, y = L.atoms\[i\].position
dx = deltaperturb * random.uniform(-1, 1)
dy = deltaperturb * random.uniform(-1, 1)
L.atoms\[i\].position = (x+dx, y+dy) :pre
L.run(0) :pre
:c,image(JPG/pylammps_mc_disordered.jpg)
Finally, the Monte Carlo algorithm is implemented in Python. It continuously
moves random atoms by a random delta and only accepts certain moves.
estart = L.eval("pe")
elast = estart :pre
naccept = 0
energies = \[estart\] :pre
niterations = 3000
deltamove = 0.1
kT = 0.05 :pre
natoms = L.system.natoms :pre
for i in range(niterations):
iatom = random.randrange(0, natoms)
current_atom = L.atoms\[iatom\] :pre
x0, y0 = current_atom.position :pre
dx = deltamove * random.uniform(-1, 1)
dy = deltamove * random.uniform(-1, 1) :pre
current_atom.position = (x0+dx, y0+dy) :pre
L.run(1, "pre no post no") :pre
e = L.eval("pe")
energies.append(e) :pre
if e <= elast:
naccept += 1
elast = e
elif random.random() <= math.exp(natoms*(elast-e)/kT):
naccept += 1
elast = e
else:
current_atom.position = (x0, y0) :pre
The energies of each iteration are collected in a Python list and finally plotted using matplotlib.
:c,image(JPG/pylammps_mc_energies_plot.jpg)
The IPython notebook also shows how to use dump commands and embed video files
inside of the IPython notebook.
Using PyLammps and mpi4py (Experimental) :h4
PyLammps can be run in parallel using mpi4py. This python package can be installed using
pip install mpi4py :pre
The following is a short example which reads in an existing LAMMPS input file and
executes it in parallel. You can find in.melt in the examples/melt folder.
from mpi4py import MPI
from lammps import PyLammps :pre
L = PyLammps()
L.file("in.melt") :pre
if MPI.COMM_WORLD.rank == 0:
print("Potential energy: ", L.eval("pe")) :pre
MPI.Finalize() :pre
To run this script (melt.py) in parallel using 4 MPI processes we invoke the
following mpirun command:
mpirun -np 4 python melt.py :pre
IMPORTANT NOTE: Any command must be executed by all MPI processes. However, evaluations and querying the system state is only available on rank 0.
Feedback and Contributing :h4
If you find this Python interface useful, please feel free to provide feedback
and ideas on how to improve it to Richard Berger (richard.berger@temple.edu). We also
want to encourage people to write tutorial style IPython notebooks showcasing LAMMPS usage
and maybe their latest research results.

60
doc/src/Howto_replica.rst Normal file
View File

@ -0,0 +1,60 @@
Multi-replica simulations
=========================
Several commands in LAMMPS run multi-replica simulations, meaning
that multiple instances (replicas) of your simulation are run
simultaneously, with small amounts of data exchanged between replicas
periodically.
These are the relevant commands:
* :doc:`neb <neb>` for nudged elastic band calculations
* :doc:`neb\_spin <neb_spin>` for magnetic nudged elastic band calculations
* :doc:`prd <prd>` for parallel replica dynamics
* :doc:`tad <tad>` for temperature accelerated dynamics
* :doc:`temper <temper>` for parallel tempering
* :doc:`fix pimd <fix_pimd>` for path-integral molecular dynamics (PIMD)
NEB is a method for finding transition states and barrier energies.
PRD and TAD are methods for performing accelerated dynamics to find
and perform infrequent events. Parallel tempering or replica exchange
runs different replicas at a series of temperature to facilitate
rare-event sampling.
These commands can only be used if LAMMPS was built with the REPLICA
package. See the :doc:`Build package <Build_package>` doc page for more
info.
PIMD runs different replicas whose individual particles are coupled
together by springs to model a system or ring-polymers.
This commands can only be used if LAMMPS was built with the USER-MISC
package. See the :doc:`Build package <Build_package>` doc page for more
info.
In all these cases, you must run with one or more processors per
replica. The processors assigned to each replica are determined at
run-time by using the :doc:`-partition command-line switch <Run_options>` to launch LAMMPS on multiple partitions,
which in this context are the same as replicas. E.g. these commands:
.. parsed-literal::
mpirun -np 16 lmp_linux -partition 8x2 -in in.temper
mpirun -np 8 lmp_linux -partition 8x1 -in in.neb
would each run 8 replicas, on either 16 or 8 processors. Note the use
of the :doc:`-in command-line switch <Run_options>` to specify the input
script which is required when running in multi-replica mode.
Also note that with MPI installed on a machine (e.g. your desktop),
you can run on more (virtual) processors than you have physical
processors. Thus the above commands could be run on a
single-processor (or few-processor) desktop so that you can run
a multi-replica simulation on more replicas than you have
physical processors.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

105
doc/src/Howto_restart.rst Normal file
View File

@ -0,0 +1,105 @@
Restart a simulation
====================
There are 3 ways to continue a long LAMMPS simulation. Multiple
:doc:`run <run>` commands can be used in the same input script. Each
run will continue from where the previous run left off. Or binary
restart files can be saved to disk using the :doc:`restart <restart>`
command. At a later time, these binary files can be read via a
:doc:`read\_restart <read_restart>` command in a new script. Or they can
be converted to text data files using the :doc:`-r command-line switch <Run_options>` and read by a :doc:`read\_data <read_data>`
command in a new script.
Here we give examples of 2 scripts that read either a binary restart
file or a converted data file and then issue a new run command to
continue where the previous run left off. They illustrate what
settings must be made in the new script. Details are discussed in the
documentation for the :doc:`read\_restart <read_restart>` and
:doc:`read\_data <read_data>` commands.
Look at the *in.chain* input script provided in the *bench* directory
of the LAMMPS distribution to see the original script that these 2
scripts are based on. If that script had the line
.. parsed-literal::
restart 50 tmp.restart
added to it, it would produce 2 binary restart files (tmp.restart.50
and tmp.restart.100) as it ran.
This script could be used to read the 1st restart file and re-run the
last 50 timesteps:
.. parsed-literal::
read_restart tmp.restart.50
neighbor 0.4 bin
neigh_modify every 1 delay 1
fix 1 all nve
fix 2 all langevin 1.0 1.0 10.0 904297
timestep 0.012
run 50
Note that the following commands do not need to be repeated because
their settings are included in the restart file: *units, atom\_style,
special\_bonds, pair\_style, bond\_style*. However these commands do
need to be used, since their settings are not in the restart file:
*neighbor, fix, timestep*\ .
If you actually use this script to perform a restarted run, you will
notice that the thermodynamic data match at step 50 (if you also put a
"thermo 50" command in the original script), but do not match at step
100. This is because the :doc:`fix langevin <fix_langevin>` command
uses random numbers in a way that does not allow for perfect restarts.
As an alternate approach, the restart file could be converted to a data
file as follows:
.. parsed-literal::
lmp_g++ -r tmp.restart.50 tmp.restart.data
Then, this script could be used to re-run the last 50 steps:
.. parsed-literal::
units lj
atom_style bond
pair_style lj/cut 1.12
pair_modify shift yes
bond_style fene
special_bonds 0.0 1.0 1.0
read_data tmp.restart.data
neighbor 0.4 bin
neigh_modify every 1 delay 1
fix 1 all nve
fix 2 all langevin 1.0 1.0 10.0 904297
timestep 0.012
reset_timestep 50
run 50
Note that nearly all the settings specified in the original *in.chain*
script must be repeated, except the *pair\_coeff* and *bond\_coeff*
commands since the new data file lists the force field coefficients.
Also, the :doc:`reset\_timestep <reset_timestep>` command is used to tell
LAMMPS the current timestep. This value is stored in restart files,
but not in data files.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

57
doc/src/Howto_spc.rst Normal file
View File

@ -0,0 +1,57 @@
SPC water model
===============
The SPC water model specifies a 3-site rigid water molecule with
charges and Lennard-Jones parameters assigned to each of the 3 atoms.
In LAMMPS the :doc:`fix shake <fix_shake>` command can be used to hold
the two O-H bonds and the H-O-H angle rigid. A bond style of
*harmonic* and an angle style of *harmonic* or *charmm* should also be
used.
These are the additional parameters (in real units) to set for O and H
atoms and the water molecule to run a rigid SPC model.
| O mass = 15.9994
| H mass = 1.008
| O charge = -0.820
| H charge = 0.410
| LJ epsilon of OO = 0.1553
| LJ sigma of OO = 3.166
| LJ epsilon, sigma of OH, HH = 0.0
| r0 of OH bond = 1.0
| theta of HOH angle = 109.47
|
Note that as originally proposed, the SPC model was run with a 9
Angstrom cutoff for both LJ and Coulombic terms. It can also be used
with long-range Coulombics (Ewald or PPPM in LAMMPS), without changing
any of the parameters above, though it becomes a different model in
that mode of usage.
The SPC/E (extended) water model is the same, except
the partial charge assignments change:
| O charge = -0.8476
| H charge = 0.4238
|
See the :ref:`(Berendsen) <howto-Berendsen>` reference for more details on both
the SPC and SPC/E models.
Wikipedia also has a nice article on `water models <http://en.wikipedia.org/wiki/Water_model>`_.
----------
.. _howto-Berendsen:
**(Berendsen)** Berendsen, Grigera, Straatsma, J Phys Chem, 91,
6269-6271 (1987).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

243
doc/src/Howto_spherical.rst Normal file
View File

@ -0,0 +1,243 @@
Finite-size spherical and aspherical particles
==============================================
Typical MD models treat atoms or particles as point masses. Sometimes
it is desirable to have a model with finite-size particles such as
spheroids or ellipsoids or generalized aspherical bodies. The
difference is that such particles have a moment of inertia, rotational
energy, and angular momentum. Rotation is induced by torque coming
from interactions with other particles.
LAMMPS has several options for running simulations with these kinds of
particles. The following aspects are discussed in turn:
* atom styles
* pair potentials
* time integration
* computes, thermodynamics, and dump output
* rigid bodies composed of finite-size particles
Example input scripts for these kinds of models are in the body,
colloid, dipole, ellipse, line, peri, pour, and tri directories of the
:doc:`examples directory <Examples>` in the LAMMPS distribution.
Atom styles
-----------
There are several :doc:`atom styles <atom_style>` that allow for
definition of finite-size particles: sphere, dipole, ellipsoid, line,
tri, peri, and body.
The sphere style defines particles that are spheroids and each
particle can have a unique diameter and mass (or density). These
particles store an angular velocity (omega) and can be acted upon by
torque. The "set" command can be used to modify the diameter and mass
of individual particles, after then are created.
The dipole style does not actually define finite-size particles, but
is often used in conjunction with spherical particles, via a command
like
.. parsed-literal::
atom_style hybrid sphere dipole
This is because when dipoles interact with each other, they induce
torques, and a particle must be finite-size (i.e. have a moment of
inertia) in order to respond and rotate. See the :doc:`atom\_style dipole <atom_style>` command for details. The "set" command can be
used to modify the orientation and length of the dipole moment of
individual particles, after then are created.
The ellipsoid style defines particles that are ellipsoids and thus can
be aspherical. Each particle has a shape, specified by 3 diameters,
and mass (or density). These particles store an angular momentum and
their orientation (quaternion), and can be acted upon by torque. They
do not store an angular velocity (omega), which can be in a different
direction than angular momentum, rather they compute it as needed.
The "set" command can be used to modify the diameter, orientation, and
mass of individual particles, after then are created. It also has a
brief explanation of what quaternions are.
The line style defines line segment particles with two end points and
a mass (or density). They can be used in 2d simulations, and they can
be joined together to form rigid bodies which represent arbitrary
polygons.
The tri style defines triangular particles with three corner points
and a mass (or density). They can be used in 3d simulations, and they
can be joined together to form rigid bodies which represent arbitrary
particles with a triangulated surface.
The peri style is used with :doc:`Peridynamic models <pair_peri>` and
defines particles as having a volume, that is used internally in the
:doc:`pair\_style peri <pair_peri>` potentials.
The body style allows for definition of particles which can represent
complex entities, such as surface meshes of discrete points,
collections of sub-particles, deformable objects, etc. The body style
is discussed in more detail on the :doc:`Howto body <Howto_body>` doc
page.
Note that if one of these atom styles is used (or multiple styles via
the :doc:`atom\_style hybrid <atom_style>` command), not all particles in
the system are required to be finite-size or aspherical.
For example, in the ellipsoid style, if the 3 shape parameters are set
to the same value, the particle will be a sphere rather than an
ellipsoid. If the 3 shape parameters are all set to 0.0 or if the
diameter is set to 0.0, it will be a point particle. In the line or
tri style, if the lineflag or triflag is specified as 0, then it
will be a point particle.
Some of the pair styles used to compute pairwise interactions between
finite-size particles also compute the correct interaction with point
particles as well, e.g. the interaction between a point particle and a
finite-size particle or between two point particles. If necessary,
:doc:`pair\_style hybrid <pair_hybrid>` can be used to insure the correct
interactions are computed for the appropriate style of interactions.
Likewise, using groups to partition particles (ellipsoids versus
spheres versus point particles) will allow you to use the appropriate
time integrators and temperature computations for each class of
particles. See the doc pages for various commands for details.
Also note that for :doc:`2d simulations <dimension>`, atom styles sphere
and ellipsoid still use 3d particles, rather than as circular disks or
ellipses. This means they have the same moment of inertia as the 3d
object. When temperature is computed, the correct degrees of freedom
are used for rotation in a 2d versus 3d system.
Pair potentials
---------------
When a system with finite-size particles is defined, the particles
will only rotate and experience torque if the force field computes
such interactions. These are the various :doc:`pair styles <pair_style>` that generate torque:
* :doc:`pair\_style gran/history <pair_gran>`
* :doc:`pair\_style gran/hertzian <pair_gran>`
* :doc:`pair\_style gran/no\_history <pair_gran>`
* :doc:`pair\_style dipole/cut <pair_dipole>`
* :doc:`pair\_style gayberne <pair_gayberne>`
* :doc:`pair\_style resquared <pair_resquared>`
* :doc:`pair\_style brownian <pair_brownian>`
* :doc:`pair\_style lubricate <pair_lubricate>`
* :doc:`pair\_style line/lj <pair_line_lj>`
* :doc:`pair\_style tri/lj <pair_tri_lj>`
* :doc:`pair\_style body/nparticle <pair_body_nparticle>`
The granular pair styles are used with spherical particles. The
dipole pair style is used with the dipole atom style, which could be
applied to spherical or ellipsoidal particles. The GayBerne and
REsquared potentials require ellipsoidal particles, though they will
also work if the 3 shape parameters are the same (a sphere). The
Brownian and lubrication potentials are used with spherical particles.
The line, tri, and body potentials are used with line segment,
triangular, and body particles respectively.
Time integration
----------------
There are several fixes that perform time integration on finite-size
spherical particles, meaning the integrators update the rotational
orientation and angular velocity or angular momentum of the particles:
* :doc:`fix nve/sphere <fix_nve_sphere>`
* :doc:`fix nvt/sphere <fix_nvt_sphere>`
* :doc:`fix npt/sphere <fix_npt_sphere>`
Likewise, there are 3 fixes that perform time integration on
ellipsoidal particles:
* :doc:`fix nve/asphere <fix_nve_asphere>`
* :doc:`fix nvt/asphere <fix_nvt_asphere>`
* :doc:`fix npt/asphere <fix_npt_asphere>`
The advantage of these fixes is that those which thermostat the
particles include the rotational degrees of freedom in the temperature
calculation and thermostatting. The :doc:`fix langevin <fix_langevin>`
command can also be used with its *omgea* or *angmom* options to
thermostat the rotational degrees of freedom for spherical or
ellipsoidal particles. Other thermostatting fixes only operate on the
translational kinetic energy of finite-size particles.
These fixes perform constant NVE time integration on line segment,
triangular, and body particles:
* :doc:`fix nve/line <fix_nve_line>`
* :doc:`fix nve/tri <fix_nve_tri>`
* :doc:`fix nve/body <fix_nve_body>`
Note that for mixtures of point and finite-size particles, these
integration fixes can only be used with :doc:`groups <group>` which
contain finite-size particles.
Computes, thermodynamics, and dump output
-----------------------------------------
There are several computes that calculate the temperature or
rotational energy of spherical or ellipsoidal particles:
* :doc:`compute temp/sphere <compute_temp_sphere>`
* :doc:`compute temp/asphere <compute_temp_asphere>`
* :doc:`compute erotate/sphere <compute_erotate_sphere>`
* :doc:`compute erotate/asphere <compute_erotate_asphere>`
These include rotational degrees of freedom in their computation. If
you wish the thermodynamic output of temperature or pressure to use
one of these computes (e.g. for a system entirely composed of
finite-size particles), then the compute can be defined and the
:doc:`thermo\_modify <thermo_modify>` command used. Note that by default
thermodynamic quantities will be calculated with a temperature that
only includes translational degrees of freedom. See the
:doc:`thermo\_style <thermo_style>` command for details.
These commands can be used to output various attributes of finite-size
particles:
* :doc:`dump custom <dump>`
* :doc:`compute property/atom <compute_property_atom>`
* :doc:`dump local <dump>`
* :doc:`compute body/local <compute_body_local>`
Attributes include the dipole moment, the angular velocity, the
angular momentum, the quaternion, the torque, the end-point and
corner-point coordinates (for line and tri particles), and
sub-particle attributes of body particles.
Rigid bodies composed of finite-size particles
----------------------------------------------
The :doc:`fix rigid <fix_rigid>` command treats a collection of
particles as a rigid body, computes its inertia tensor, sums the total
force and torque on the rigid body each timestep due to forces on its
constituent particles, and integrates the motion of the rigid body.
If any of the constituent particles of a rigid body are finite-size
particles (spheres or ellipsoids or line segments or triangles), then
their contribution to the inertia tensor of the body is different than
if they were point particles. This means the rotational dynamics of
the rigid body will be different. Thus a model of a dimer is
different if the dimer consists of two point masses versus two
spheroids, even if the two particles have the same mass. Finite-size
particles that experience torque due to their interaction with other
particles will also impart that torque to a rigid body they are part
of.
See the "fix rigid" command for example of complex rigid-body models
it is possible to define in LAMMPS.
Note that the :doc:`fix shake <fix_shake>` command can also be used to
treat 2, 3, or 4 particles as a rigid body, but it always assumes the
particles are point masses.
Also note that body particles cannot be modeled with the :doc:`fix rigid <fix_rigid>` command. Body particles are treated by LAMMPS
as single particles, though they can store internal state, such as a
list of sub-particles. Individual body particles are typically treated
as rigid bodies, and their motion integrated with a command like :doc:`fix nve/body <fix_nve_body>`. Interactions between pairs of body
particles are computed via a command like :doc:`pair\_style body/nparticle <pair_body_nparticle>`.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

73
doc/src/Howto_spins.rst Normal file
View File

@ -0,0 +1,73 @@
Magnetic spins
==============
The magnetic spin simulations are enabled by the SPIN package, whose
implementation is detailed in :ref:`Tranchida <Tranchida>`.
The model represents the simulation of atomic magnetic spins coupled
to lattice vibrations. The dynamics of those magnetic spins can be used
to simulate a broad range a phenomena related to magneto-elasticity, or
or to study the influence of defects on the magnetic properties of
materials.
The magnetic spins are interacting with each others and with the
lattice via pair interactions. Typically, the magnetic exchange
interaction can be defined using the
:doc:`pair/spin/exchange <pair_spin_exchange>` command. This exchange
applies a magnetic torque to a given spin, considering the orientation
of its neighboring spins and their relative distances.
It also applies a force on the atoms as a function of the spin
orientations and their associated inter-atomic distances.
The command :doc:`fix precession/spin <fix_precession_spin>` allows to
apply a constant magnetic torque on all the spins in the system. This
torque can be an external magnetic field (Zeeman interaction), or an
uniaxial magnetic anisotropy.
A Langevin thermostat can be applied to those magnetic spins using
:doc:`fix langevin/spin <fix_langevin_spin>`. Typically, this thermostat
can be coupled to another Langevin thermostat applied to the atoms
using :doc:`fix langevin <fix_langevin>` in order to simulate
thermostatted spin-lattice systems.
The magnetic Gilbert damping can also be applied using :doc:`fix langevin/spin <fix_langevin_spin>`. It allows to either dissipate
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 <fix_setforce>` 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 <fix_nve_spin>` can be used to
perform a symplectic integration of the combined dynamics of spins
and atomic motions.
The minimization style :doc:`min/spin <min_spin>` can be applied
to the spins to perform a minimization of the spin configuration.
All the computed magnetic properties can be output by two main
commands. The first one is :doc:`compute spin <compute_spin>`, that
enables to evaluate magnetic averaged quantities, such as the total
magnetization of the system along x, y, or z, the spin temperature, or
the magnetic energy. The second command is :doc:`compute property/atom <compute_property_atom>`. It enables to output all the
per atom magnetic quantities. Typically, the orientation of a given
magnetic spin, or the magnetic force acting on this spin.
----------
.. _Tranchida:
**(Tranchida)** Tranchida, Plimpton, Thibaudeau and Thompson,
Journal of Computational Physics, 372, 406-425, (2018).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

38
doc/src/Howto_temperature.rst Normal file
View File

@ -0,0 +1,38 @@
Calculate temperature
=====================
Temperature is computed as kinetic energy divided by some number of
degrees of freedom (and the Boltzmann constant). Since kinetic energy
is a function of particle velocity, there is often a need to
distinguish between a particle's advection velocity (due to some
aggregate motion of particles) and its thermal velocity. The sum of
the two is the particle's total velocity, but the latter is often what
is wanted to compute a temperature.
LAMMPS has several options for computing temperatures, any of which
can be used in :doc:`thermostatting <Howto_thermostat>` and
:doc:`barostatting <Howto_barostat>`. These :doc:`compute commands <compute>` calculate temperature:
* :doc:`compute temp <compute_temp>`
* :doc:`compute temp/sphere <compute_temp_sphere>`
* :doc:`compute temp/asphere <compute_temp_asphere>`
* :doc:`compute temp/com <compute_temp_com>`
* :doc:`compute temp/deform <compute_temp_deform>`
* :doc:`compute temp/partial <compute_temp_partial>`
* :doc:`compute temp/profile <compute_temp_profile>`
* :doc:`compute temp/ramp <compute_temp_ramp>`
* :doc:`compute temp/region <compute_temp_region>`
All but the first 3 calculate velocity biases directly (e.g. advection
velocities) that are removed when computing the thermal temperature.
:doc:`Compute temp/sphere <compute_temp_sphere>` and :doc:`compute temp/asphere <compute_temp_asphere>` compute kinetic energy for
finite-size particles that includes rotational degrees of freedom.
They both allow for velocity biases indirectly, via an optional extra
argument which is another temperature compute that subtracts a
velocity bias. This allows the translational velocity of spherical or
aspherical particles to be adjusted in prescribed ways.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

99
doc/src/Howto_thermostat.rst Normal file
View File

@ -0,0 +1,99 @@
Thermostats
===========
Thermostatting means controlling the temperature of particles in an MD
simulation. :doc:`Barostatting <Howto_barostat>` means controlling the
pressure. Since the pressure includes a kinetic component due to
particle velocities, both these operations require calculation of the
temperature. Typically a target temperature (T) and/or pressure (P)
is specified by the user, and the thermostat or barostat attempts to
equilibrate the system to the requested T and/or P.
Thermostatting in LAMMPS is performed by :doc:`fixes <fix>`, or in one
case by a pair style. Several thermostatting fixes are available:
Nose-Hoover (nvt), Berendsen, CSVR, Langevin, and direct rescaling
(temp/rescale). Dissipative particle dynamics (DPD) thermostatting
can be invoked via the *dpd/tstat* pair style:
* :doc:`fix nvt <fix_nh>`
* :doc:`fix nvt/sphere <fix_nvt_sphere>`
* :doc:`fix nvt/asphere <fix_nvt_asphere>`
* :doc:`fix nvt/sllod <fix_nvt_sllod>`
* :doc:`fix temp/berendsen <fix_temp_berendsen>`
* :doc:`fix temp/csvr <fix_temp_csvr>`
* :doc:`fix langevin <fix_langevin>`
* :doc:`fix temp/rescale <fix_temp_rescale>`
* :doc:`pair\_style dpd/tstat <pair_dpd>`
:doc:`Fix nvt <fix_nh>` only thermostats the translational velocity of
particles. :doc:`Fix nvt/sllod <fix_nvt_sllod>` also does this, except
that it subtracts out a velocity bias due to a deforming box and
integrates the SLLOD equations of motion. See the :doc:`Howto nemd <Howto_nemd>` doc page for further details. :doc:`Fix nvt/sphere <fix_nvt_sphere>` and :doc:`fix nvt/asphere <fix_nvt_asphere>` thermostat not only translation
velocities but also rotational velocities for spherical and aspherical
particles.
.. note::
A recent (2017) book by :ref:`(Daivis and Todd) <Daivis-thermostat>`
discusses use of the SLLOD method and non-equilibrium MD (NEMD)
thermostatting generally, for both simple and complex fluids,
e.g. molecular systems. The latter can be tricky to do correctly.
DPD thermostatting alters pairwise interactions in a manner analogous
to the per-particle thermostatting of :doc:`fix langevin <fix_langevin>`.
Any of the thermostatting fixes can use :doc:`temperature computes <Howto_thermostat>` that remove bias which has two
effects. First, the current calculated temperature, which is compared
to the requested target temperature, is calculated with the velocity
bias removed. Second, the thermostat adjusts only the thermal
temperature component of the particle's velocities, which are the
velocities with the bias removed. The removed bias is then added back
to the adjusted velocities. See the doc pages for the individual
fixes and for the :doc:`fix\_modify <fix_modify>` command for
instructions on how to assign a temperature compute to a
thermostatting fix. For example, you can apply a thermostat to only
the x and z components of velocity by using it in conjunction with
:doc:`compute temp/partial <compute_temp_partial>`. Of you could
thermostat only the thermal temperature of a streaming flow of
particles without affecting the streaming velocity, by using :doc:`compute temp/profile <compute_temp_profile>`.
.. note::
Only the nvt fixes perform time integration, meaning they update
the velocities and positions of particles due to forces and velocities
respectively. The other thermostat fixes only adjust velocities; they
do NOT perform time integration updates. Thus they should be used in
conjunction with a constant NVE integration fix such as these:
* :doc:`fix nve <fix_nve>`
* :doc:`fix nve/sphere <fix_nve_sphere>`
* :doc:`fix nve/asphere <fix_nve_asphere>`
Thermodynamic output, which can be setup via the
:doc:`thermo\_style <thermo_style>` command, often includes temperature
values. As explained on the doc page for the
:doc:`thermo\_style <thermo_style>` command, the default temperature is
setup by the thermo command itself. It is NOT the temperature
associated with any thermostatting fix you have defined or with any
compute you have defined that calculates a temperature. The doc pages
for the thermostatting fixes explain the ID of the temperature compute
they create. Thus if you want to view these temperatures, you need to
specify them explicitly via the :doc:`thermo\_style custom <thermo_style>` command. Or you can use the
:doc:`thermo\_modify <thermo_modify>` command to re-define what
temperature compute is used for default thermodynamic output.
----------
.. _Daivis-thermostat:
**(Daivis and Todd)** Daivis and Todd, Nonequilibrium Molecular Dynamics (book),
Cambridge University Press, https://doi.org/10.1017/9781139017848, (2017).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

81
doc/src/Howto_tip3p.rst Normal file
View File

@ -0,0 +1,81 @@
TIP3P water model
=================
The TIP3P water model as implemented in CHARMM
:ref:`(MacKerell) <howto-tip3p>` specifies a 3-site rigid water molecule with
charges and Lennard-Jones parameters assigned to each of the 3 atoms.
In LAMMPS the :doc:`fix shake <fix_shake>` command can be used to hold
the two O-H bonds and the H-O-H angle rigid. A bond style of
*harmonic* and an angle style of *harmonic* or *charmm* should also be
used.
These are the additional parameters (in real units) to set for O and H
atoms and the water molecule to run a rigid TIP3P-CHARMM model with a
cutoff. The K values can be used if a flexible TIP3P model (without
fix shake) is desired. If the LJ epsilon and sigma for HH and OH are
set to 0.0, it corresponds to the original 1983 TIP3P model
:ref:`(Jorgensen) <Jorgensen1>`.
| O mass = 15.9994
| H mass = 1.008
| O charge = -0.834
| H charge = 0.417
| LJ epsilon of OO = 0.1521
| LJ sigma of OO = 3.1507
| LJ epsilon of HH = 0.0460
| LJ sigma of HH = 0.4000
| LJ epsilon of OH = 0.0836
| LJ sigma of OH = 1.7753
| K of OH bond = 450
| r0 of OH bond = 0.9572
| K of HOH angle = 55
| theta of HOH angle = 104.52
|
These are the parameters to use for TIP3P with a long-range Coulombic
solver (e.g. Ewald or PPPM in LAMMPS), see :ref:`(Price) <Price1>` for
details:
| O mass = 15.9994
| H mass = 1.008
| O charge = -0.830
| H charge = 0.415
| LJ epsilon of OO = 0.102
| LJ sigma of OO = 3.188
| LJ epsilon, sigma of OH, HH = 0.0
| K of OH bond = 450
| r0 of OH bond = 0.9572
| K of HOH angle = 55
| theta of HOH angle = 104.52
|
Wikipedia also has a nice article on `water models <http://en.wikipedia.org/wiki/Water_model>`_.
----------
.. _howto-tip3p:
**(MacKerell)** MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field,
Fischer, Gao, Guo, Ha, et al, J Phys Chem, 102, 3586 (1998).
.. _Jorgensen1:
**(Jorgensen)** Jorgensen, Chandrasekhar, Madura, Impey, Klein, J Chem
Phys, 79, 926 (1983).
.. _Price1:
**(Price)** Price and Brooks, J Chem Phys, 121, 10096 (2004).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

116
doc/src/Howto_tip4p.rst Normal file
View File

@ -0,0 +1,116 @@
TIP4P water model
=================
The four-point TIP4P rigid water model extends the traditional
three-point TIP3P model by adding an additional site, usually
massless, where the charge associated with the oxygen atom is placed.
This site M is located at a fixed distance away from the oxygen along
the bisector of the HOH bond angle. A bond style of *harmonic* and an
angle style of *harmonic* or *charmm* should also be used.
A TIP4P model is run with LAMMPS using either this command
for a cutoff model:
:doc:`pair\_style lj/cut/tip4p/cut <pair_lj>`
or these two commands for a long-range model:
* :doc:`pair\_style lj/cut/tip4p/long <pair_lj>`
* :doc:`kspace\_style pppm/tip4p <kspace_style>`
For both models, the bond lengths and bond angles should be held fixed
using the :doc:`fix shake <fix_shake>` command.
These are the additional parameters (in real units) to set for O and H
atoms and the water molecule to run a rigid TIP4P model with a cutoff
:ref:`(Jorgensen) <Jorgensen5>`. Note that the OM distance is specified in
the :doc:`pair\_style <pair_style>` command, not as part of the pair
coefficients.
| O mass = 15.9994
| H mass = 1.008
| O charge = -1.040
| H charge = 0.520
| r0 of OH bond = 0.9572
| theta of HOH angle = 104.52
| OM distance = 0.15
| LJ epsilon of O-O = 0.1550
| LJ sigma of O-O = 3.1536
| LJ epsilon, sigma of OH, HH = 0.0
| Coulombic cutoff = 8.5
|
For the TIP4/Ice model (J Chem Phys, 122, 234511 (2005);
http://dx.doi.org/10.1063/1.1931662) these values can be used:
| O mass = 15.9994
| H mass = 1.008
| O charge = -1.1794
| H charge = 0.5897
| r0 of OH bond = 0.9572
| theta of HOH angle = 104.52
| OM distance = 0.1577
| LJ epsilon of O-O = 0.21084
| LJ sigma of O-O = 3.1668
| LJ epsilon, sigma of OH, HH = 0.0
| Coulombic cutoff = 8.5
|
For the TIP4P/2005 model (J Chem Phys, 123, 234505 (2005);
http://dx.doi.org/10.1063/1.2121687), these values can be used:
| O mass = 15.9994
| H mass = 1.008
| O charge = -1.1128
| H charge = 0.5564
| r0 of OH bond = 0.9572
| theta of HOH angle = 104.52
| OM distance = 0.1546
| LJ epsilon of O-O = 0.1852
| LJ sigma of O-O = 3.1589
| LJ epsilon, sigma of OH, HH = 0.0
| Coulombic cutoff = 8.5
|
These are the parameters to use for TIP4P with a long-range Coulombic
solver (e.g. Ewald or PPPM in LAMMPS):
| O mass = 15.9994
| H mass = 1.008
| O charge = -1.0484
| H charge = 0.5242
| r0 of OH bond = 0.9572
| theta of HOH angle = 104.52
| OM distance = 0.1250
| LJ epsilon of O-O = 0.16275
| LJ sigma of O-O = 3.16435
| LJ epsilon, sigma of OH, HH = 0.0
|
Note that the when using the TIP4P pair style, the neighbor list
cutoff for Coulomb interactions is effectively extended by a distance
2 \* (OM distance), to account for the offset distance of the
fictitious charges on O atoms in water molecules. Thus it is
typically best in an efficiency sense to use a LJ cutoff >= Coulomb
cutoff + 2\*(OM distance), to shrink the size of the neighbor list.
This leads to slightly larger cost for the long-range calculation, so
you can test the trade-off for your model. The OM distance and the LJ
and Coulombic cutoffs are set in the :doc:`pair\_style lj/cut/tip4p/long <pair_lj>` command.
Wikipedia also has a nice article on `water models <http://en.wikipedia.org/wiki/Water_model>`_.
----------
.. _Jorgensen5:
**(Jorgensen)** Jorgensen, Chandrasekhar, Madura, Impey, Klein, J Chem
Phys, 79, 926 (1983).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

228
doc/src/Howto_triclinic.rst Normal file
View File

@ -0,0 +1,228 @@
:doc:`Higher level section <Howto>` - `LAMMPS WWW Site <lws_>`_ - `LAMMPS Documentation <ld_>`_ - `LAMMPS Commands <lc_>`_
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands\_all.html
Triclinic (non-orthogonal) simulation boxes
===========================================
By default, LAMMPS uses an orthogonal simulation box to encompass the
particles. The :doc:`boundary <boundary>` command sets the boundary
conditions of the box (periodic, non-periodic, etc). The orthogonal
box has its "origin" at (xlo,ylo,zlo) and is defined by 3 edge vectors
starting from the origin given by **a** = (xhi-xlo,0,0); **b** =
(0,yhi-ylo,0); **c** = (0,0,zhi-zlo). The 6 parameters
(xlo,xhi,ylo,yhi,zlo,zhi) are defined at the time the simulation box
is created, e.g. by the :doc:`create\_box <create_box>` or
:doc:`read\_data <read_data>` or :doc:`read\_restart <read_restart>`
commands. Additionally, LAMMPS defines box size parameters lx,ly,lz
where lx = xhi-xlo, and similarly in the y and z dimensions. The 6
parameters, as well as lx,ly,lz, can be output via the :doc:`thermo\_style custom <thermo_style>` command.
LAMMPS also allows simulations to be performed in triclinic
(non-orthogonal) simulation boxes shaped as a parallelepiped with
triclinic symmetry. The parallelepiped has its "origin" at
(xlo,ylo,zlo) and is defined by 3 edge vectors starting from the
origin given by **a** = (xhi-xlo,0,0); **b** = (xy,yhi-ylo,0); **c** =
(xz,yz,zhi-zlo). *xy,xz,yz* can be 0.0 or positive or negative values
and are called "tilt factors" because they are the amount of
displacement applied to faces of an originally orthogonal box to
transform it into the parallelepiped. In LAMMPS the triclinic
simulation box edge vectors **a**\ , **b**\ , and **c** cannot be arbitrary
vectors. As indicated, **a** must lie on the positive x axis. **b** must
lie in the xy plane, with strictly positive y component. **c** may have
any orientation with strictly positive z component. The requirement
that **a**\ , **b**\ , and **c** have strictly positive x, y, and z components,
respectively, ensures that **a**\ , **b**\ , and **c** form a complete
right-handed basis. These restrictions impose no loss of generality,
since it is possible to rotate/invert any set of 3 crystal basis
vectors so that they conform to the restrictions.
For example, assume that the 3 vectors **A**\ ,\ **B**\ ,\ **C** are the edge
vectors of a general parallelepiped, where there is no restriction on
**A**\ ,\ **B**\ ,\ **C** other than they form a complete right-handed basis i.e.
**A** x **B** . **C** > 0. The equivalent LAMMPS **a**\ ,\ **b**\ ,\ **c** are a linear
rotation of **A**\ , **B**\ , and **C** and can be computed as follows:
.. image:: Eqs/transform.jpg
:align: center
where A = \| **A** \| indicates the scalar length of **A**\ . The hat symbol (\^)
indicates the corresponding unit vector. *beta* and *gamma* are angles
between the vectors described below. Note that by construction,
**a**\ , **b**\ , and **c** have strictly positive x, y, and z components, respectively.
If it should happen that
**A**\ , **B**\ , and **C** form a left-handed basis, then the above equations
are not valid for **c**\ . In this case, it is necessary
to first apply an inversion. This can be achieved
by interchanging two basis vectors or by changing the sign of one of them.
For consistency, the same rotation/inversion applied to the basis vectors
must also be applied to atom positions, velocities,
and any other vector quantities.
This can be conveniently achieved by first converting to
fractional coordinates in the
old basis and then converting to distance coordinates in the new basis.
The transformation is given by the following equation:
.. image:: Eqs/rotate.jpg
:align: center
where *V* is the volume of the box, **X** is the original vector quantity and
**x** is the vector in the LAMMPS basis.
There is no requirement that a triclinic box be periodic in any
dimension, though it typically should be in at least the 2nd dimension
of the tilt (y in xy) if you want to enforce a shift in periodic
boundary conditions across that boundary. Some commands that work
with triclinic boxes, e.g. the :doc:`fix deform <fix_deform>` and :doc:`fix npt <fix_nh>` commands, require periodicity or non-shrink-wrap
boundary conditions in specific dimensions. See the command doc pages
for details.
The 9 parameters (xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz) are defined at the
time the simulation box is created. This happens in one of 3 ways.
If the :doc:`create\_box <create_box>` command is used with a region of
style *prism*\ , then a triclinic box is setup. See the
:doc:`region <region>` command for details. If the
:doc:`read\_data <read_data>` command is used to define the simulation
box, and the header of the data file contains a line with the "xy xz
yz" keyword, then a triclinic box is setup. See the
:doc:`read\_data <read_data>` command for details. Finally, if the
:doc:`read\_restart <read_restart>` command reads a restart file which
was written from a simulation using a triclinic box, then a triclinic
box will be setup for the restarted simulation.
Note that you can define a triclinic box with all 3 tilt factors =
0.0, so that it is initially orthogonal. This is necessary if the box
will become non-orthogonal, e.g. due to the :doc:`fix npt <fix_nh>` or
:doc:`fix deform <fix_deform>` commands. Alternatively, you can use the
:doc:`change\_box <change_box>` command to convert a simulation box from
orthogonal to triclinic and vice versa.
As with orthogonal boxes, LAMMPS defines triclinic box size parameters
lx,ly,lz where lx = xhi-xlo, and similarly in the y and z dimensions.
The 9 parameters, as well as lx,ly,lz, can be output via the
:doc:`thermo\_style custom <thermo_style>` command.
To avoid extremely tilted boxes (which would be computationally
inefficient), LAMMPS normally requires that no tilt factor can skew
the box more than half the distance of the parallel box length, which
is the 1st dimension in the tilt factor (x for xz). This is required
both when the simulation box is created, e.g. via the
:doc:`create\_box <create_box>` or :doc:`read\_data <read_data>` commands,
as well as when the box shape changes dynamically during a simulation,
e.g. via the :doc:`fix deform <fix_deform>` or :doc:`fix npt <fix_nh>`
commands.
For example, if xlo = 2 and xhi = 12, then the x box length is 10 and
the xy tilt factor must be between -5 and 5. Similarly, both xz and
yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is
not a limitation, since if the maximum tilt factor is 5 (as in this
example), then configurations with tilt = ..., -15, -5, 5, 15, 25,
... are geometrically all equivalent. If the box tilt exceeds this
limit during a dynamics run (e.g. via the :doc:`fix deform <fix_deform>`
command), then the box is "flipped" to an equivalent shape with a tilt
factor within the bounds, so the run can continue. See the :doc:`fix deform <fix_deform>` doc page for further details.
One exception to this rule is if the 1st dimension in the tilt
factor (x for xy) is non-periodic. In that case, the limits on the
tilt factor are not enforced, since flipping the box in that dimension
does not change the atom positions due to non-periodicity. In this
mode, if you tilt the system to extreme angles, the simulation will
simply become inefficient, due to the highly skewed simulation box.
The limitation on not creating a simulation box with a tilt factor
skewing the box more than half the distance of the parallel box length
can be overridden via the :doc:`box <box>` command. Setting the *tilt*
keyword to *large* allows any tilt factors to be specified.
Box flips that may occur using the :doc:`fix deform <fix_deform>` or
:doc:`fix npt <fix_nh>` commands can be turned off using the *flip no*
option with either of the commands.
Note that if a simulation box has a large tilt factor, LAMMPS will run
less efficiently, due to the large volume of communication needed to
acquire ghost atoms around a processor's irregular-shaped sub-domain.
For extreme values of tilt, LAMMPS may also lose atoms and generate an
error.
Triclinic crystal structures are often defined using three lattice
constants *a*\ , *b*\ , and *c*\ , and three angles *alpha*\ , *beta* and
*gamma*\ . Note that in this nomenclature, the a, b, and c lattice
constants are the scalar lengths of the edge vectors **a**\ , **b**\ , and **c**
defined above. The relationship between these 6 quantities
(a,b,c,alpha,beta,gamma) and the LAMMPS box sizes (lx,ly,lz) =
(xhi-xlo,yhi-ylo,zhi-zlo) and tilt factors (xy,xz,yz) is as follows:
.. image:: Eqs/box.jpg
:align: center
The inverse relationship can be written as follows:
.. image:: Eqs/box_inverse.jpg
:align: center
The values of *a*\ , *b*\ , *c* , *alpha*\ , *beta* , and *gamma* can be printed
out or accessed by computes using the
:doc:`thermo\_style custom <thermo_style>` keywords
*cella*\ , *cellb*\ , *cellc*\ , *cellalpha*\ , *cellbeta*\ , *cellgamma*\ ,
respectively.
As discussed on the :doc:`dump <dump>` command doc page, when the BOX
BOUNDS for a snapshot is written to a dump file for a triclinic box,
an orthogonal bounding box which encloses the triclinic simulation box
is output, along with the 3 tilt factors (xy, xz, yz) of the triclinic
box, formatted as follows:
.. parsed-literal::
ITEM: BOX BOUNDS xy xz yz
xlo_bound xhi_bound xy
ylo_bound yhi_bound xz
zlo_bound zhi_bound yz
This bounding box is convenient for many visualization programs and is
calculated from the 9 triclinic box parameters
(xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz) as follows:
.. parsed-literal::
xlo_bound = xlo + MIN(0.0,xy,xz,xy+xz)
xhi_bound = xhi + MAX(0.0,xy,xz,xy+xz)
ylo_bound = ylo + MIN(0.0,yz)
yhi_bound = yhi + MAX(0.0,yz)
zlo_bound = zlo
zhi_bound = zhi
These formulas can be inverted if you need to convert the bounding box
back into the triclinic box parameters, e.g. xlo = xlo\_bound -
MIN(0.0,xy,xz,xy+xz).
One use of triclinic simulation boxes is to model solid-state crystals
with triclinic symmetry. The :doc:`lattice <lattice>` command can be
used with non-orthogonal basis vectors to define a lattice that will
tile a triclinic simulation box via the
:doc:`create\_atoms <create_atoms>` command.
A second use is to run Parrinello-Rahman dynamics via the :doc:`fix npt <fix_nh>` command, which will adjust the xy, xz, yz tilt
factors to compensate for off-diagonal components of the pressure
tensor. The analog for an :doc:`energy minimization <minimize>` is
the :doc:`fix box/relax <fix_box_relax>` command.
A third use is to shear a bulk solid to study the response of the
material. The :doc:`fix deform <fix_deform>` command can be used for
this purpose. It allows dynamic control of the xy, xz, yz tilt
factors as a simulation runs. This is discussed in the next section
on non-equilibrium MD (NEMD) simulations.

148
doc/src/Howto_viscosity.rst Normal file
View File

@ -0,0 +1,148 @@
Calculate viscosity
===================
The shear viscosity eta of a fluid can be measured in at least 5 ways
using various options in LAMMPS. See the examples/VISCOSITY directory
for scripts that implement the 5 methods discussed here for a simple
Lennard-Jones fluid model. Also, see the :doc:`Howto kappa <Howto_kappa>` doc page for an analogous discussion for
thermal conductivity.
Eta is a measure of the propensity of a fluid to transmit momentum in
a direction perpendicular to the direction of velocity or momentum
flow. Alternatively it is the resistance the fluid has to being
sheared. It is given by
J = -eta grad(Vstream)
where J is the momentum flux in units of momentum per area per time.
and grad(Vstream) is the spatial gradient of the velocity of the fluid
moving in another direction, normal to the area through which the
momentum flows. Viscosity thus has units of pressure-time.
The first method is to perform a non-equilibrium MD (NEMD) simulation
by shearing the simulation box via the :doc:`fix deform <fix_deform>`
command, and using the :doc:`fix nvt/sllod <fix_nvt_sllod>` command to
thermostat the fluid via the SLLOD equations of motion.
Alternatively, as a second method, one or more moving walls can be
used to shear the fluid in between them, again with some kind of
thermostat that modifies only the thermal (non-shearing) components of
velocity to prevent the fluid from heating up.
.. note::
A recent (2017) book by :ref:`(Daivis and Todd) <Daivis-viscosity>`
discusses use of the SLLOD method and non-equilibrium MD (NEMD)
thermostatting generally, for both simple and complex fluids,
e.g. molecular systems. The latter can be tricky to do correctly.
In both cases, the velocity profile setup in the fluid by this
procedure can be monitored by the :doc:`fix ave/chunk <fix_ave_chunk>`
command, which determines grad(Vstream) in the equation above.
E.g. the derivative in the y-direction of the Vx component of fluid
motion or grad(Vstream) = dVx/dy. The Pxy off-diagonal component of
the pressure or stress tensor, as calculated by the :doc:`compute pressure <compute_pressure>` command, can also be monitored, which
is the J term in the equation above. See the :doc:`Howto nemd <Howto_nemd>` doc page for details on NEMD simulations.
The third method is to perform a reverse non-equilibrium MD simulation
using the :doc:`fix viscosity <fix_viscosity>` command which implements
the rNEMD algorithm of Muller-Plathe. Momentum in one dimension is
swapped between atoms in two different layers of the simulation box in
a different dimension. This induces a velocity gradient which can be
monitored with the :doc:`fix ave/chunk <fix_ave_chunk>` command.
The fix tallies the cumulative momentum transfer that it performs.
See the :doc:`fix viscosity <fix_viscosity>` 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
stress/pressure tensor to eta. This can be done in a fully
equilibrated simulation which is in contrast to the two preceding
non-equilibrium methods, where momentum flows continuously through the
simulation box.
Here is an example input script that calculates the viscosity of
liquid Ar via the GK formalism:
.. parsed-literal::
# Sample LAMMPS input script for viscosity of liquid Ar
units real
variable T equal 86.4956
variable V equal vol
variable dt equal 4.0
variable p equal 400 # correlation length
variable s equal 5 # sample interval
variable d equal $p\*$s # dump interval
# convert from LAMMPS real units to SI
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
variable convert equal ${atm2Pa}\*${atm2Pa}\*${fs2s}\*${A2m}\*${A2m}\*${A2m}
# setup problem
dimension 3
boundary p p p
lattice fcc 5.376 orient x 1 0 0 orient y 0 1 0 orient z 0 0 1
region box block 0 4 0 4 0 4
create_box 1 box
create_atoms 1 box
mass 1 39.948
pair_style lj/cut 13.0
pair_coeff \* \* 0.2381 3.405
timestep ${dt}
thermo $d
# equilibration and thermalization
velocity all create $T 102486 mom yes rot yes dist gaussian
fix NVT all nvt temp $T $T 10 drag 0.2
run 8000
# viscosity calculation, switch to NVE if desired
#unfix NVT
#fix NVE all nve
reset_timestep 0
variable pxy equal pxy
variable pxz equal pxz
variable pyz equal pyz
fix SS all ave/correlate $s $p $d &
v_pxy v_pxz v_pyz type auto file S0St.dat ave running
variable scale equal ${convert}/(${kB}\*$T)\*$V\*$s\*${dt}
variable v11 equal trap(f_SS[3])\*${scale}
variable v22 equal trap(f_SS[4])\*${scale}
variable v33 equal trap(f_SS[5])\*${scale}
thermo_style custom step temp press v_pxy v_pxz v_pyz v_v11 v_v22 v_v33
run 100000
variable v equal (v_v11+v_v22+v_v33)/3.0
variable ndens equal count(all)/vol
print "average viscosity: $v [Pa.s] @ $T K, ${ndens} /A\^3"
The fifth method is related to the above Green-Kubo method,
but uses the Einstein formulation, analogous to the Einstein
mean-square-displacement formulation for self-diffusivity. The
time-integrated momentum fluxes play the role of Cartesian
coordinates, whose mean-square displacement increases linearly
with time at sufficiently long times.
----------
.. _Daivis-viscosity:
**(Daivis and Todd)** Daivis and Todd, Nonequilibrium Molecular Dynamics (book),
Cambridge University Press, https://doi.org/10.1017/9781139017848, (2017).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

43
doc/src/Howto_viz.rst Normal file
View File

@ -0,0 +1,43 @@
Visualize LAMMPS snapshots
==========================
LAMMPS itself does not do visualization, but snapshots from LAMMPS
simulations can be visualized (and analyzed) in a variety of ways.
Mention dump image and dump movie.
LAMMPS snapshots are created by the :doc:`dump <dump>` command which can
create files in several formats. The native LAMMPS dump format is a
text file (see "dump atom" or "dump custom") which can be visualized
by several popular visualization tools. The :doc:`dump image <dump_image>` and :doc:`dump movie <dump_image>` styles can
output internally rendered images and convert a sequence of them to a
movie during the MD run. Several programs included with LAMMPS as
auxiliary tools can convert between LAMMPS format files and other
formats. See the :doc:`Tools <Tools>` doc page for details.
A Python-based toolkit distributed by our group can read native LAMMPS
dump files, including custom dump files with additional columns of
user-specified atom information, and convert them to various formats
or pipe them into visualization software directly. See the `Pizza.py WWW site <pizza_>`_ for details. Specifically, Pizza.py can convert
LAMMPS dump files into PDB, XYZ, `Ensight <ensight_>`_, and VTK formats.
Pizza.py can pipe LAMMPS dump files directly into the Raster3d and
RasMol visualization programs. Pizza.py has tools that do interactive
3d OpenGL visualization and one that creates SVG images of dump file
snapshots.
.. _pizza: http://www.sandia.gov/~sjplimp/pizza.html
.. _ensight: http://www.ensight.com
.. _atomeye: http://mt.seas.upenn.edu/Archive/Graphics/A
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

76
doc/src/Howto_walls.rst Normal file
View File

@ -0,0 +1,76 @@
Walls
=====
Walls in an MD simulation are typically used to bound particle motion,
i.e. to serve as a boundary condition.
Walls in LAMMPS can be of rough (made of particles) or idealized
surfaces. Ideal walls can be smooth, generating forces only in the
normal direction, or frictional, generating forces also in the
tangential direction.
Rough walls, built of particles, can be created in various ways. The
particles themselves can be generated like any other particle, via the
:doc:`lattice <lattice>` and :doc:`create\_atoms <create_atoms>` commands,
or read in via the :doc:`read\_data <read_data>` command.
Their motion can be constrained by many different commands, so that
they do not move at all, move together as a group at constant velocity
or in response to a net force acting on them, move in a prescribed
fashion (e.g. rotate around a point), etc. Note that if a time
integration fix like :doc:`fix nve <fix_nve>` or :doc:`fix nvt <fix_nh>`
is not used with the group that contains wall particles, their
positions and velocities will not be updated.
* :doc:`fix aveforce <fix_aveforce>` - set force on particles to average value, so they move together
* :doc:`fix setforce <fix_setforce>` - set force on particles to a value, e.g. 0.0
* :doc:`fix freeze <fix_freeze>` - freeze particles for use as granular walls
* :doc:`fix nve/noforce <fix_nve_noforce>` - advect particles by their velocity, but without force
* :doc:`fix move <fix_move>` - prescribe motion of particles by a linear velocity, oscillation, rotation, variable
The :doc:`fix move <fix_move>` command offers the most generality, since
the motion of individual particles can be specified with
:doc:`variable <variable>` formula which depends on time and/or the
particle position.
For rough walls, it may be useful to turn off pairwise interactions
between wall particles via the :doc:`neigh\_modify exclude <neigh_modify>` command.
Rough walls can also be created by specifying frozen particles that do
not move and do not interact with mobile particles, and then tethering
other particles to the fixed particles, via a :doc:`bond <bond_style>`.
The bonded particles do interact with other mobile particles.
Idealized walls can be specified via several fix commands. :doc:`Fix wall/gran <fix_wall_gran>` creates frictional walls for use with
granular particles; all the other commands create smooth walls.
* :doc:`fix wall/reflect <fix_wall_reflect>` - reflective flat walls
* :doc:`fix wall/lj93 <fix_wall>` - flat walls, with Lennard-Jones 9/3 potential
* :doc:`fix wall/lj126 <fix_wall>` - flat walls, with Lennard-Jones 12/6 potential
* :doc:`fix wall/colloid <fix_wall>` - flat walls, with :doc:`pair\_style colloid <pair_colloid>` potential
* :doc:`fix wall/harmonic <fix_wall>` - flat walls, with repulsive harmonic spring potential
* :doc:`fix wall/morse <fix_wall>` - flat walls, with Morse potential
* :doc:`fix wall/region <fix_wall_region>` - use region surface as wall
* :doc:`fix wall/gran <fix_wall_gran>` - flat or curved walls with :doc:`pair\_style granular <pair_gran>` potential
The *lj93*\ , *lj126*\ , *colloid*\ , *harmonic*\ , and *morse* styles all
allow the flat walls to move with a constant velocity, or oscillate in
time. The :doc:`fix wall/region <fix_wall_region>` command offers the
most generality, since the region surface is treated as a wall, and
the geometry of the region can be a simple primitive volume (e.g. a
sphere, or cube, or plane), or a complex volume made from the union
and intersection of primitive volumes. :doc:`Regions <region>` can also
specify a volume "interior" or "exterior" to the specified primitive
shape or *union* or *intersection*\ . :doc:`Regions <region>` can also be
"dynamic" meaning they move with constant velocity, oscillate, or
rotate.
The only frictional idealized walls currently in LAMMPS are flat or
curved surfaces specified by the :doc:`fix wall/gran <fix_wall_gran>`
command. At some point we plan to allow regoin surfaces to be used as
frictional walls, as well as triangulated surfaces.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

58
doc/src/Install.rst Normal file
View File

@ -0,0 +1,58 @@
Install LAMMPS
**************
You can download LAMMPS as an executable or as source code.
With source code, you also have to :doc:`build LAMMPS <Build>`. But you
have more flexibility as to what features to include or exclude in the
build. If you plan to :doc:`modify or extend LAMMPS <Modify>`, then you
need the source code.
.. toctree::
:maxdepth: 1
Install_linux
Install_mac
Install_windows
Install_conda
Install_tarball
Install_git
Install_svn
Install_patch
These are the files and sub-directories in the LAMMPS distribution:
+------------+-------------------------------------------+
| README | text file |
+------------+-------------------------------------------+
| LICENSE | GNU General Public License (GPL) |
+------------+-------------------------------------------+
| bench | benchmark problems |
+------------+-------------------------------------------+
| cmake | CMake build files |
+------------+-------------------------------------------+
| doc | documentation |
+------------+-------------------------------------------+
| examples | simple test problems |
+------------+-------------------------------------------+
| lib | additional provided or external libraries |
+------------+-------------------------------------------+
| potentials | interatomic potential files |
+------------+-------------------------------------------+
| python | Python wrapper on LAMMPS |
+------------+-------------------------------------------+
| src | source files |
+------------+-------------------------------------------+
| tools | pre- and post-processing tools |
+------------+-------------------------------------------+
You will have all of these if you download source. You will only have
some of them if you download executables, as explained on the pages
listed above.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

65
doc/src/Install.txt
View File

@ -1,65 +0,0 @@
"Previous Section"_Intro.html - "LAMMPS WWW Site"_lws - "LAMMPS
Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Build.html
:c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Commands_all.html)
:line
Install LAMMPS :h2
You can download LAMMPS as an executable or as source code.
With source code, you also have to "build LAMMPS"_Build.html. But you
have more flexibility as to what features to include or exclude in the
build. If you plan to "modify or extend LAMMPS"_Modify.html, then you
need the source code.
<!-- RST
.. toctree::
:maxdepth: 1
Install_linux
Install_mac
Install_windows
Install_tarball
Install_git
Install_svn
Install_patch
END_RST -->
<!-- HTML_ONLY -->
"Download an executable for Linux"_Install_linux.html
"Download an executable for Mac"_Install_mac.html
"Download an executable for Windows"_Install_windows.html :all(b)
"Download source as a tarball"_Install_tarball.html
"Donwload source via Git"_Install_git.html
"Donwload source via SVN"_Install_svn.html
"Install patch files"_Install_patch.html :all(b)
<!-- END_HTML_ONLY -->
These are the files and sub-directories in the LAMMPS distribution:
README: text file
LICENSE: GNU General Public License (GPL)
bench: benchmark problems
cmake: CMake build files
doc: documentation
examples: simple test problems
lib: additional provided or external libraries
potentials: interatomic potential files
python: Python wrapper on LAMMPS
src: source files
tools: pre- and post-processing tools :tb(s=:,a=l)
You will have all of these if you download source. You will only have
some of them if you download executables, as explained on the pages
listed above.

53
doc/src/Install_conda.rst Normal file
View File

@ -0,0 +1,53 @@
Download an executable for Linux or Mac via Conda
=================================================
Binaries are available for macOS or Linux via `Conda <conda_>`_.
First, one must setup the Conda package manager on your system. Follow the
instructions to install `Miniconda <mini_conda_install_>`_, then create a conda
environment (named `my-lammps-env` or whatever you prefer) for your lammps
install:
.. parsed-literal::
% conda config --add channels conda-forge
% conda create -n my-lammps-env
Then, you can install lammps on your system with the following command:
.. parsed-literal::
% conda activate my-lammps-env
% conda install lammps
The LAMMPS binary is built with the :ref:`KIM package <kim>` which
results in Conda also installing the `kim-api` binaries when LAMMPS is
installed. In order to use potentials from `openkim.org <openkim_>`_, you can
install the `openkim-models` package
.. parsed-literal::
% conda install openkim-models
If you have problems with the installation you can post issues to
`this link <conda_forge_lammps_>`_.
.. _conda_forge_lammps: https://github.com/conda-forge/lammps-feedstock/issues
Thanks to Jan Janssen (Max-Planck-Institut für Eisenforschung) for setting
up the Conda capability.
.. _openkim: https://openkim.org
.. _conda: https://docs.conda.io/en/latest/index.html
.. _mini_conda_install: https://docs.conda.io/en/latest/miniconda.html
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

128
doc/src/Install_git.rst Normal file
View File

@ -0,0 +1,128 @@
Download source via Git
=======================
All LAMMPS development is coordinated through the "LAMMPS GitHub
site". If you clone the LAMMPS repository onto your local machine, it
has several advantages:
* You can stay current with changes to LAMMPS with a single git
command.
* You can create your own development branches to add code to LAMMPS.
* You can submit your new features back to GitHub for inclusion in
LAMMPS.
You must have `Git <git_>`_ installed on your system to communicate with
the public Git server for LAMMPS.
.. warning::
As of Oct 2016, the official home of public LAMMPS
development is on GitHub. The previously advertised LAMMPS git
repositories on git.lammps.org and bitbucket.org are now deprecated,
may not be up-to-date, and may go away at any time.
.. _git: http://git-scm.com
You can follow LAMMPS development on 3 different Git branches:
* **stable** : this branch is updated with every stable release
* **unstable** : this branch is updated with every patch release
* **master** : this branch continuously follows ongoing development
To access the Git repositories on your box, use the clone command to
create a local copy of the LAMMPS repository with a command like:
.. parsed-literal::
git clone -b unstable https://github.com/lammps/lammps.git mylammps
where "mylammps" is the name of the directory you wish to create on
your machine and "unstable" is one of the 3 branches listed above.
(Note that you actually download all 3 branches; you can switch
between them at any time using "git checkout <branch name>".)
Once the command completes, your directory will contain the same files
as if you unpacked a current LAMMPS tarball, with the exception, that
the HTML documentation files are not included. They can be fetched
from the LAMMPS website by typing "make fetch" in the doc directory.
Or they can be generated from the content provided in doc/src by
typing "make html" from the doc directory.
After initial cloning, as bug fixes and new features are added to
LAMMPS, as listed on :doc:`this page <Errors_bugs>`, you can stay
up-to-date by typing the following Git commands from within the
"mylammps" directory:
.. parsed-literal::
git checkout unstable # not needed if you always stay in this branch
git checkout stable # use one of the 3 checkout commands
git checkout master
git pull
Doing a "pull" will not change any files you have added to the LAMMPS
directory structure. It will also not change any existing LAMMPS
files you have edited, unless those files have changed in the
repository. In that case, Git will attempt to merge the new
repository file with your version of the file and tell you if there
are any conflicts. See the Git documentation for details.
If you want to access a particular previous release version of LAMMPS,
you can instead "checkout" any version with a published tag. See the
output of "git tag -l" for the list of tags. The Git command to do
this is as follows.
.. parsed-literal::
git checkout tagID
Stable versions and what tagID to use for a particular stable version
are discussed on :doc:`this page <Errors_bugs>`. Note that this command
will print some warnings, because in order to get back to the latest
revision and to be able to update with "git pull" again, you first
will need to first type "git checkout unstable" (or check out any
other desired branch).
Once you have updated your local files with a "git pull" (or "git
checkout"), you still need to re-build LAMMPS if any source files have
changed. To do this, you should cd to the src directory and type:
.. parsed-literal::
make purge # remove any deprecated src files
make package-update # sync package files with src files
make foo # re-build for your machine (mpi, serial, etc)
just as described on the :doc:`Install patch <Install_patch>` doc page,
after a patch has been installed.
.. warning::
If you wish to edit/change a src file that is from a
package, you should edit the version of the file inside the package
sub-directory with src, then re-install the package. The version in
the src dir is merely a copy and will be wiped out if you type "make
package-update".
.. warning::
The GitHub servers support both the "git://" and
"https://" access protocols for anonymous read-only access. If you
have a correspondingly configured GitHub account, you may also use SSH
with "git@github.com:/lammps/lammps.git".
The LAMMPS GitHub project is managed by Christoph Junghans (LANL,
junghans at lanl.gov), Axel Kohlmeyer (Temple U, akohlmey at
gmail.com) and Richard Berger (Temple U, richard.berger at
temple.edu).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

269
doc/src/Install_linux.rst Normal file
View File

@ -0,0 +1,269 @@
Download an executable for Linux
================================
Binaries are available for different versions of Linux:
| :ref:`Pre-built Ubuntu Linux executables <ubuntu>`
| :ref:`Pre-built Fedora Linux executables <fedora>`
| :ref:`Pre-built EPEL Linux executables (RHEL, CentOS) <epel>`
| :ref:`Pre-built OpenSuse Linux executables <opensuse>`
| :ref:`Gentoo Linux executable <gentoo>`
| :ref:`Arch Linux build-script <arch>`
|
----------
.. _ubuntu:
Pre-built Ubuntu Linux executables
-----------------------------------------------
A pre-built LAMMPS executable suitable for running on the latest
Ubuntu Linux versions, can be downloaded as a Debian package. This
allows you to install LAMMPS with a single command, and stay
up-to-date with the current version of LAMMPS by simply updating your
operating system.
To install the appropriate personal-package archive (PPA), do the
following once:
.. parsed-literal::
sudo add-apt-repository ppa:gladky-anton/lammps
sudo apt-get update
To install LAMMPS do the following once:
.. parsed-literal::
sudo apt-get install lammps-daily
This downloads an executable named "lmp\_daily" to your box, which
can then be used in the usual way to run input scripts:
.. parsed-literal::
lmp_daily -in in.lj
To update LAMMPS to the most current version, do the following:
.. parsed-literal::
sudo apt-get update
which will also update other packages on your system.
To get a copy of the current documentation and examples:
.. parsed-literal::
sudo apt-get install lammps-daily-doc
which will download the doc files in
/usr/share/doc/lammps-daily-doc/doc and example problems in
/usr/share/doc/lammps-doc/examples.
Note that you may still wish to download the tarball to get potential
files and auxiliary tools.
To un-install LAMMPS, do the following:
.. parsed-literal::
sudo apt-get remove lammps-daily
Note that the lammps-daily executable is built with the following
sequence of make commands, as if you had done the same with the
unpacked tarball files in the src directory:
make yes-all; make no-lib; make openmpi
Thus it builds with FFTW3 and OpenMPI.
Thanks to Anton Gladky (gladky.anton at gmail.com) for setting up this
Ubuntu package capability.
----------
.. _fedora:
Pre-built Fedora Linux executables
-----------------------------------------------
Pre-built LAMMPS packages for stable releases are available
in the Fedora Linux distribution as of version 28. The packages
can be installed via the dnf package manager. There are 3 basic
varieties (lammps = no MPI, lammps-mpich = MPICH MPI library,
lammps-openmpi = OpenMPI MPI library) and for each support for
linking to the C library interface (lammps-devel, lammps-mpich-devel,
lammps-openmpi-devel), the header for compiling programs using
the C library interface (lammps-headers), and the LAMMPS python
module for Python 3. All packages can be installed at the same
time and the name of the LAMMPS executable is *lmp* and *lmp\_openmpi*
or *lmp\_mpich* respectively. By default, *lmp* will refer to the
serial executable, unless one of the MPI environment modules is loaded
("module load mpi/mpich-x86\_64" or "module load mpi/openmpi-x86\_64").
Then the corresponding parallel LAMMPS executable can be used.
The same mechanism applies when loading the LAMMPS python module.
To install LAMMPS with OpenMPI and run an input in.lj with 2 CPUs do:
.. parsed-literal::
dnf install lammps-openmpi
module load mpi/openmpi-x86_64
mpirun -np 2 lmp -in in.lj
The "dnf install" command is needed only once. In case of a new LAMMPS
stable release, "dnf update" will automatically update to the newer
version as soon at the RPM files are built and uploaded to the download
mirrors. The "module load" command is needed once per (shell) session
or shell terminal instance, unless it is automatically loaded from the
shell profile.
Please use "lmp -help" to see which compilation options, packages,
and styles are included in the binary.
Thanks to Christoph Junghans (LANL) for making LAMMPS available in Fedora.
----------
.. _epel:
Pre-built EPEL Linux executable
------------------------------------------
Pre-built LAMMPS packages for stable releases are available
in the `Extra Packages for Enterprise Linux (EPEL) repository <https://fedoraproject.org/wiki/EPEL>`_
for use with Red Hat Enterprise Linux (RHEL) or CentOS version 7.x
and compatible Linux distributions. Names of packages, executable,
and content are the same as described above for Fedora Linux.
But RHEL/CentOS 7.x uses the "yum" package manager instead of "dnf"
in Fedora 28.
Please use "lmp -help" to see which compilation options, packages,
and styles are included in the binary.
Thanks to Christoph Junghans (LANL) for making LAMMPS available in EPEL.
----------
.. _opensuse:
Pre-built OpenSuse Linux executable
--------------------------------------------------
A pre-built LAMMPS package for stable releases is available
in OpenSuse as of Leap 15.0. You can install the package with:
.. parsed-literal::
zypper install lammps
This includes support for OpenMPI. The name of the LAMMPS executable
is *lmp*\ . Thus to run an input in parallel on 2 CPUs you would do:
.. parsed-literal::
mpirun -np 2 lmp -in in.lj
Please use "lmp -help" to see which compilation options, packages,
and styles are included in the binary.
Thanks to Christoph Junghans (LANL) for making LAMMPS available in OpenSuse.
----------
.. _gentoo:
Gentoo Linux executable
------------------------------------
LAMMPS is part of Gentoo's main package tree and can be installed by
typing:
.. parsed-literal::
% emerge --ask lammps
Note that in Gentoo the LAMMPS source is downloaded and the package is
built on the your machine.
Certain LAMMPS packages can be enable via USE flags, type
.. parsed-literal::
% equery uses lammps
for details.
Thanks to Nicolas Bock and Christoph Junghans (LANL) for setting up
this Gentoo capability.
----------
.. _arch:
Archlinux build-script
---------------------------------
LAMMPS is available via Arch's unofficial Arch User repository (AUR).
There are three scripts available, named lammps, lammps-beta and lammps-git.
They respectively package the stable, patch and git releases.
To install, you will need to have the git package installed. You may use
any of the above names in-place of lammps.
.. parsed-literal::
$ git clone https://aur.archlinux.org/lammps.git
$ cd lammps
$ makepkg -s
# makepkg -i
To update, you may repeat the above, or change into the cloned directory,
and execute the following, after which, if there are any changes, you may
use makepkg as above.
.. parsed-literal::
$ git pull
Alternatively, you may use an AUR helper to install these packages.
Note that the AUR provides build-scripts that download the source and
the build the package on your machine.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

54
doc/src/Install_mac.rst Normal file
View File

@ -0,0 +1,54 @@
Download an executable for Mac
==============================
LAMMPS can be downloaded, built, and configured for OS X on a Mac with
`Homebrew <homebrew_>`_. (Alternatively, see the install instructions for
:doc:`Download an executable via Conda <Install_conda>`.) The following LAMMPS
packages are unavailable at this time because of additional needs not yet met:
GPU, KOKKOS, LATTE, MSCG, MESSAGE, MPIIO POEMS VORONOI.
After installing Homebrew, you can install LAMMPS on your system with
the following commands:
.. parsed-literal::
% brew install lammps
This will install the executables "lammps\_serial" and "lammps\_mpi", as well as
the LAMMPS "doc", "potentials", "tools", "bench", and "examples" directories.
Once LAMMPS is installed, you can test the installation with the
Lennard-Jones benchmark file:
.. parsed-literal::
% brew test lammps -v
The LAMMPS binary is built with the :ref:`KIM package <kim>` which
results in Homebrew also installing the `kim-api` binaries when LAMMPS is
installed. In order to use potentials from `openkim.org <openkim_>`_, you can
install the `openkim-models` package
.. parsed-literal::
% brew install openkim-models
If you have problems with the installation you can post issues to
`this link <homebrew_>`_.
.. _homebrew: https://github.com/Homebrew/homebrew-core/issues
Thanks to Derek Thomas (derekt at cello.t.u-tokyo.ac.jp) for setting
up the Homebrew capability.
.. _openkim: https://openkim.org
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

43
doc/src/Install_mac.txt
View File

@ -1,43 +0,0 @@
"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS
Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Commands_all.html)
:line
Download an executable for Mac :h3
LAMMPS can be downloaded, built, and configured for OS X on a Mac with
"Homebrew"_homebrew. The following LAMMPS packages are unavailable at this
time because of additional needs not yet met: GPU, KOKKOS, LATTE, MSCG,
MESSAGE, MPIIO POEMS VORONOI.
After installing Homebrew, you can install LAMMPS on your system with
the following commands:
% brew install lammps :pre
This will install the executables "lammps_serial" and "lammps_mpi", as well as
the LAMMPS "doc", "potentials", "tools", "bench", and "examples" directories.
Once LAMMPS is installed, you can test the installation with the
Lennard-Jones benchmark file:
% brew test lammps -v :pre
The LAMMPS binary is built with the "KIM package"_Build_extras#kim which
results in Homebrew also installing the `kim-api` binaries when LAMMPS is
installed. In order to use potentials from "openkim.org"_openkim, you can
install the `openkim-models` package
% brew install openkim-models :pre
If you have problems with the installation you can post issues to
"this link"_homebrew.
Thanks to Derek Thomas (derekt at cello.t.u-tokyo.ac.jp) for setting
up the Homebrew capability.
:link(homebrew,https://github.com/Homebrew/homebrew-core/issues)
:link(openkim,https://openkim.org)

68
doc/src/Install_patch.rst Normal file
View File

@ -0,0 +1,68 @@
Applying patches
================
It is easy to stay current with the most recent LAMMPS patch releases
if you use Git or SVN to track LAMMPS development. Instructions for
how to stay current are on the :doc:`Install git <Install_git>` and
:doc:`Install svn <Install_svn>` doc pages.
If you prefer to download a tarball, as described on the :doc:`Install git <Install_tarball>` doc page, you can stay current by
downloading "patch files" when new patch releases are made. A link to
a patch file is posted on the `bug and feature page <http://lammps.sandia.gov/bug.html>`_ of the LAMMPS website, along
with a list of changed files and details about what is in the new patch
release. This page explains how to apply the patch file to your local
LAMMPS directory.
.. note::
You should not apply patch files to a local Git or SVN repo of
LAMMPS, only to an unpacked tarball. Use Git and SVN commands to
update repo versions of LAMMPS.
Here are the steps to apply a patch file. Note that if your version
of LAMMPS is several patch releases behind, you need to apply all the
intervening patch files in succession to bring your version of LAMMPS
up to date.
* Download the patch file. You may have to shift-click in your browser
to download the file instead of display it. Patch files have names
like patch.12Dec16.
* Put the patch file in your top-level LAMMPS directory, where the
LICENSE and README files are.
* Apply the patch by typing the following command from your top-level
LAMMPS directory, where the redirected file is the name of the patch
file.
.. parsed-literal::
patch -bp1 < patch.12Dec16
* A list of updated files print out to the screen. The -b switch
creates backup files of your originals (e.g. src/force.cpp.orig), so
you can manually undo the patch if something goes wrong.
* Type the following from the src directory, to enforce consistency
between the src and package directories. This is OK to do even if you
don't use one or more packages. If you are applying several patches
successively, you only need to type this once at the end. The purge
command removes deprecated src files if any were removed by the patch
from package sub-directories.
.. parsed-literal::
make purge
make package-update
* Re-build LAMMPS via the "make" command.
.. warning::
If you wish to edit/change a src file that is from a
package, you should edit the version of the file inside the package
sub-dir of src, then re-install the package. The version in the src
dir is merely a copy and will be wiped out if you type "make
package-update".
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

102
doc/src/Install_svn.rst Normal file
View File

@ -0,0 +1,102 @@
Download source via SVN
=======================
.. warning::
As of Oct 2016, SVN support is now implemented via a
git-to-subversion interface service on GitHub and no longer through a
mirror of the internal SVN repository at Sandia.
You must have the `Subversion (SVN) client software <svn_>`_ installed on
your system to communicate with the Git server in this mode.
.. _svn: http://subversion.apache.org
You can follow LAMMPS development on 3 different SVN branches:
* **stable** : this branch is updated with every stable release
* **unstable** : this branch is updated with every patch release
* **master** : this branch continuously follows ongoing development
The corresponding command lines to do an initial checkout are as
follows. (Note that unlike Git, you must perform a separate checkout
into a unique directory for each of the 3 branches.)
.. parsed-literal::
svn checkout https://github.com/lammps/lammps.git/branches/unstable mylammps
svn checkout https://github.com/lammps/lammps.git/branches/stable mylammps
svn checkout https://github.com/lammps/lammps.git/trunk mylammps
where "mylammps" is the name of the directory you wish to create on
your machine.
Once the command completes, your directory will contain the same files
as if you unpacked a current LAMMPS tarball, with the exception, that
the HTML documentation files are not included. They can be fetched
from the LAMMPS website by typing "make fetch" in the doc directory.
Or they can be generated from the content provided in doc/src by
typing "make html" from the doc directory.
After initial checkout, as bug fixes and new features are added to
LAMMPS, as listed on :doc:`this page <Errors_bugs>`, you can stay
up-to-date by typing the following SVN commands from within the
"mylammps" directory:
.. parsed-literal::
svn update
You can also check if there are any updates by typing:
.. parsed-literal::
svn -qu status
Doing an "update" will not change any files you have added to the
LAMMPS directory structure. It will also not change any existing
LAMMPS files you have edited, unless those files have changed in the
repository. In that case, SVN will attempt to merge the new
repository file with your version of the file and tell you if there
are any conflicts. See the SVN documentation for details.
Please refer to the `subversion client support help pages on GitHub <https://help.github.com/articles/support-for-subversion-clients>`_
if you want to use advanced features like accessing particular
previous release versions via tags.
Once you have updated your local files with an "svn update" (or "svn
co"), you still need to re-build LAMMPS if any source files have
changed. To do this, you should cd to the src directory and type:
.. parsed-literal::
make purge # remove any deprecated src files
make package-update # sync package files with src files
make foo # re-build for your machine (mpi, serial, etc)
just as described on the :doc:`Install patch <Install_patch>` doc page,
after a patch has been installed.
.. warning::
If you wish to edit/change a src file that is from a
package, you should edit the version of the file inside the package
sub-directory with src, then re-install the package. The version in
the src dir is merely a copy and will be wiped out if you type "make
package-update".
The LAMMPS GitHub project is managed by Christoph Junghans (LANL,
junghans at lanl.gov), Axel Kohlmeyer (Temple U, akohlmey at
gmail.com) and Richard Berger (Temple U, richard.berger at
temple.edu).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

84
doc/src/Install_tarball.rst Normal file
View File

@ -0,0 +1,84 @@
Download source and documentation as a tarball
==============================================
You can download a current LAMMPS tarball from the `download page <download_>`_
of the `LAMMPS website <lws_>`_.
.. _download: http://lammps.sandia.gov/download.html
.. _bug: http://lammps.sandia.gov/bug.html
.. _older: http://lammps.sandia.gov/tars
You have two choices of tarballs, either the most recent stable
release or the most current patch release. Stable releases occur a
few times per year, and undergo more testing before release. Patch
releases occur a couple times per month. The new contents in all
releases are listed on the `bug and feature page <bug_>`_ of the website.
Both tarballs include LAMMPS documentation (HTML and PDF files)
corresponding to that version. The download page also has an option
to download the current-version LAMMPS documentation by itself.
Older versions of LAMMPS can also be downloaded from `this page <older_>`_.
Once you have a tarball, unzip and untar it with the following
command:
.. parsed-literal::
tar -xzvf lammps\*.tar.gz
This will create a LAMMPS directory with the version date
in its name, e.g. lammps-23Jun18.
----------
You can also download a zip file via the "Clone or download" button on
the `LAMMPS GitHub site <git_>`_. The file name will be lammps-master.zip
which can be unzipped with the following command, to create
a lammps-master dir:
.. parsed-literal::
unzip lammps\*.zip
This version is the most up-to-date LAMMPS development version. It
will have the date of the most recent patch release (see the file
src/version.h). But it will also include any new bug-fixes or
features added since the last patch release. They will be included in
the next patch release tarball.
.. _git: https://github.com/lammps/lammps
----------
If you download a current LAMMPS tarball, one way to stay current as
new patch tarballs are released, is to download a patch file which you
can apply to your local directory to update it for each new patch
release. (Or of course you could just download the newest tarball
periodically.)
The patch files are posted on the `bug and feature page <bug_>`_ of the
website, along with a list of changed files and details about what is
in the new patch release. Instructions for applying a patch file are
on the :doc:`Install patch <Install_patch>` doc page.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

49
doc/src/Install_windows.rst Normal file
View File

@ -0,0 +1,49 @@
Download an executable for Windows
==================================
Pre-compiled Windows installers which install LAMMPS executables on a
Windows system can be downloaded from this site:
`http://packages.lammps.org/windows.html <http://packages.lammps.org/windows.html>`_
Note that each installer package has a date in its name, which
corresponds to the LAMMPS version of the same date. Installers for
current and older versions of LAMMPS are available. 32-bit and 64-bit
installers are available, and each installer contains both a serial
and parallel executable. The installer site also explains how to
install the Windows MPI package (MPICH2 from Argonne National Labs),
needed to run in parallel.
The LAMMPS binaries contain all optional packages included in the
source distribution except: KIM, KOKKOS, USER-INTEL, and USER-QMMM.
The serial version also does not include the MPIIO and
USER-LB packages. GPU support is provided for OpenCL.
The installer site also has instructions on how to run LAMMPS under
Windows, once it is installed, in both serial and parallel.
When you download the installer package, you run it on your Windows
machine. It will then prompt you with a dialog, where you can choose
the installation directory, unpack and copy several executables,
potential files, documentation pdfs, selected example files, etc. It
will then update a few system settings (e.g. PATH, LAMMPS\_POTENTIALS)
and add an entry into the Start Menu (with references to the
documentation, LAMMPS homepage and more). From that menu, there is
also a link to an uninstaller that removes the files and undoes the
environment manipulations.
Note that to update to a newer version of LAMMPS, you should typically
uninstall the version you currently have, download a new installer,
and go through the install procedure described above. I.e. the same
procedure for installing/updating most Windows programs. You can
install multiple versions of LAMMPS (in different directories), but
only the executable for the last-installed package will be found
automatically, so this should only be done for debugging purposes.
Thanks to Axel Kohlmeyer (Temple U, akohlmey at gmail.com) for setting
up this Windows capability.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

21
doc/src/Intro.rst Normal file
View File

@ -0,0 +1,21 @@
Introduction
************
These pages provide a brief introduction to LAMMPS.
.. toctree::
:maxdepth: 1
Intro_overview
Manual_version
Intro_features
Intro_nonfeatures
Intro_opensource
Intro_authors
Intro_website
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

69
doc/src/Intro_authors.rst Normal file
View File

@ -0,0 +1,69 @@
Authors of LAMMPS
=================
The primary LAMMPS developers are at Sandia National Labs and Temple
University:
* `Steve Plimpton <sjp_>`_, sjplimp at sandia.gov
* Aidan Thompson, athomps at sandia.gov
* Stan Moore, stamoor at sandia.gov
* Axel Kohlmeyer, akohlmey at gmail.com
* Richard Berger, richard.berger at temple.edu
.. _sjp: http://www.cs.sandia.gov/~sjplimp
Past developers include Paul Crozier and Mark Stevens, both at Sandia,
and Ray Shan, now at Materials Design.
----------
The `Authors page <http://lammps.sandia.gov/authors.html>`_ of the
`LAMMPS website <lws_>`_ has a comprehensive list of all the individuals
who have contributed code for a new feature or command or tool to
LAMMPS.
----------
The following folks deserve special recognition. Many of the packages
they have written are unique for an MD code and LAMMPS would not be as
general-purpose as it is without their expertise and efforts.
* Metin Aktulga (MSU), USER-REAXC package for C version of ReaxFF
* Mike Brown (Intel), GPU and USER-INTEL packages
* Colin Denniston (U Western Ontario), USER-LB package
* Georg Ganzenmuller (EMI), USER-SMD and USER-SPH packages
* Andres Jaramillo-Botero (Caltech), USER-EFF package for electron force field
* Reese Jones (Sandia) and colleagues, USER-ATC package for atom/continuum coupling
* Christoph Kloss (DCS Computing), LIGGGHTS code for granular materials, built on top of LAMMPS
* Rudra Mukherjee (JPL), POEMS package for articulated rigid body motion
* Trung Ngyuen (Northwestern U), GPU and RIGID and BODY packages
* Mike Parks (Sandia), PERI package for Peridynamics
* Roy Pollock (LLNL), Ewald and PPPM solvers
* Christian Trott (Sandia), USER-CUDA and KOKKOS packages
* Ilya Valuev (JIHT), USER-AWPMD package for wave packet MD
* Greg Wagner (Northwestern U), MEAM package for MEAM potential
----------
As discussed on the `History page <http://lammps.sandia.gov/history.html>`_ of the website, LAMMPS
originated as a cooperative project between DOE labs and industrial
partners. Folks involved in the design and testing of the original
version of LAMMPS were the following:
* John Carpenter (Mayo Clinic, formerly at Cray Research)
* Terry Stouch (Lexicon Pharmaceuticals, formerly at Bristol Myers Squibb)
* Steve Lustig (Dupont)
* Jim Belak and Roy Pollock (LLNL)
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

231
doc/src/Intro_features.rst Normal file
View File

@ -0,0 +1,231 @@
LAMMPS features
===============
LAMMPS is a classical molecular dynamics (MD) code with these general
classes of functionality:
* :ref:`General features <general>`
* :ref:`Particle and model types <particle>`
* :ref:`Interatomic potentials (force fields) <ff>`
* :ref:`Atom creation <create>`
* :ref:`Ensembles, constraints, and boundary conditions <ensemble>`
* :ref:`Integrators <integrate>`
* :ref:`Diagnostics <diag>`
* :ref:`Output <output>`
* :ref:`Multi-replica models <replica1>`
* :ref:`Pre- and post-processing <prepost>`
* :ref:`Specialized features (beyond MD itself) <special>`
----------
.. _general:
General features
------------------------------
* runs on a single processor or in parallel
* distributed-memory message-passing parallelism (MPI)
* spatial-decomposition of simulation domain for parallelism
* open-source distribution
* highly portable C++
* optional libraries used: MPI and single-processor FFT
* GPU (CUDA and OpenCL), Intel Xeon Phi, and OpenMP support for many code features
* easy to extend with new features and functionality
* runs from an input script
* syntax for defining and using variables and formulas
* syntax for looping over runs and breaking out of loops
* run one or multiple simulations simultaneously (in parallel) from one script
* build as library, invoke LAMMPS through library interface or provided Python wrapper
* couple with other codes: LAMMPS calls other code, other code calls LAMMPS, umbrella code calls both
.. _particle:
Particle and model types
---------------------------------------
(:doc:`atom style <atom_style>` command)
* atoms
* coarse-grained particles (e.g. bead-spring polymers)
* united-atom polymers or organic molecules
* all-atom polymers, organic molecules, proteins, DNA
* metals
* granular materials
* coarse-grained mesoscale models
* finite-size spherical and ellipsoidal particles
* finite-size line segment (2d) and triangle (3d) particles
* point dipole particles
* rigid collections of particles
* hybrid combinations of these
.. _ff:
Interatomic potentials (force fields)
----------------------------------------------
(:doc:`pair style <pair_style>`, :doc:`bond style <bond_style>`,
:doc:`angle style <angle_style>`, :doc:`dihedral style <dihedral_style>`,
:doc:`improper style <improper_style>`, :doc:`kspace style <kspace_style>`
commands)
* pairwise potentials: Lennard-Jones, Buckingham, Morse, Born-Mayer-Huggins, Yukawa, soft, class 2 (COMPASS), hydrogen bond, tabulated
* charged pairwise potentials: Coulombic, point-dipole
* many-body potentials: EAM, Finnis/Sinclair EAM, modified EAM (MEAM), embedded ion method (EIM), EDIP, ADP, Stillinger-Weber, Tersoff, REBO, AIREBO, ReaxFF, COMB, SNAP, Streitz-Mintmire, 3-body polymorphic
* long-range interactions for charge, point-dipoles, and LJ dispersion: Ewald, Wolf, PPPM (similar to particle-mesh Ewald)
* polarization models: :doc:`QEq <fix_qeq>`, :doc:`core/shell model <Howto_coreshell>`, :doc:`Drude dipole model <Howto_drude>`
* charge equilibration (QEq via dynamic, point, shielded, Slater methods)
* coarse-grained potentials: DPD, GayBerne, REsquared, colloidal, DLVO
* mesoscopic potentials: granular, Peridynamics, SPH
* electron force field (eFF, AWPMD)
* bond potentials: harmonic, FENE, Morse, nonlinear, class 2, quartic (breakable)
* angle potentials: harmonic, CHARMM, cosine, cosine/squared, cosine/periodic, class 2 (COMPASS)
* dihedral potentials: harmonic, CHARMM, multi-harmonic, helix, class 2 (COMPASS), OPLS
* improper potentials: harmonic, cvff, umbrella, class 2 (COMPASS)
* polymer potentials: all-atom, united-atom, bead-spring, breakable
* water potentials: TIP3P, TIP4P, SPC
* implicit solvent potentials: hydrodynamic lubrication, Debye
* force-field compatibility with common CHARMM, AMBER, DREIDING, OPLS, GROMACS, COMPASS options
* access to the `OpenKIM Repository <http://openkim.org>`_ of potentials via :doc:`kim\_init, kim\_interactions, and kim\_query <kim_commands>` commands
* hybrid potentials: multiple pair, bond, angle, dihedral, improper potentials can be used in one simulation
* overlaid potentials: superposition of multiple pair potentials
.. _create:
Atom creation
--------------------------
(:doc:`read\_data <read_data>`, :doc:`lattice <lattice>`,
:doc:`create\_atoms <create_atoms>`, :doc:`delete\_atoms <delete_atoms>`,
:doc:`displace\_atoms <displace_atoms>`, :doc:`replicate <replicate>` commands)
* read in atom coords from files
* create atoms on one or more lattices (e.g. grain boundaries)
* delete geometric or logical groups of atoms (e.g. voids)
* replicate existing atoms multiple times
* displace atoms
.. _ensemble:
Ensembles, constraints, and boundary conditions
--------------------------------------------------------------
(:doc:`fix <fix>` command)
* 2d or 3d systems
* orthogonal or non-orthogonal (triclinic symmetry) simulation domains
* constant NVE, NVT, NPT, NPH, Parrinello/Rahman integrators
* thermostatting options for groups and geometric regions of atoms
* pressure control via Nose/Hoover or Berendsen barostatting in 1 to 3 dimensions
* simulation box deformation (tensile and shear)
* harmonic (umbrella) constraint forces
* rigid body constraints
* SHAKE bond and angle constraints
* Monte Carlo bond breaking, formation, swapping
* atom/molecule insertion and deletion
* walls of various kinds
* non-equilibrium molecular dynamics (NEMD)
* variety of additional boundary conditions and constraints
.. _integrate:
Integrators
---------------------------
(:doc:`run <run>`, :doc:`run\_style <run_style>`, :doc:`minimize <minimize>` commands)
* velocity-Verlet integrator
* Brownian dynamics
* rigid body integration
* energy minimization via conjugate gradient or steepest descent relaxation
* rRESPA hierarchical timestepping
* rerun command for post-processing of dump files
.. _diag:
Diagnostics
----------------------
* see various flavors of the :doc:`fix <fix>` and :doc:`compute <compute>` commands
.. _output:
Output
-------------------
(:doc:`dump <dump>`, :doc:`restart <restart>` commands)
* log file of thermodynamic info
* text dump files of atom coords, velocities, other per-atom quantities
* binary restart files
* parallel I/O of dump and restart files
* per-atom quantities (energy, stress, centro-symmetry parameter, CNA, etc)
* user-defined system-wide (log file) or per-atom (dump file) calculations
* spatial and time averaging of per-atom quantities
* time averaging of system-wide quantities
* atom snapshots in native, XYZ, XTC, DCD, CFG formats
.. _replica1:
Multi-replica models
-----------------------------------
* :doc:`nudged elastic band <neb>`
* :doc:`parallel replica dynamics <prd>`
* :doc:`temperature accelerated dynamics <tad>`
* :doc:`parallel tempering <temper>`
.. _prepost:
Pre- and post-processing
--------------------------------------
* A handful of pre- and post-processing tools are packaged with LAMMPS,
some of which can convert input and output files to/from formats used
by other codes; see the :doc:`Toos <Tools>` doc page.
* Our group has also written and released a separate toolkit called
`Pizza.py <pizza_>`_ which provides tools for doing setup, analysis,
plotting, and visualization for LAMMPS simulations. Pizza.py is
written in `Python <python_>`_ and is available for download from `the Pizza.py WWW site <pizza_>`_.
.. _pizza: http://www.sandia.gov/~sjplimp/pizza.html
.. _python: http://www.python.org
.. _special:
Specialized features
----------------------------------
LAMMPS can be built with optional packages which implement a variety
of additional capabilities. See the :doc:`Packages <Packages>` doc
page for details.
These are LAMMPS capabilities which you may not think of as typical
classical MD options:
* :doc:`static <balance>` and :doc:`dynamic load-balancing <fix_balance>`
* :doc:`generalized aspherical particles <Howto_body>`
* :doc:`stochastic rotation dynamics (SRD) <fix_srd>`
* :doc:`real-time visualization and interactive MD <fix_imd>`
* calculate :doc:`virtual diffraction patterns <compute_xrd>`
* :doc:`atom-to-continuum coupling <fix_atc>` with finite elements
* coupled rigid body integration via the :doc:`POEMS <fix_poems>` library
* :doc:`QM/MM coupling <fix_qmmm>`
* Monte Carlo via :doc:`GCMC <fix_gcmc>` and :doc:`tfMC <fix_tfmc>` and :doc:`atom swapping <fix_atom_swap>`
* :doc:`path-integral molecular dynamics (PIMD) <fix_ipi>` and :doc:`this as well <fix_pimd>`
* :doc:`Direct Simulation Monte Carlo <pair_dsmc>` for low-density fluids
* :doc:`Peridynamics mesoscale modeling <pair_peri>`
* :doc:`Lattice Boltzmann fluid <fix_lb_fluid>`
* :doc:`targeted <fix_tmd>` and :doc:`steered <fix_smd>` molecular dynamics
* :doc:`two-temperature electron model <fix_ttm>`
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

87
doc/src/Intro_nonfeatures.rst Normal file
View File

@ -0,0 +1,87 @@
LAMMPS non-features
===================
LAMMPS is designed to be a fast, parallel engine for molecular
dynamics (MD) simulations. It provides only a modest amount of
functionality for setting up simulations and analyzing their output.
Specifically, LAMMPS was not conceived and designed for:
* being run through a GUI
* building molecular systems, or building molecular topologies
* assign force-field coefficients automagically
* perform sophisticated analysis of your MD simulation
* visualize your MD simulation interactively
* plot your output data
Although over the years these limitations have been somewhat
reduced through features added to LAMMPS or external tools
that either closely interface with LAMMPS or extend LAMMPS.
Here are suggestions on how to perform these tasks:
* **GUI:** LAMMPS can be built as a library and a Python wrapper that wraps
the library interface is provided. Thus, GUI interfaces can be
written in Python (or C or C++ if desired) that run LAMMPS and
visualize or plot its output. Examples of this are provided in the
python directory and described on the :doc:`Python <Python_head>` doc
page. Also, there are several external wrappers or GUI front ends.
* **Builder:** Several pre-processing tools are packaged with LAMMPS. Some
of them convert input files in formats produced by other MD codes such
as CHARMM, AMBER, or Insight into LAMMPS input formats. Some of them
are simple programs that will build simple molecular systems, such as
linear bead-spring polymer chains. The moltemplate program is a true
molecular builder that will generate complex molecular models. See
the :doc:`Tools <Tools>` doc page for details on tools packaged with
LAMMPS. The `Pre/post processing page <http:/lammps.sandia.gov/prepost.html>`_ of the LAMMPS website
describes a variety of 3rd party tools for this task. Furthermore,
some LAMMPS internal commands allow to reconstruct, or selectively add
topology information, as well as provide the option to insert molecule
templates instead of atoms for building bulk molecular systems.
* **Force-field assignment:** The conversion tools described in the previous
bullet for CHARMM, AMBER, and Insight will also assign force field
coefficients in the LAMMPS format, assuming you provide CHARMM, AMBER,
or BIOVIA (formerly Accelrys) force field files. The tools
`ParmEd <https://parmed.github.io/ParmEd/html/index.html>`_ and
`InterMol <https://github.com/shirtsgroup/InterMol>`_ are particularly
powerful and flexible in converting force field and topology data
between various MD simulation programs.
* **Simulation analysis:** If you want to perform analysis on-the-fly as
your simulation runs, see the :doc:`compute <compute>` and
:doc:`fix <fix>` doc pages, which list commands that can be used in a
LAMMPS input script. Also see the :doc:`Modify <Modify>` doc page for
info on how to add your own analysis code or algorithms to LAMMPS.
For post-processing, LAMMPS output such as :doc:`dump file snapshots <dump>` can be converted into formats used by other MD or
post-processing codes. To some degree, that conversion can be done
directly inside of LAMMPS by interfacing to the VMD molfile plugins.
The :doc:`rerun <rerun>` command also allows to do some post-processing
of existing trajectories, and through being able to read a variety
of file formats, this can also be used for analyzing trajectories
from other MD codes. Some post-processing tools packaged with
LAMMPS will do these conversions. Scripts provided in the
tools/python directory can extract and massage data in dump files to
make it easier to import into other programs. See the
:doc:`Tools <Tools>` doc page for details on these various options.
* **Visualization:** LAMMPS can produce NETPBM, JPG or PNG snapshot images
on-the-fly via its :doc:`dump image <dump_image>` command and pass
them to an external program, `FFmpeg <https://www.ffmpeg.org>`_ to generate
movies from them. For high-quality, interactive visualization there are
many excellent and free tools available. See the `Other Codes page <http://lammps.sandia.gov/viz.html>`_ page of the LAMMPS website for
visualization packages that can use LAMMPS output data.
* **Plotting:** See the next bullet about Pizza.py as well as the
:doc:`Python <Python_head>` doc page for examples of plotting LAMMPS
output. Scripts provided with the *python* tool in the tools
directory will extract and massage data in log and dump files to make
it easier to analyze and plot. See the :doc:`Tools <Tools>` doc page
for more discussion of the various tools.
* **Pizza.py:** Our group has also written a separate toolkit called
`Pizza.py <http://pizza.sandia.gov>`_ which can do certain kinds of
setup, analysis, plotting, and visualization (via OpenGL) for LAMMPS
simulations. It thus provides some functionality for several of the
above bullets. Pizza.py is written in `Python <http://www.python.org>`_
and is available for download from `this page <http://www.cs.sandia.gov/~sjplimp/download.html>`_.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

49
doc/src/Intro_opensource.rst Normal file
View File

@ -0,0 +1,49 @@
LAMMPS open-source license
==========================
LAMMPS is a freely-available open-source code, distributed under the
terms of the `GNU Public License <gnu_>`_, which means you can use or
modify the code however you wish.
LAMMPS comes with no warranty of any kind. As each source file states
in its header, it is a copyrighted code that is distributed free-of-
charge, under the terms of the `GNU Public License <gnu_>`_ (GPL). This
is often referred to as open-source distribution - see
`www.gnu.org <gnuorg_>`_ or `www.opensource.org <opensource_>`_. The legal
text of the GPL is in the LICENSE file included in the LAMMPS
distribution.
.. _gnu: http://www.gnu.org/copyleft/gpl.html
.. _gnuorg: http://www.gnu.org
.. _opensource: http://www.opensource.org
Here is a summary of what the GPL means for LAMMPS users:
(1) Anyone is free to use, modify, or extend LAMMPS in any way they
choose, including for commercial purposes.
(2) If you distribute a modified version of LAMMPS, it must remain
open-source, meaning you distribute it under the terms of the GPL.
You should clearly annotate such a code as a derivative version of
LAMMPS.
(3) If you release any code that includes LAMMPS source code, then it
must also be open-sourced, meaning you distribute it under the terms
of the GPL.
(4) If you give LAMMPS files to someone else, the GPL LICENSE file and
source file headers (including the copyright and GPL notices) should
remain part of the code.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

54
doc/src/Intro_overview.rst Normal file
View File

@ -0,0 +1,54 @@
Overview of LAMMPS
==================
LAMMPS is a classical molecular dynamics (MD) code that models
ensembles of particles in a liquid, solid, or gaseous state. It can
model atomic, polymeric, biological, solid-state (metals, ceramics,
oxides), granular, coarse-grained, or macroscopic systems using a
variety of interatomic potentials (force fields) and boundary
conditions. It can model 2d or 3d systems with only a few particles
up to millions or billions.
LAMMPS can be built and run on a laptop or desktop machine, but is
designed for parallel computers. It will run on any parallel machine
that supports the `MPI <mpi_>`_ message-passing library. This includes
shared-memory boxes and distributed-memory clusters and
supercomputers.
.. _mpi: http://www-unix.mcs.anl.gov/mpi
LAMMPS is written in C++. Earlier versions were written in F77 and
F90. See the `History page <http://lammps.sandia.gov/history.html>`_ of
the website for details. All versions can be downloaded from the
`LAMMPS website <lws_>`_.
LAMMPS is designed to be easy to modify or extend with new
capabilities, such as new force fields, atom types, boundary
conditions, or diagnostics. See the :doc:`Modify <Modify>` doc page for
more details.
In the most general sense, LAMMPS integrates Newton's equations of
motion for a collection of interacting particles. A single particle
can be an atom or molecule or electron, a coarse-grained cluster of
atoms, or a mesoscopic or macroscopic clump of material. The
interaction models that LAMMPS includes are mostly short-range in
nature; some long-range models are included as well.
LAMMPS uses neighbor lists to keep track of nearby particles. The
lists are optimized for systems with particles that are repulsive at
short distances, so that the local density of particles never becomes
too large. This is in contrast to methods used for modeling plasma
or gravitational bodies (e.g. galaxy formation).
On parallel machines, LAMMPS uses spatial-decomposition techniques to
partition the simulation domain into small sub-domains of equal
computational cost, one of which is assigned to each processor.
Processors communicate and store "ghost" atom information for atoms
that border their sub-domain.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

39
doc/src/Intro_website.rst Normal file
View File

@ -0,0 +1,39 @@
Additional website links
========================
The `LAMMPS website <lws_>`_ has a variety of additional info about
LAMMPS, beyond what is in this manual. Some of the other pages in
this Intr are included in this list.
* `Brief intro and recently added significant features <lws_>`_
* `List of features <http://lammps.sandia.gov/features.html>`_
* `List of non-features <http://lammps.sandia.gov/non_features.html>`_
* `Recent bug fixes and new features <http://lammps.sandia.gov/bug.html>`_
* `Download info <http://lammps.sandia.gov/download.html>`_
* `GitHub site <https://github.com/lammps/lammps>`_
* `SourceForge site <https://sourceforge.net/projects/lammps>`_
* `LAMMPS open-source license <http://lammps.sandia.gov/open_source.html>`_
* `Glossary of MD terms relevant to LAMMPS <http://lammps.sandia.gov/glossary.html>`_
* `LAMMPS highlights with images <http://lammps.sandia.gov/pictures.html>`_
* `LAMMPS highlights with movies <http://lammps.sandia.gov/movies.html>`_
* `Mail list <http://lammps.sandia.gov/mail.html>`_
* `Workshops <http://lammps.sandia.gov/workshops.html>`_
* `Tutorials <http://lammps.sandia.gov/tutorials.html>`_
* `Developer guide <http://lammps.sandia.gov/Developer.pdf>`_
* `Pre- and post-processing tools for LAMMPS <http://lammps.sandia.gov/prepost.html>`_
* `Other software usable with LAMMPS <http://lammps.sandia.gov/offsite.html>`_
* `Viz tools usable with LAMMPS <http://lammps.sandia.gov/viz.html>`_
* `Benchmark performance <http://lammps.sandia.gov/bench.html>`_
* `Publications that have cited LAMMPS <http://lammps.sandia.gov/papers.html>`_
* `Authors of LAMMPS <http://lammps.sandia.gov/authors.html>`_
* `History of LAMMPS development <http://lammps.sandia.gov/history.html>`_
* `Funding for LAMMPS <http://lammps.sandia.gov/funding.html>`_
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

92
doc/src/Manual.rst Normal file
View File

@ -0,0 +1,92 @@
LAMMPS Documentation
####################
|version| version
*****************
:doc:`What is a LAMMPS version? <Manual_version>`
LAMMPS stands for Large-scale Atomic/Molecular Massively Parallel
Simulator.
LAMMPS is a classical molecular dynamics simulation code with a focus
on materials modeling. It was designed to run efficiently on parallel
computers. It was developed originally at Sandia National
Laboratories, a US Department of Energy facility. The majority of
funding for LAMMPS has come from the US Department of Energy (DOE).
LAMMPS is an open-source code, distributed freely under the terms of
the GNU Public License (GPL).
The `LAMMPS website <lws_>`_ has a variety of information about the code.
It includes links to an on-line version of this manual, a `mailing list <http://lammps.sandia.gov/mail.html>`_ where users can post
questions, and a `GitHub site <https://github.com/lammps/lammps>`_ where
all LAMMPS development is coordinated.
----------
The content for this manual is part of the LAMMPS distribution. You
can build a local copy of the Manual as HTML pages or a PDF file, by
following the steps on the :doc:`Manual build <Manual_build>` doc page.
There is also a `Developer.pdf <Developer.pdf>`_ document which gives
a brief description of the basic code structure of LAMMPS.
----------
Once you are familiar with LAMMPS, you may want to bookmark :doc:`this page <Commands>` since it gives quick access to a doc page for
every LAMMPS command.
.. toctree::
:maxdepth: 2
:numbered: 3
:caption: User Documentation
:name: userdoc
:includehidden:
Intro
Install
Build
Run_head
Commands
Packages
Speed
Howto
Examples
Tools
Modify
Python_head
Errors
Manual_build
.. toctree::
:caption: Index
:name: index
:hidden:
commands_list
fixes
computes
pairs
bonds
angles
dihedrals
impropers
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`
.. raw:: html
</BODY>
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

124
doc/src/Manual.txt
View File

@ -1,124 +0,0 @@
<!-- HTML_ONLY -->
<HEAD>
<TITLE>LAMMPS Users Manual</TITLE>
<META NAME="docnumber" CONTENT="19 Sep 2019 version">
<META NAME="author" CONTENT="http://lammps.sandia.gov - Sandia National Laboratories">
<META NAME="copyright" CONTENT="Copyright (2003) Sandia Corporation. This software and manual is distributed under the GNU General Public License.">
</HEAD>
<BODY>
<H1></H1>
<!-- END_HTML_ONLY -->
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Commands_all.html#comm)
:line
LAMMPS Documentation :c,h1
19 Sep 2019 version :c,h2
"What is a LAMMPS version?"_Manual_version.html
LAMMPS stands for Large-scale Atomic/Molecular Massively Parallel
Simulator.
LAMMPS is a classical molecular dynamics simulation code with a focus
on materials modeling. It was designed to run efficiently on parallel
computers. It was developed originally at Sandia National
Laboratories, a US Department of Energy facility. The majority of
funding for LAMMPS has come from the US Department of Energy (DOE).
LAMMPS is an open-source code, distributed freely under the terms of
the GNU Public License (GPL).
The "LAMMPS website"_lws has a variety of information about the code.
It includes links to an on-line version of this manual, a "mailing
list"_http://lammps.sandia.gov/mail.html where users can post
questions, and a "GitHub site"_https://github.com/lammps/lammps where
all LAMMPS development is coordinated.
:line
The content for this manual is part of the LAMMPS distribution. You
can build a local copy of the Manual as HTML pages or a PDF file, by
following the steps on the "Manual build"_Manual_build.html doc page.
There is also a "Developer.pdf"_Developer.pdf document which gives
a brief description of the basic code structure of LAMMPS.
:line
Once you are familiar with LAMMPS, you may want to bookmark "this
page"_Commands.html since it gives quick access to a doc page for
every LAMMPS command.
<!-- RST
.. toctree::
:maxdepth: 2
:numbered: 3
:caption: User Documentation
:name: userdoc
:includehidden:
Intro
Install
Build
Run_head
Commands
Packages
Speed
Howto
Examples
Tools
Modify
Python_head
Errors
Manual_build
.. toctree::
:caption: Index
:name: index
:hidden:
commands_list
fixes
computes
pairs
bonds
angles
dihedrals
impropers
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`
END_RST -->
<!-- HTML_ONLY -->
"Introduction"_Intro.html :olb,l
"Install LAMMPS"_Install.html :l
"Build LAMMPS"_Build.html :l
"Run LAMMPS"_Run_head.html :l
"Commands"_Commands.html :l
"Optional packages"_Packages.html :l
"Accelerate performance"_Speed.html :l
"How-to discussions"_Howto.html :l
"Example scripts"_Examples.html :l
"Auxiliary tools"_Tools.html :l
"Modify & extend LAMMPS"_Modify.html :l
"Use Python with LAMMPS"_Python_head.html :l
"Errors"_Errors.html :l
"Building the LAMMPS manual"_Manual_build.html :l
:ole
<!-- END_HTML_ONLY -->
</BODY>

141
doc/src/Manual_build.rst Normal file
View File

@ -0,0 +1,141 @@
Building the LAMMPS manual
**************************
Depending on how you obtained LAMMPS, the doc directory has 2 or 3
sub-directories and optionally 2 PDF files and 2 e-book format files:
.. parsed-literal::
src # content files for LAMMPS documentation
html # HTML version of the LAMMPS manual (see html/Manual.html)
tools # tools and settings for building the documentation
Manual.pdf # large PDF version of entire manual
Developer.pdf # small PDF with info about how LAMMPS is structured
LAMMPS.epub # Manual in ePUB e-book format
LAMMPS.mobi # Manual in MOBI e-book format
If you downloaded LAMMPS as a tarball from the web site, all these
directories and files should be included.
If you downloaded LAMMPS from the public SVN or Git repositories, then
the HTML and PDF files are not included. Instead you need to create
them, in one of two ways:
a. You can "fetch" the current HTML and PDF files from the LAMMPS web site.
Just type "make fetch". This should create a html\_www dir and
Manual\_www.pdf/Developer\_www.pdf files. Note that if new LAMMPS features
have been added more recently than the date of your version, the fetched
documentation will include those changes (but your source code will not, unless
you update your local repository).
b. You can build the HTML and PDF files yourself, by typing "make
html" followed by "make pdf". Note that the PDF make requires the
HTML files already exist. This requires various tools including
Sphinx, which the build process will attempt to download and install
on your system, if not already available. See more details below.
----------
The generation of all documentation is managed by the Makefile in
the doc dir.
.. code-block:: bash
Documentation Build Options:
make html # generate HTML in html dir using Sphinx
make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf)
# in doc dir via htmldoc and pdflatex
make fetch # fetch HTML doc pages and 2 PDF files from web site
# as a tarball and unpack into html dir and 2 PDFs
make epub # generate LAMMPS.epub in ePUB format using Sphinx
make mobi # generate LAMMPS.mobi in MOBI format using ebook-convert
make clean # remove intermediate RST files created by HTML build
make clean-all # remove entire build folder and any cached data
make anchor\_check # check for duplicate anchor labels
make spelling # spell-check the manual
----------
Installing prerequisites for HTML build
=======================================
To run the HTML documentation build toolchain, Python 3 and virtualenv
have to be installed. Here are instructions for common setups:
Ubuntu
------
.. code-block:: bash
sudo apt-get install python-virtualenv
Fedora (up to version 21) and Red Hat Enterprise Linux or CentOS (up to version 7.x)
------------------------------------------------------------------------------------
.. code-block:: bash
sudo yum install python3-virtualenv
Fedora (since version 22)
-------------------------
.. code-block:: bash
sudo dnf install python3-virtualenv
MacOS X
-------
Python 3
^^^^^^^^
Download the latest Python 3 MacOS X package from
`https://www.python.org <https://www.python.org>`_
and install it. This will install both Python 3
and pip3.
virtualenv
^^^^^^^^^^
Once Python 3 is installed, open a Terminal and type
.. code-block:: bash
pip3 install virtualenv
This will install virtualenv from the Python Package Index.
----------
Installing prerequisites for epub build
=======================================
ePUB
----
Same as for HTML. This uses the same tools and configuration
files as the HTML tree.
For converting the generated ePUB file to a MOBI format file
(for e-book readers like Kindle, that cannot read ePUB), you
also need to have the 'ebook-convert' tool from the "calibre"
software installed. `http://calibre-ebook.com/ <http://calibre-ebook.com/>`_
You first create the ePUB file and then convert it with 'make mobi'
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

133
doc/src/Manual_build.txt
View File

@ -1,133 +0,0 @@
"Previous Section"_Errors.html - "LAMMPS WWW Site"_lws -
"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next
Section"_Manual.html :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Commands_all.html)
:line
Building the LAMMPS manual :h2
Depending on how you obtained LAMMPS, the doc directory has 2 or 3
sub-directories and optionally 2 PDF files and 2 e-book format files:
src # content files for LAMMPS documentation
html # HTML version of the LAMMPS manual (see html/Manual.html)
tools # tools and settings for building the documentation
Manual.pdf # large PDF version of entire manual
Developer.pdf # small PDF with info about how LAMMPS is structured
LAMMPS.epub # Manual in ePUB e-book format
LAMMPS.mobi # Manual in MOBI e-book format :pre
If you downloaded LAMMPS as a tarball from the web site, all these
directories and files should be included.
If you downloaded LAMMPS from the public SVN or Git repositories, then
the HTML and PDF files are not included. Instead you need to create
them, in one of three ways:
(a) You can "fetch" the current HTML and PDF files from the LAMMPS web
site. Just type "make fetch". This should create a html_www dir and
Manual_www.pdf/Developer_www.pdf files. Note that if new LAMMPS
features have been added more recently than the date of your version,
the fetched documentation will include those changes (but your source
code will not, unless you update your local repository).
(b) You can build the HTML and PDF files yourself, by typing "make
html" followed by "make pdf". Note that the PDF make requires the
HTML files already exist. This requires various tools including
Sphinx, which the build process will attempt to download and install
on your system, if not already available. See more details below.
(c) You can generate an older, simpler, less-fancy style of HTML
documentation by typing "make old". This will create an "old"
directory. This can be useful if (b) does not work on your box for
some reason, or you want to quickly view the HTML version of a doc
page you have created or edited yourself within the src directory.
E.g. if you are planning to submit a new feature to LAMMPS.
:line
The generation of all documentation is managed by the Makefile in
the doc dir.
Documentation Build Options: :pre
make html # generate HTML in html dir using Sphinx
make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf)
# in doc dir via htmldoc and pdflatex
make old # generate old-style HTML pages in old dir via txt2html
make fetch # fetch HTML doc pages and 2 PDF files from web site
# as a tarball and unpack into html dir and 2 PDFs
make epub # generate LAMMPS.epub in ePUB format using Sphinx
make mobi # generate LAMMPS.mobi in MOBI format using ebook-convert
make clean # remove intermediate RST files created by HTML build
make clean-all # remove entire build folder and any cached data :pre
make anchor_check # check for duplicate anchor labels
make spelling # spell-check the manual
:line
Installing prerequisites for HTML build :h3
To run the HTML documentation build toolchain, Python 3 and virtualenv
have to be installed. Here are instructions for common setups:
Ubuntu :h4
sudo apt-get install python-virtualenv :pre
Fedora (up to version 21) and Red Hat Enterprise Linux or CentOS (up to version 7.x) :h4
sudo yum install python3-virtualenv :pre
Fedora (since version 22) :h4
sudo dnf install python3-virtualenv :pre
MacOS X :h4
Python 3 :h5
Download the latest Python 3 MacOS X package from
"https://www.python.org"_https://www.python.org
and install it. This will install both Python 3
and pip3.
virtualenv :h5
Once Python 3 is installed, open a Terminal and type
pip3 install virtualenv :pre
This will install virtualenv from the Python Package Index.
:line
Installing prerequisites for PDF build
Building the PDF manual requires a working C++ compiler (to
compile the txt2html tool and a working installation of
"HTMLDOC"_https://www.msweet.org/htmldoc/
HTMLDOC has its own list of prerequisites, but in most cases
you can install a binary package of it either through your
Linux package manager or MacOS (dmg) and Windows installer
(msi) packages from its
"GitHub releases page at"_https://github.com/michaelrsweet/htmldoc/releases
:line
Installing prerequisites for epub build :h3
ePUB :h4
Same as for HTML. This uses the same tools and configuration
files as the HTML tree.
For converting the generated ePUB file to a MOBI format file
(for e-book readers like Kindle, that cannot read ePUB), you
also need to have the 'ebook-convert' tool from the "calibre"
software installed. "http://calibre-ebook.com/"_http://calibre-ebook.com/
You first create the ePUB file and then convert it with 'make mobi'

28
doc/src/Manual_version.rst Normal file
View File

@ -0,0 +1,28 @@
What does a LAMMPS version mean
===============================
The LAMMPS "version" is the date when it was released, such as 1 May
2014. LAMMPS is updated continuously. Whenever we fix a bug or add a
feature, we release it in the next *patch* release, which are
typically made every couple of weeks. Info on patch releases are on
`this website page <http://lammps.sandia.gov/bug.html>`_. Every few
months, the latest patch release is subjected to more thorough testing
and labeled as a *stable* version.
Each version of LAMMPS contains all the features and bug-fixes up to
and including its version date.
The version date is printed to the screen and logfile every time you
run LAMMPS. It is also in the file src/version.h and in the LAMMPS
directory name created when you unpack a tarball. And it is on the
first page of the :doc:`manual <Manual>`.
* If you browse the HTML doc pages on the LAMMPS WWW site, they always
describe the most current patch release of LAMMPS.
* If you browse the HTML doc pages included in your tarball, they
describe the version you have, which may be older.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

40
doc/src/Modify.rst Normal file
View File

@ -0,0 +1,40 @@
Modify & extend LAMMPS
**********************
LAMMPS is designed in a modular fashion so as to be easy to modify and
extend with new functionality. In fact, about 95% of its source code
is add-on files. These doc pages give basic instructions on how to do
this.
If you add a new feature to LAMMPS and think it will be of interest to
general users, we encourage you to submit it for inclusion in LAMMPS
as a pull request on our `GitHub site <https://github.com/lammps/lammps>`_, after reading the :doc:`Modify contribute <Modify_contribute>` doc page.
.. toctree::
:maxdepth: 1
Modify_overview
Modify_contribute
.. toctree::
:maxdepth: 1
Modify_atom
Modify_pair
Modify_bond
Modify_compute
Modify_fix
Modify_command
Modify_dump
Modify_kspace
Modify_min
Modify_region
Modify_body
Modify_thermo
Modify_variable
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

124
doc/src/Modify_atom.rst Normal file
View File

@ -0,0 +1,124 @@
Atom styles
===========
Classes that define an :doc:`atom style <atom_style>` are derived from
the AtomVec class and managed by the Atom class. The atom style
determines what attributes are associated with an atom. A new atom
style can be created if one of the existing atom styles does not
define all the attributes you need to store and communicate with
atoms.
Atom\_vec\_atomic.cpp is a simple example of an atom style.
Here is a brief description of methods you define in your new derived
class. See atom\_vec.h for details.
+-------------------------+--------------------------------------------------------------------------------+
| init | one time setup (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| grow | re-allocate atom arrays to longer lengths (required) |
+-------------------------+--------------------------------------------------------------------------------+
| grow\_reset | make array pointers in Atom and AtomVec classes consistent (required) |
+-------------------------+--------------------------------------------------------------------------------+
| copy | copy info for one atom to another atom's array locations (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack\_comm | store an atom's info in a buffer communicated every timestep (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack\_comm\_vel | add velocity info to communication buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack\_comm\_hybrid | store extra info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack\_comm | retrieve an atom's info from the buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack\_comm\_vel | also retrieve velocity info (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack\_comm\_hybrid | retrieve extra info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| pack\_reverse | store an atom's info in a buffer communicating partial forces (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack\_reverse\_hybrid | store extra info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack\_reverse | retrieve an atom's info from the buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack\_reverse\_hybrid | retrieve extra info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| pack\_border | store an atom's info in a buffer communicated on neighbor re-builds (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack\_border\_vel | add velocity info to buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack\_border\_hybrid | store extra info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack\_border | retrieve an atom's info from the buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack\_border\_vel | also retrieve velocity info (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack\_border\_hybrid | retrieve extra info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| pack\_exchange | store all an atom's info to migrate to another processor (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack\_exchange | retrieve an atom's info from the buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| size\_restart | number of restart quantities associated with proc's atoms (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack\_restart | pack atom quantities into a buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack\_restart | unpack atom quantities from a buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| create\_atom | create an individual atom of this style (required) |
+-------------------------+--------------------------------------------------------------------------------+
| data\_atom | parse an atom line from the data file (required) |
+-------------------------+--------------------------------------------------------------------------------+
| data\_atom\_hybrid | parse additional atom info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| data\_vel | parse one line of velocity information from data file (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| data\_vel\_hybrid | parse additional velocity data unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| memory\_usage | tally memory allocated by atom arrays (required) |
+-------------------------+--------------------------------------------------------------------------------+
The constructor of the derived class sets values for several variables
that you must set when defining a new atom style, which are documented
in atom\_vec.h. New atom arrays are defined in atom.cpp. Search for
the word "customize" and you will find locations you will need to
modify.
.. note::
It is possible to add some attributes, such as a molecule ID, to
atom styles that do not have them via the :doc:`fix property/atom <fix_property_atom>` command. This command also
allows new custom attributes consisting of extra integer or
floating-point values to be added to atoms. See the :doc:`fix property/atom <fix_property_atom>` doc page for examples of cases
where this is useful and details on how to initialize, access, and
output the custom values.
New :doc:`pair styles <pair_style>`, :doc:`fixes <fix>`, or
:doc:`computes <compute>` can be added to LAMMPS, as discussed below.
The code for these classes can use the per-atom properties defined by
fix property/atom. The Atom class has a find\_custom() method that is
useful in this context:
.. parsed-literal::
int index = atom->find_custom(char \*name, int &flag);
The "name" of a custom attribute, as specified in the :doc:`fix property/atom <fix_property_atom>` command, is checked to verify
that it exists and its index is returned. The method also sets flag =
0/1 depending on whether it is an integer or floating-point attribute.
The vector of values associated with the attribute can then be
accessed using the returned index as
.. parsed-literal::
int \*ivector = atom->ivector[index];
double \*dvector = atom->dvector[index];
Ivector or dvector are vectors of length Nlocal = # of owned atoms,
which store the attributes of individual atoms.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

40
doc/src/Modify_body.rst Normal file
View File

@ -0,0 +1,40 @@
Body styles
===========
Classes that define body particles are derived from the Body class.
Body particles can represent complex entities, such as surface meshes
of discrete points, collections of sub-particles, deformable objects,
etc.
See the :doc:`Howto body <Howto_body>` doc page for an overview of using
body particles and the various body styles LAMMPS supports. New
styles can be created to add new kinds of body particles to LAMMPS.
Body\_nparticle.cpp is an example of a body particle that is treated as
a rigid body containing N sub-particles.
Here is a brief description of methods you define in your new derived
class. See body.h for details.
+----------------------+-----------------------------------------------------------+
| data\_body | process a line from the Bodies section of a data file |
+----------------------+-----------------------------------------------------------+
| noutrow | number of sub-particles output is generated for |
+----------------------+-----------------------------------------------------------+
| noutcol | number of values per-sub-particle output is generated for |
+----------------------+-----------------------------------------------------------+
| output | output values for the Mth sub-particle |
+----------------------+-----------------------------------------------------------+
| pack\_comm\_body | body attributes to communicate every timestep |
+----------------------+-----------------------------------------------------------+
| unpack\_comm\_body | unpacking of those attributes |
+----------------------+-----------------------------------------------------------+
| pack\_border\_body | body attributes to communicate when reneighboring is done |
+----------------------+-----------------------------------------------------------+
| unpack\_border\_body | unpacking of those attributes |
+----------------------+-----------------------------------------------------------+
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

41
doc/src/Modify_bond.rst Normal file
View File

@ -0,0 +1,41 @@
Bond, angle, dihedral, improper styles
======================================
Classes that compute molecular interactions are derived from the Bond,
Angle, Dihedral, and Improper classes. New styles can be created to
add new potentials to LAMMPS.
Bond\_harmonic.cpp is the simplest example of a bond style. Ditto for
the harmonic forms of the angle, dihedral, and improper style
commands.
Here is a brief description of common methods you define in your
new derived class. See bond.h, angle.h, dihedral.h, and improper.h
for details and specific additional methods.
+-----------------------+---------------------------------------------------------------------------+
| init | check if all coefficients are set, calls *init\_style* (optional) |
+-----------------------+---------------------------------------------------------------------------+
| init\_style | check if style specific conditions are met (optional) |
+-----------------------+---------------------------------------------------------------------------+
| compute | compute the molecular interactions (required) |
+-----------------------+---------------------------------------------------------------------------+
| settings | apply global settings for all types (optional) |
+-----------------------+---------------------------------------------------------------------------+
| coeff | set coefficients for one type (required) |
+-----------------------+---------------------------------------------------------------------------+
| equilibrium\_distance | length of bond, used by SHAKE (required, bond only) |
+-----------------------+---------------------------------------------------------------------------+
| equilibrium\_angle | opening of angle, used by SHAKE (required, angle only) |
+-----------------------+---------------------------------------------------------------------------+
| write & read\_restart | writes/reads coeffs to restart files (required) |
+-----------------------+---------------------------------------------------------------------------+
| single | force and energy of a single bond or angle (required, bond or angle only) |
+-----------------------+---------------------------------------------------------------------------+
| memory\_usage | tally memory allocated by the style (optional) |
+-----------------------+---------------------------------------------------------------------------+
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

25
doc/src/Modify_command.rst Normal file
View File

@ -0,0 +1,25 @@
Input script command style
==========================
New commands can be added to LAMMPS input scripts by adding new
classes that have a "command" method. For example, the create\_atoms,
read\_data, velocity, and run commands are all implemented in this
fashion. When such a command is encountered in the LAMMPS input
script, LAMMPS simply creates a class with the corresponding name,
invokes the "command" method of the class, and passes it the arguments
from the input script. The command method can perform whatever
operations it wishes on LAMMPS data structures.
The single method your new class must define is as follows:
+---------+-----------------------------------------+
| command | operations performed by the new command |
+---------+-----------------------------------------+
Of course, the new class can define other methods and variables as
needed.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

62
doc/src/Modify_compute.rst Normal file
View File

@ -0,0 +1,62 @@
Compute styles
==============
Classes that compute scalar and vector quantities like temperature
and the pressure tensor, as well as classes that compute per-atom
quantities like kinetic energy and the centro-symmetry parameter
are derived from the Compute class. New styles can be created
to add new calculations to LAMMPS.
Compute\_temp.cpp is a simple example of computing a scalar
temperature. Compute\_ke\_atom.cpp is a simple example of computing
per-atom kinetic energy.
Here is a brief description of methods you define in your new derived
class. See compute.h for details.
+-----------------------+------------------------------------------------------------------+
| init | perform one time setup (required) |
+-----------------------+------------------------------------------------------------------+
| init\_list | neighbor list setup, if needed (optional) |
+-----------------------+------------------------------------------------------------------+
| compute\_scalar | compute a scalar quantity (optional) |
+-----------------------+------------------------------------------------------------------+
| compute\_vector | compute a vector of quantities (optional) |
+-----------------------+------------------------------------------------------------------+
| compute\_peratom | compute one or more quantities per atom (optional) |
+-----------------------+------------------------------------------------------------------+
| compute\_local | compute one or more quantities per processor (optional) |
+-----------------------+------------------------------------------------------------------+
| pack\_comm | pack a buffer with items to communicate (optional) |
+-----------------------+------------------------------------------------------------------+
| unpack\_comm | unpack the buffer (optional) |
+-----------------------+------------------------------------------------------------------+
| pack\_reverse | pack a buffer with items to reverse communicate (optional) |
+-----------------------+------------------------------------------------------------------+
| unpack\_reverse | unpack the buffer (optional) |
+-----------------------+------------------------------------------------------------------+
| remove\_bias | remove velocity bias from one atom (optional) |
+-----------------------+------------------------------------------------------------------+
| remove\_bias\_all | remove velocity bias from all atoms in group (optional) |
+-----------------------+------------------------------------------------------------------+
| restore\_bias | restore velocity bias for one atom after remove\_bias (optional) |
+-----------------------+------------------------------------------------------------------+
| restore\_bias\_all | same as before, but for all atoms in group (optional) |
+-----------------------+------------------------------------------------------------------+
| pair\_tally\_callback | callback function for *tally*\ -style computes (optional). |
+-----------------------+------------------------------------------------------------------+
| memory\_usage | tally memory usage (optional) |
+-----------------------+------------------------------------------------------------------+
Tally-style computes are a special case, as their computation is done
in two stages: the callback function is registered with the pair style
and then called from the Pair::ev\_tally() function, which is called for
each pair after force and energy has been computed for this pair. Then
the tallied values are retrieved with the standard compute\_scalar or
compute\_vector or compute\_peratom methods. The USER-TALLY package
provides *examples*\ \_compute\_tally.html for utilizing this mechanism.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Commands_all.html

Some files were not shown because too many files have changed in this diff Show More