jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@14532 f3b2605a-c512-4ea7-a41b-209d697bcdaa

This commit is contained in:
sjplimp 2016-02-02 16:05:07 +00:00
parent 0766f95adc
commit 9cf43f2a0b
502 changed files with 106606 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
doc/_sources/Manual.txt Normal file
View File

@ -0,0 +1,104 @@
.. raw:: html
<H1></H1>
LAMMPS Documentation
====================
29 Jan 2016 version
-------------------
Version info:
-------------
The LAMMPS "version" is the date when it was released, such as 1 May
2010. LAMMPS is updated continuously. Whenever we fix a bug or add a
feature, we release it immediately, and post a notice on `this page of the WWW site <bug_>`_. Each dated copy of LAMMPS contains all the
features and bug-fixes up to and including that 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 at the top of
the first page of the manual (this page).
* If you browse the HTML doc pages on the LAMMPS WWW site, they always
describe the most current version of LAMMPS.
* If you browse the HTML doc pages included in your tarball, they
describe the version you have.
* The `PDF file <Manual.pdf>`_ on the WWW site or in the tarball is updated
about once per month. This is because it is large, and we don't want
it to be part of every patch.
* There is also a `Developer.pdf <Developer.pdf>`_ file in the doc
directory, which describes the internal structure and algorithms of
LAMMPS.
LAMMPS stands for Large-scale Atomic/Molecular Massively Parallel
Simulator.
LAMMPS is a classical molecular dynamics simulation code designed to
run efficiently on parallel computers. It was developed at Sandia
National Laboratories, a US Department of Energy facility, with
funding from the DOE. It is an open-source code, distributed freely
under the terms of the GNU Public License (GPL).
The primary developers of LAMMPS are `Steve Plimpton <sjp_>`_, Aidan
Thompson, and Paul Crozier who can be contacted at
sjplimp,athomps,pscrozi at sandia.gov. The `LAMMPS WWW Site <lws_>`_ at
http://lammps.sandia.gov has more information about the code and its
uses.
.. _bug: http://lammps.sandia.gov/bug.html
.. _sjp: http://www.sandia.gov/~sjplimp
----------
The LAMMPS documentation is organized into the following sections. If
you find errors or omissions in this manual or have suggestions for
useful information to add, please send an email to the developers so
we can improve the LAMMPS documentation.
Once you are familiar with LAMMPS, you may want to bookmark :ref:`this page <comm>` at Section_commands.html#comm since
it gives quick access to documentation for all LAMMPS commands.
`PDF file <Manual.pdf>`_ of the entire manual, generated by
`htmldoc <http://freecode.com/projects/htmldoc>`_
.. toctree::
:maxdepth: 2
:numbered:
Section_intro
Section_start
Section_commands
Section_packages
Section_accelerate
Section_howto
Section_example
Section_perf
Section_tools
Section_modify
Section_python
Section_errors
Section_history
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`
.. raw:: html
</BODY>
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

430
doc/_sources/Section_accelerate.txt Normal file
View File

@ -0,0 +1,430 @@
Accelerating LAMMPS performance
===============================
This section describes various methods for improving LAMMPS
performance for different classes of problems running on different
kinds of machines.
There are two thrusts to the discussion that follows. The
first is using code options that implement alternate algorithms
that can speed-up a simulation. The second is to use one
of the several accelerator packages provided with LAMMPS that
contain code optimized for certain kinds of hardware, including
multi-core CPUs, GPUs, and Intel Xeon Phi coprocessors.
* 5.1 :ref:`Measuring performance <acc_1>`
* 5.2 :ref:`Algorithms and code options to boost performace <acc_2>`
* 5.3 :ref:`Accelerator packages with optimized styles <acc_3>`
* 5.3.1 :doc:`USER-CUDA package <accelerate_cuda>`
* 5.3.2 :doc:`GPU package <accelerate_gpu>`
* 5.3.3 :doc:`USER-INTEL package <accelerate_intel>`
* 5.3.4 :doc:`KOKKOS package <accelerate_kokkos>`
* 5.3.5 :doc:`USER-OMP package <accelerate_omp>`
* 5.3.6 :doc:`OPT package <accelerate_opt>`
* 5.4 :ref:`Comparison of various accelerator packages <acc_4>`
The `Benchmark page <http://lammps.sandia.gov/bench.html>`_ of the LAMMPS
web site gives performance results for the various accelerator
packages discussed in Section 5.2, for several of the standard LAMMPS
benchmark problems, as a function of problem size and number of
compute nodes, on different hardware platforms.
.. _acc_1:
Measuring performance
---------------------------------
Before trying to make your simulation run faster, you should
understand how it currently performs and where the bottlenecks are.
The best way to do this is run the your system (actual number of
atoms) for a modest number of timesteps (say 100 steps) on several
different processor counts, including a single processor if possible.
Do this for an equilibrium version of your system, so that the
100-step timings are representative of a much longer run. There is
typically no need to run for 1000s of timesteps to get accurate
timings; you can simply extrapolate from short runs.
For the set of runs, look at the timing data printed to the screen and
log file at the end of each LAMMPS run. :ref:`This section <start_8>` of the manual has an overview.
Running on one (or a few processors) should give a good estimate of
the serial performance and what portions of the timestep are taking
the most time. Running the same problem on a few different processor
counts should give an estimate of parallel scalability. I.e. if the
simulation runs 16x faster on 16 processors, its 100% parallel
efficient; if it runs 8x faster on 16 processors, it's 50% efficient.
The most important data to look at in the timing info is the timing
breakdown and relative percentages. For example, trying different
options for speeding up the long-range solvers will have little impact
if they only consume 10% of the run time. If the pairwise time is
dominating, you may want to look at GPU or OMP versions of the pair
style, as discussed below. Comparing how the percentages change as
you increase the processor count gives you a sense of how different
operations within the timestep are scaling. Note that if you are
running with a Kspace solver, there is additional output on the
breakdown of the Kspace time. For PPPM, this includes the fraction
spent on FFTs, which can be communication intensive.
Another important detail in the timing info are the histograms of
atoms counts and neighbor counts. If these vary widely across
processors, you have a load-imbalance issue. This often results in
inaccurate relative timing data, because processors have to wait when
communication occurs for other processors to catch up. Thus the
reported times for "Communication" or "Other" may be higher than they
really are, due to load-imbalance. If this is an issue, you can
uncomment the MPI_Barrier() lines in src/timer.cpp, and recompile
LAMMPS, to obtain synchronized timings.
----------
.. _acc_2:
General strategies
------------------------------
.. note::
this section 5.2 is still a work in progress
Here is a list of general ideas for improving simulation performance.
Most of them are only applicable to certain models and certain
bottlenecks in the current performance, so let the timing data you
generate be your guide. It is hard, if not impossible, to predict how
much difference these options will make, since it is a function of
problem size, number of processors used, and your machine. There is
no substitute for identifying performance bottlenecks, and trying out
various options.
* rRESPA
* 2-FFT PPPM
* Staggered PPPM
* single vs double PPPM
* partial charge PPPM
* verlet/split run style
* processor command for proc layout and numa layout
* load-balancing: balance and fix balance
2-FFT PPPM, also called *analytic differentiation* or *ad* PPPM, uses
2 FFTs instead of the 4 FFTs used by the default *ik differentiation*
PPPM. However, 2-FFT PPPM also requires a slightly larger mesh size to
achieve the same accuracy as 4-FFT PPPM. For problems where the FFT
cost is the performance bottleneck (typically large problems running
on many processors), 2-FFT PPPM may be faster than 4-FFT PPPM.
Staggered PPPM performs calculations using two different meshes, one
shifted slightly with respect to the other. This can reduce force
aliasing errors and increase the accuracy of the method, but also
doubles the amount of work required. For high relative accuracy, using
staggered PPPM allows one to half the mesh size in each dimension as
compared to regular PPPM, which can give around a 4x speedup in the
kspace time. However, for low relative accuracy, using staggered PPPM
gives little benefit and can be up to 2x slower in the kspace
time. For example, the rhodopsin benchmark was run on a single
processor, and results for kspace time vs. relative accuracy for the
different methods are shown in the figure below. For this system,
staggered PPPM (using ik differentiation) becomes useful when using a
relative accuracy of slightly greater than 1e-5 and above.
.. image:: JPG/rhodo_staggered.jpg
:align: center
.. note::
Using staggered PPPM may not give the same increase in accuracy
of energy and pressure as it does in forces, so some caution must be
used if energy and/or pressure are quantities of interest, such as
when using a barostat.
----------
.. _acc_3:
Packages with optimized styles
------------------------------------------
Accelerated versions of various :doc:`pair_style <pair_style>`,
:doc:`fixes <fix>`, :doc:`computes <compute>`, and other commands have
been added to LAMMPS, which will typically run faster than the
standard non-accelerated versions. Some require appropriate hardware
to be present on your system, e.g. GPUs or Intel Xeon Phi
coprocessors.
All of these commands are in packages provided with LAMMPS. An
overview of packages is give in :doc:`Section packages <Section_packages>`.
These are the accelerator packages
currently in LAMMPS, either as standard or user packages:
+--------------------------------------+------------------------------------------------+
| :doc:`USER-CUDA <accelerate_cuda>` | for NVIDIA GPUs |
+--------------------------------------+------------------------------------------------+
| :doc:`GPU <accelerate_gpu>` | for NVIDIA GPUs as well as OpenCL support |
+--------------------------------------+------------------------------------------------+
| :doc:`USER-INTEL <accelerate_intel>` | for Intel CPUs and Intel Xeon Phi |
+--------------------------------------+------------------------------------------------+
| :doc:`KOKKOS <accelerate_kokkos>` | for GPUs, Intel Xeon Phi, and OpenMP threading |
+--------------------------------------+------------------------------------------------+
| :doc:`USER-OMP <accelerate_omp>` | for OpenMP threading |
+--------------------------------------+------------------------------------------------+
| :doc:`OPT <accelerate_opt>` | generic CPU optimizations |
+--------------------------------------+------------------------------------------------+
Inverting this list, LAMMPS currently has acceleration support for
three kinds of hardware, via the listed packages:
+----------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| Many-core CPUs | :doc:`USER-INTEL <accelerate_intel>`, :doc:`KOKKOS <accelerate_kokkos>`, :doc:`USER-OMP <accelerate_omp>`, :doc:`OPT <accelerate_opt>` packages |
+----------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| NVIDIA GPUs | :doc:`USER-CUDA <accelerate_cuda>`, :doc:`GPU <accelerate_gpu>`, :doc:`KOKKOS <accelerate_kokkos>` packages |
+----------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
| Intel Phi | :doc:`USER-INTEL <accelerate_intel>`, :doc:`KOKKOS <accelerate_kokkos>` packages |
+----------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
Which package is fastest for your hardware may depend on the size
problem you are running and what commands (accelerated and
non-accelerated) are invoked by your input script. While these doc
pages include performance guidelines, there is no substitute for
trying out the different packages appropriate to your hardware.
Any accelerated style has the same name as the corresponding standard
style, except that a suffix is appended. Otherwise, the syntax for
the command that uses the style is identical, their functionality is
the same, and the numerical results it produces should also be the
same, except for precision and round-off effects.
For example, all of these styles are accelerated variants of the
Lennard-Jones :doc:`pair_style lj/cut <pair_lj>`:
* :doc:`pair_style lj/cut/cuda <pair_lj>`
* :doc:`pair_style lj/cut/gpu <pair_lj>`
* :doc:`pair_style lj/cut/intel <pair_lj>`
* :doc:`pair_style lj/cut/kk <pair_lj>`
* :doc:`pair_style lj/cut/omp <pair_lj>`
* :doc:`pair_style lj/cut/opt <pair_lj>`
To see what accelerate styles are currently available, see
:ref:`Section_commands 5 <cmd_5>` of the manual. The
doc pages for individual commands (e.g. :doc:`pair lj/cut <pair_lj>` or
:doc:`fix nve <fix_nve>`) also list any accelerated variants available
for that style.
To use an accelerator package in LAMMPS, and one or more of the styles
it provides, follow these general steps. Details vary from package to
package and are explained in the individual accelerator doc pages,
listed above:
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| build the accelerator library | only for USER-CUDA and GPU packages |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| install the accelerator package | make yes-opt, make yes-user-intel, etc |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| add compile/link flags to Makefile.machine | in src/MAKE, <br>
only for USER-INTEL, KOKKOS, USER-OMP, OPT packages |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| re-build LAMMPS | make machine |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| run a LAMMPS simulation | lmp_machine < in.script <br>
mpirun -np 32 lmp_machine -in in.script |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| enable the accelerator package | via "-c on" and "-k on" :ref:`command-line switches <start_7>`, <br>
only for USER-CUDA and KOKKOS packages |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| set any needed options for the package | via "-pk" :ref:`command-line switch <start_7>` or
:doc:`package <package>` command, <br>
only if defaults need to be changed |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| use accelerated styles in your input script | via "-sf" :ref:`command-line switch <start_7>` or
:doc:`suffix <suffix>` command |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
Note that the first 4 steps can be done as a single command, using the
src/Make.py tool. This tool is discussed in :ref:`Section 2.4 <start_4>` of the manual, and its use is
illustrated in the individual accelerator sections. Typically these
steps only need to be done once, to create an executable that uses one
or more accelerator packages.
The last 4 steps can all be done from the command-line when LAMMPS is
launched, without changing your input script, as illustrated in the
individual accelerator sections. Or you can add
:doc:`package <package>` and :doc:`suffix <suffix>` commands to your input
script.
.. note::
With a few exceptions, you can build a single LAMMPS executable
with all its accelerator packages installed. Note however that the
USER-INTEL and KOKKOS packages require you to choose one of their
hardware options when building for a specific platform. I.e. CPU or
Phi option for the USER-INTEL package. Or the OpenMP, Cuda, or Phi
option for the KOKKOS package.
These are the exceptions. You cannot build a single executable with:
* both the USER-INTEL Phi and KOKKOS Phi options
* the USER-INTEL Phi or Kokkos Phi option, and either the USER-CUDA or GPU packages
See the examples/accelerate/README and make.list files for sample
Make.py commands that build LAMMPS with any or all of the accelerator
packages. As an example, here is a command that builds with all the
GPU related packages installed (USER-CUDA, GPU, KOKKOS with Cuda),
including settings to build the needed auxiliary USER-CUDA and GPU
libraries for Kepler GPUs:
.. parsed-literal::
Make.py -j 16 -p omp gpu cuda kokkos -cc nvcc wrap=mpi -cuda mode=double arch=35 -gpu mode=double arch=35 \ -kokkos cuda arch=35 lib-all file mpi
The examples/accelerate directory also has input scripts that can be
used with all of the accelerator packages. See its README file for
details.
Likewise, the bench directory has FERMI and KEPLER and PHI
sub-directories with Make.py commands and input scripts for using all
the accelerator packages on various machines. See the README files in
those dirs.
As mentioned above, the `Benchmark page <http://lammps.sandia.gov/bench.html>`_ of the LAMMPS web site gives
performance results for the various accelerator packages for several
of the standard LAMMPS benchmark problems, as a function of problem
size and number of compute nodes, on different hardware platforms.
Here is a brief summary of what the various packages provide. Details
are in the individual accelerator sections.
* Styles with a "cuda" or "gpu" suffix are part of the USER-CUDA or GPU
packages, and can be run on NVIDIA GPUs. The speed-up on a GPU
depends on a variety of factors, discussed in the accelerator
sections.
* Styles with an "intel" suffix are part of the USER-INTEL
package. These styles support vectorized single and mixed precision
calculations, in addition to full double precision. In extreme cases,
this can provide speedups over 3.5x on CPUs. The package also
supports acceleration in "offload" mode to Intel(R) Xeon Phi(TM)
coprocessors. This can result in additional speedup over 2x depending
on the hardware configuration.
* Styles with a "kk" suffix are part of the KOKKOS package, and can be
run using OpenMP on multicore CPUs, on an NVIDIA GPU, or on an Intel
Xeon Phi in "native" mode. The speed-up depends on a variety of
factors, as discussed on the KOKKOS accelerator page.
* Styles with an "omp" suffix are part of the USER-OMP package and allow
a pair-style to be run in multi-threaded mode using OpenMP. This can
be useful on nodes with high-core counts when using less MPI processes
than cores is advantageous, e.g. when running with PPPM so that FFTs
are run on fewer MPI processors or when the many MPI tasks would
overload the available bandwidth for communication.
* Styles with an "opt" suffix are part of the OPT package and typically
speed-up the pairwise calculations of your simulation by 5-25% on a
CPU.
The individual accelerator package doc pages explain:
* what hardware and software the accelerated package requires
* how to build LAMMPS with the accelerated package
* how to run with the accelerated package either via command-line switches or modifying the input script
* speed-ups to expect
* guidelines for best performance
* restrictions
----------
.. _acc_4:
Comparison of various accelerator packages
------------------------------------------------------
.. note::
this section still needs to be re-worked with additional KOKKOS
and USER-INTEL information.
The next section compares and contrasts the various accelerator
options, since there are multiple ways to perform OpenMP threading,
run on GPUs, and run on Intel Xeon Phi coprocessors.
All 3 of these packages accelerate a LAMMPS calculation using NVIDIA
hardware, but they do it in different ways.
As a consequence, for a particular simulation on specific hardware,
one package may be faster than the other. We give guidelines below,
but the best way to determine which package is faster for your input
script is to try both of them on your machine. See the benchmarking
section below for examples where this has been done.
**Guidelines for using each package optimally:**
* The GPU package allows you to assign multiple CPUs (cores) to a single
GPU (a common configuration for "hybrid" nodes that contain multicore
CPU(s) and GPU(s)) and works effectively in this mode. The USER-CUDA
package does not allow this; you can only use one CPU per GPU.
* The GPU package moves per-atom data (coordinates, forces)
back-and-forth between the CPU and GPU every timestep. The USER-CUDA
package only does this on timesteps when a CPU calculation is required
(e.g. to invoke a fix or compute that is non-GPU-ized). Hence, if you
can formulate your input script to only use GPU-ized fixes and
computes, and avoid doing I/O too often (thermo output, dump file
snapshots, restart files), then the data transfer cost of the
USER-CUDA package can be very low, causing it to run faster than the
GPU package.
* The GPU package is often faster than the USER-CUDA package, if the
number of atoms per GPU is smaller. The crossover point, in terms of
atoms/GPU at which the USER-CUDA package becomes faster depends
strongly on the pair style. For example, for a simple Lennard Jones
system the crossover (in single precision) is often about 50K-100K
atoms per GPU. When performing double precision calculations the
crossover point can be significantly smaller.
* Both packages compute bonded interactions (bonds, angles, etc) on the
CPU. This means a model with bonds will force the USER-CUDA package
to transfer per-atom data back-and-forth between the CPU and GPU every
timestep. If the GPU package is running with several MPI processes
assigned to one GPU, the cost of computing the bonded interactions is
spread across more CPUs and hence the GPU package can run faster.
* When using the GPU package with multiple CPUs assigned to one GPU, its
performance depends to some extent on high bandwidth between the CPUs
and the GPU. Hence its performance is affected if full 16 PCIe lanes
are not available for each GPU. In HPC environments this can be the
case if S2050/70 servers are used, where two devices generally share
one PCIe 2.0 16x slot. Also many multi-GPU mainboards do not provide
full 16 lanes to each of the PCIe 2.0 16x slots.
**Differences between the two packages:**
* The GPU package accelerates only pair force, neighbor list, and PPPM
calculations. The USER-CUDA package currently supports a wider range
of pair styles and can also accelerate many fix styles and some
compute styles, as well as neighbor list and PPPM calculations.
* The USER-CUDA package does not support acceleration for minimization.
* The USER-CUDA package does not support hybrid pair styles.
* The USER-CUDA package can order atoms in the neighbor list differently
from run to run resulting in a different order for force accumulation.
* The USER-CUDA package has a limit on the number of atom types that can be
used in a simulation.
* The GPU package requires neighbor lists to be built on the CPU when using
exclusion lists or a triclinic simulation box.
* The GPU package uses more GPU memory than the USER-CUDA package. This
is generally not a problem since typical runs are computation-limited
rather than memory-limited.
Examples
""""""""
The LAMMPS distribution has two directories with sample input scripts
for the GPU and USER-CUDA packages.
* lammps/examples/gpu = GPU package files
* lammps/examples/USER/cuda = USER-CUDA package files
These contain input scripts for identical systems, so they can be used
to benchmark the performance of both packages on your system.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

810
doc/_sources/Section_commands.txt Normal file
View File

@ -0,0 +1,810 @@
Commands
========
This section describes how a LAMMPS input script is formatted and the
input script commands used to define a LAMMPS simulation.
| 3.1 :ref:`LAMMPS input script <cmd_1>`
| 3.2 :ref:`Parsing rules <cmd_2>`
| 3.3 :ref:`Input script structure <cmd_3>`
| 3.4 :ref:`Commands listed by category <cmd_4>`
| 3.5 :ref:`Commands listed alphabetically <cmd_5>`
|
.. _cmd_1:
LAMMPS input script
-------------------
LAMMPS executes by reading commands from a input script (text file),
one line at a time. When the input script ends, LAMMPS exits. Each
command causes LAMMPS to take some action. It may set an internal
variable, read in a file, or run a simulation. Most commands have
default settings, which means you only need to use the command if you
wish to change the default.
In many cases, the ordering of commands in an input script is not
important. However the following rules apply:
(1) LAMMPS does not read your entire input script and then perform a
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:
.. parsed-literal::
timestep 0.5
run 100
run 100
does something different than this sequence:
.. parsed-literal::
run 100
timestep 0.5
run 100
In the first case, the specified timestep (0.5 fmsec) is used for two
simulations of 100 timesteps each. In the 2nd case, the default
timestep (1.0 fmsec) is used for the 1st 100 step simulation and a 0.5
fmsec timestep is used for the 2nd one.
(2) Some commands are only valid when they follow other commands. For
example you cannot set the temperature of a group of atoms until atoms
have been defined and a group command is used to define which atoms
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
: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 :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. :doc:`This section <Section_errors>` gives
more information on what errors mean. The documentation for each
command lists restrictions on how the command can be used.
----------
.. _cmd_2:
Parsing rules
-------------
Each non-blank line in the input script is treated as a command.
LAMMPS commands are case sensitive. Command names are lower-case, as
are specified command arguments. Upper case letters may be used in
file names or user-chosen ID strings.
Here is how each line in the input script is parsed by LAMMPS:
(1) If the last printable character on the line is a "&" character,
the command is assumed to continue on the next line. The next line is
concatenated to the previous line by removing the "&" character and
line break. This allows long commands to be continued across two or
more lines. See the discussion of triple quotes in (6) for how to
continue a command across multiple line without using "&" characters.
(2) All characters from the first "#" character onward are treated as
comment and discarded. See an exception in (6). Note that a
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.
(3) The line is searched repeatedly for $ characters, which indicate
variables that are replaced with a text string. See an exception in
(6).
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
"x".
How the variable is converted to a text string depends on what style
of variable it is; see the `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
input command. The variable can also store a numeric formula which
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 :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:
.. parsed-literal::
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
.. parsed-literal::
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.
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:
.. parsed-literal::
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
:doc:`equal-style variable <variable>`.
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.
(4) The line is broken into "words" separated by whitespace (tabs,
spaces). Note that words can thus contain letters, digits,
underscores, or punctuation characters.
(5) The first word is the command name. All successive words in the
line are arguments.
(6) If you want text with spaces to be treated as a single argument,
it can be enclosed in either single or double or triple quotes. A
long single argument enclosed in single or double quotes can span
multiple lines if the "&" character is used, as described above. When
the lines are concatenated together (and the "&" characters and line
breaks removed), the text will become a single line. If you want
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:
.. parsed-literal::
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 :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 :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.
----------
.. _cmd_3:
Input script structure
----------------------------------
This section describes the structure of a typical LAMMPS input script.
The "examples" directory in the LAMMPS distribution contains many
sample input scripts; the corresponding problems are discussed in
:doc:`Section_example <Section_example>`, and animated on the `LAMMPS WWW Site <lws_>`_.
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 the
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.
----------
.. _cmd_4:
Commands listed by category
---------------------------
This section lists all LAMMPS commands, grouped by category. The
:ref:`next section <cmd_5>` lists the same commands alphabetically. Note
that some style options for some commands are part of specific LAMMPS
packages, which means they cannot be used unless the package was
included when LAMMPS was built. Not all packages are included in a
default LAMMPS build. These dependencies are listed as Restrictions
in the command's documentation.
Initialization:
:doc:`atom_modify <atom_modify>`, :doc:`atom_style <atom_style>`,
:doc:`boundary <boundary>`, :doc:`dimension <dimension>`,
:doc:`newton <newton>`, :doc:`processors <processors>`, :doc:`units <units>`
Atom definition:
:doc:`create_atoms <create_atoms>`, :doc:`create_box <create_box>`,
:doc:`lattice <lattice>`, :doc:`read_data <read_data>`,
:doc:`read_dump <read_dump>`, :doc:`read_restart <read_restart>`,
:doc:`region <region>`, :doc:`replicate <replicate>`
Force fields:
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_style <angle_style>`,
:doc:`bond_coeff <bond_coeff>`, :doc:`bond_style <bond_style>`,
: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_style <comm_style>`, :doc:`group <group>`, :doc:`mass <mass>`,
:doc:`min_modify <min_modify>`, :doc:`min_style <min_style>`,
:doc:`neigh_modify <neigh_modify>`, :doc:`neighbor <neighbor>`,
:doc:`reset_timestep <reset_timestep>`, :doc:`run_style <run_style>`,
:doc:`set <set>`, :doc:`timestep <timestep>`, :doc:`velocity <velocity>`
Fixes:
:doc:`fix <fix>`, :doc:`fix_modify <fix_modify>`, :doc:`unfix <unfix>`
Computes:
:doc:`compute <compute>`, :doc:`compute_modify <compute_modify>`,
:doc:`uncompute <uncompute>`
Output:
:doc:`dump <dump>`, :doc:`dump image <dump_image>`,
:doc:`dump_modify <dump_modify>`, :doc:`dump movie <dump_image>`,
:doc:`restart <restart>`, :doc:`thermo <thermo>`,
:doc:`thermo_modify <thermo_modify>`, :doc:`thermo_style <thermo_style>`,
:doc:`undump <undump>`, :doc:`write_data <write_data>`,
:doc:`write_dump <write_dump>`, :doc:`write_restart <write_restart>`
Actions:
:doc:`delete_atoms <delete_atoms>`, :doc:`delete_bonds <delete_bonds>`,
:doc:`displace_atoms <displace_atoms>`, :doc:`change_box <change_box>`,
:doc:`minimize <minimize>`, :doc:`neb <neb>` :doc:`prd <prd>`,
:doc:`rerun <rerun>`, :doc:`run <run>`, :doc:`temper <temper>`
Miscellaneous:
: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:`shell <shell>`, :doc:`variable <variable>`
----------
.. _cmd_5:
.. _comm:
Individual commands
------------------------------------------
This section lists all LAMMPS commands alphabetically, with a separate
listing below of styles within certain commands. The :ref:`previous section <cmd_4>` lists the same commands, grouped by category. Note
that some style options for some commands are part of specific LAMMPS
packages, which means they cannot be used unless the package was
included when LAMMPS was built. Not all packages are included in a
default LAMMPS build. These dependencies are listed as Restrictions
in the command's documentation.
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :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:`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 image <dump_image>` | :doc:`dump_modify <dump_modify>` | :doc:`dump movie <dump_image>` | :doc:`echo <echo>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`fix <fix>` | :doc:`fix_modify <fix_modify>` | :doc:`group <group>` | :doc:`if <if>` | :doc:`info <info>` | :doc:`improper_coeff <improper_coeff>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`improper_style <improper_style>` | :doc:`include <include>` | :doc:`jump <jump>` | :doc:`kspace_modify <kspace_modify>` | :doc:`kspace_style <kspace_style>` | :doc:`label <label>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`lattice <lattice>` | :doc:`log <log>` | :doc:`mass <mass>` | :doc:`minimize <minimize>` | :doc:`min_modify <min_modify>` | :doc:`min_style <min_style>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`molecule <molecule>` | :doc:`neb <neb>` | :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_timestep <reset_timestep>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`restart <restart>` | :doc:`run <run>` | :doc:`run_style <run_style>` | :doc:`set <set>` | :doc:`shell <shell>` | :doc:`special_bonds <special_bonds>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`suffix <suffix>` | :doc:`tad <tad>` | :doc:`temper <temper>` | :doc:`thermo <thermo>` | :doc:`thermo_modify <thermo_modify>` | :doc:`thermo_style <thermo_style>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :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_data <write_data>` | :doc:`write_dump <write_dump>` | :doc:`write_restart <write_restart>` | |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
These are additional commands in USER packages, which can be used if
:ref:`LAMMPS is built with the appropriate package <start_3>`.
+------------------------------+
| :doc:`group2ndx <group2ndx>` |
+------------------------------+
----------
Fix styles
----------
See the :doc:`fix <fix>` command for one-line descriptions of each style
or click on the style itself for a full description. Some of the
styles have accelerated versions, which can be used if LAMMPS is built
with the :doc:`appropriate accelerated package <Section_accelerate>`.
This is indicated by additional letters in parenthesis: c = USER-CUDA,
g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`adapt <fix_adapt>` | :doc:`addforce (c) <fix_addforce>` | :doc:`append/atoms <fix_append_atoms>` | :doc:`atom/swap <fix_atom_swap>` | :doc:`aveforce (c) <fix_aveforce>` | :doc:`ave/atom <fix_ave_atom>` | :doc:`ave/chunk <fix_ave_chunk>` | :doc:`ave/correlate <fix_ave_correlate>` |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`ave/histo <fix_ave_histo>` | :doc:`ave/histo/weight <fix_ave_histo>` | :doc:`ave/spatial <fix_ave_spatial>` | :doc:`ave/time <fix_ave_time>` | :doc:`balance <fix_balance>` | :doc:`bond/break <fix_bond_break>` | :doc:`bond/create <fix_bond_create>` | :doc:`bond/swap <fix_bond_swap>` |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`box/relax <fix_box_relax>` | :doc:`deform (k) <fix_deform>` | :doc:`deposit <fix_deposit>` | :doc:`drag <fix_drag>` | :doc:`dt/reset <fix_dt_reset>` | :doc:`efield <fix_efield>` | :doc:`enforce2d (c) <fix_enforce2d>` | :doc:`evaporate <fix_evaporate>` |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`external <fix_external>` | :doc:`freeze (c) <fix_freeze>` | :doc:`gcmc <fix_gcmc>` | :doc:`gld <fix_gld>` | :doc:`gravity (co) <fix_gravity>` | :doc:`heat <fix_heat>` | :doc:`indent <fix_indent>` | :doc:`langevin (k) <fix_langevin>` |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`lineforce <fix_lineforce>` | :doc:`momentum <fix_momentum>` | :doc:`move <fix_move>` | :doc:`msst <fix_msst>` | :doc:`neb <fix_neb>` | :doc:`nph (ko) <fix_nh>` | :doc:`nphug (o) <fix_nphug>` | :doc:`nph/asphere (o) <fix_nph_asphere>` |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`nph/sphere (o) <fix_nph_sphere>` | :doc:`npt (ckio) <fix_nh>` | :doc:`npt/asphere (o) <fix_npt_asphere>` | :doc:`npt/sphere (o) <fix_npt_sphere>` | :doc:`nve (ckio) <fix_nve>` | :doc:`nve/asphere (i) <fix_nve_asphere>` | :doc:`nve/asphere/noforce <fix_nve_asphere_noforce>` | :doc:`nve/body <fix_nve_body>` |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`nve/limit <fix_nve_limit>` | :doc:`nve/line <fix_nve_line>` | :doc:`nve/noforce <fix_nve_noforce>` | :doc:`nve/sphere (o) <fix_nve_sphere>` | :doc:`nve/tri <fix_nve_tri>` | :doc:`nvt (cko) <fix_nh>` | :doc:`nvt/asphere (o) <fix_nvt_asphere>` | :doc:`nvt/sllod (o) <fix_nvt_sllod>` |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`nvt/sphere (o) <fix_nvt_sphere>` | :doc:`oneway <fix_oneway>` | :doc:`orient/fcc <fix_orient_fcc>` | :doc:`planeforce <fix_planeforce>` | :doc:`poems <fix_poems>` | :doc:`pour <fix_pour>` | :doc:`press/berendsen <fix_press_berendsen>` | :doc:`print <fix_print>` |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`property/atom <fix_property_atom>` | :doc:`qeq/comb (o) <fix_qeq_comb>` | :doc:`qeq/dynamic <fix_qeq>` | :doc:`qeq/fire <fix_qeq>` | :doc:`qeq/point <fix_qeq>` | :doc:`qeq/shielded <fix_qeq>` | :doc:`qeq/slater <fix_qeq>` | :doc:`reax/bonds <fix_reax_bonds>` |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`recenter <fix_recenter>` | :doc:`restrain <fix_restrain>` | :doc:`rigid (o) <fix_rigid>` | :doc:`rigid/nph (o) <fix_rigid>` | :doc:`rigid/npt (o) <fix_rigid>` | :doc:`rigid/nve (o) <fix_rigid>` | :doc:`rigid/nvt (o) <fix_rigid>` | :doc:`rigid/small (o) <fix_rigid>` |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`rigid/small/nph <fix_rigid>` | :doc:`rigid/small/npt <fix_rigid>` | :doc:`rigid/small/nve <fix_rigid>` | :doc:`rigid/small/nvt <fix_rigid>` | :doc:`setforce (ck) <fix_setforce>` | :doc:`shake (c) <fix_shake>` | :doc:`spring <fix_spring>` | :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:`temp/berendsen (c) <fix_temp_berendsen>` | :doc:`temp/csld <fix_temp_csvr>` | :doc:`temp/csvr <fix_temp_csvr>` | :doc:`temp/rescale (c) <fix_temp_rescale>` |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`tfmc <fix_tfmc>` | :doc:`thermal/conductivity <fix_thermal_conductivity>` | :doc:`tmd <fix_tmd>` | :doc:`ttm <fix_ttm>` | :doc:`tune/kspace <fix_tune_kspace>` | :doc:`vector <fix_vector>` | :doc:`viscosity <fix_viscosity>` | :doc:`viscous (c) <fix_viscous>` |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`wall/colloid <fix_wall>` | :doc:`wall/gran <fix_wall_gran>` | :doc:`wall/harmonic <fix_wall>` | :doc:`wall/lj1043 <fix_wall>` | :doc:`wall/lj126 <fix_wall>` | :doc:`wall/lj93 <fix_wall>` | :doc:`wall/piston <fix_wall_piston>` | :doc:`wall/reflect (k) <fix_wall_reflect>` |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
| :doc:`wall/region <fix_wall_region>` | :doc:`wall/srd <fix_wall_srd>` | | | | | | |
+------------------------------------------+--------------------------------------------------------+------------------------------------------+----------------------------------------+------------------------------------------------+------------------------------------------+------------------------------------------------------+--------------------------------------------+
These are additional fix styles in USER packages, which can be used if
:ref:`LAMMPS is built with the appropriate package <start_3>`.
+-----------------------------------------------------+------------------------------------------------------+------------------------------------------------------+--------------------------------------------------------------------------+----------------------------------------------------+----------------------------------------------------------------------------------+
| :doc:`adapt/fep <fix_adapt_fep>` | :doc:`addtorque <fix_addtorque>` | :doc:`atc <fix_atc>` | :doc:`ave/correlate/long <fix_ave_correlate_long>` | :doc:`ave/spatial/sphere <fix_ave_spatial_sphere>` | :doc:`drude <fix_drude>` |
+-----------------------------------------------------+------------------------------------------------------+------------------------------------------------------+--------------------------------------------------------------------------+----------------------------------------------------+----------------------------------------------------------------------------------+
| :doc:`drude/transform/direct <fix_drude_transform>` | :doc:`drude/transform/reverse <fix_drude_transform>` | :doc:`colvars <fix_colvars>` | :doc:`gle <fix_gle>` | :doc:`imd <fix_imd>` | :doc:`ipi <fix_ipi>` |
+-----------------------------------------------------+------------------------------------------------------+------------------------------------------------------+--------------------------------------------------------------------------+----------------------------------------------------+----------------------------------------------------------------------------------+
| :doc:`langevin/drude <fix_langevin_drude>` | :doc:`langevin/eff <fix_langevin_eff>` | :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:`meso <fix_meso>` | :doc:`meso/stationary <fix_meso_stationary>` | :doc:`nph/eff <fix_nh_eff>` | :doc:`npt/eff <fix_nh_eff>` | :doc:`nve/eff <fix_nve_eff>` |
+-----------------------------------------------------+------------------------------------------------------+------------------------------------------------------+--------------------------------------------------------------------------+----------------------------------------------------+----------------------------------------------------------------------------------+
| :doc:`nvt/eff <fix_nh_eff>` | :doc:`nvt/sllod/eff <fix_nvt_sllod_eff>` | :doc:`phonon <fix_phonon>` | :doc:`pimd <fix_pimd>` | :doc:`qbmsst <fix_qbmsst>` | :doc:`qeq/reax <fix_qeq_reax>` |
+-----------------------------------------------------+------------------------------------------------------+------------------------------------------------------+--------------------------------------------------------------------------+----------------------------------------------------+----------------------------------------------------------------------------------+
| :doc:`qmmm <fix_qmmm>` | :doc:`qtb <fix_qtb>` | :doc:`reax/c/bonds <fix_reax_bonds>` | :doc:`reax/c/species <fix_reaxc_species>` | :doc:`saed/vtk <fix_saed_vtk>` | :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/triangulated/surface <fix_smd_move_triangulated_surface>` | :doc:`smd/setvel <fix_smd_setvel>` | :doc:`smd/tlsph/reference/configuration <fix_smd_tlsph_reference_configuration>` |
+-----------------------------------------------------+------------------------------------------------------+------------------------------------------------------+--------------------------------------------------------------------------+----------------------------------------------------+----------------------------------------------------------------------------------+
| :doc:`smd/wall/surface <fix_smd_wall_surface>` | :doc:`temp/rescale/eff <fix_temp_rescale_eff>` | :doc:`ti/rs <fix_ti_rs>` | :doc:`ti/spring <fix_ti_spring>` | :doc:`ttm/mod <fix_ttm>` | |
+-----------------------------------------------------+------------------------------------------------------+------------------------------------------------------+--------------------------------------------------------------------------+----------------------------------------------------+----------------------------------------------------------------------------------+
----------
Compute styles
--------------
See the :doc:`compute <compute>` command for one-line descriptions of
each style or click on the style itself for a full description. Some
of the styles have accelerated versions, which can be used if LAMMPS
is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+----------------------------------------------------+
| :doc:`angle/local <compute_angle_local>` | :doc:`angmom/chunk <compute_angmom_chunk>` | :doc:`body/local <compute_body_local>` | :doc:`bond/local <compute_bond_local>` | :doc:`centro/atom <compute_centro_atom>` | :doc:`chunk/atom <compute_chunk_atom>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+----------------------------------------------------+
| :doc:`cluster/atom <compute_cluster_atom>` | :doc:`cna/atom <compute_cna_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/local <compute_dihedral_local>` | :doc:`dilatation/atom <compute_dilatation_atom>` | :doc:`displace/atom <compute_displace_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:`group/group <compute_group_group>` | :doc:`gyration <compute_gyration>` | :doc:`gyration/chunk <compute_gyration_chunk>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+----------------------------------------------------+
| :doc:`heat/flux <compute_heat_flux>` | :doc:`hexorder/atom <compute_hexorder_atom>` | :doc:`improper/local <compute_improper_local>` | :doc:`inertia/chunk <compute_inertia_chunk>` | :doc:`ke <compute_ke>` | :doc:`ke/atom <compute_ke_atom>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+----------------------------------------------------+
| :doc:`ke/rigid <compute_ke_rigid>` | :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 (c) <compute_pe>` | :doc:`pe/atom <compute_pe_atom>` | :doc:`plasticity/atom <compute_plasticity_atom>` | :doc:`pressure (c) <compute_pressure>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+----------------------------------------------------+
| :doc:`property/atom <compute_property_atom>` | :doc:`property/local <compute_property_local>` | :doc:`property/chunk <compute_property_chunk>` | :doc:`rdf <compute_rdf>` | :doc:`reduce <compute_reduce>` | :doc:`reduce/region <compute_reduce>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+----------------------------------------------------+
| :doc:`slice <compute_slice>` | :doc:`sna/atom <compute_sna_atom>` | :doc:`snad/atom <compute_sna_atom>` | :doc:`snav/atom <compute_sna_atom>` | :doc:`stress/atom <compute_stress_atom>` | :doc:`temp (ck) <compute_temp>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+----------------------------------------------------+
| :doc:`temp/asphere <compute_temp_asphere>` | :doc:`temp/chunk <compute_temp_chunk>` | :doc:`temp/com <compute_temp_com>` | :doc:`temp/deform <compute_temp_deform>` | :doc:`temp/partial (c) <compute_temp_partial>` | :doc:`temp/profile <compute_temp_profile>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+----------------------------------------------------+
| :doc:`temp/ramp <compute_temp_ramp>` | :doc:`temp/region <compute_temp_region>` | :doc:`temp/sphere <compute_temp_sphere>` | :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>` | | | | |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+----------------------------------------------------+
These are additional compute styles in USER packages, which can be
used if :ref:`LAMMPS is built with the appropriate package <start_3>`.
+--------------------------------------------------------------+------------------------------------------------------+------------------------------------------------------------------------+------------------------------------------------------------+--------------------------------------------------------+------------------------------------------------------------------+
| :doc:`ackland/atom <compute_ackland_atom>` | :doc:`basal/atom <compute_basal_atom>` | :doc:`fep <compute_fep>` | :doc:`force/tally <compute_tally>` | :doc:`heat/flux/tally <compute_tally>` | :doc:`ke/eff <compute_ke_eff>` |
+--------------------------------------------------------------+------------------------------------------------------+------------------------------------------------------------------------+------------------------------------------------------------+--------------------------------------------------------+------------------------------------------------------------------+
| :doc:`ke/atom/eff <compute_ke_atom_eff>` | :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:`pe/tally <compute_tally>` | :doc:`saed <compute_saed>` |
+--------------------------------------------------------------+------------------------------------------------------+------------------------------------------------------------------------+------------------------------------------------------------+--------------------------------------------------------+------------------------------------------------------------------+
| :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/mesh/vertices <compute_smd_triangle_mesh_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:`stress/tally <compute_tally>` | :doc:`temp/drude <compute_temp_drude>` | :doc:`temp/eff <compute_temp_eff>` | :doc:`temp/deform/eff <compute_temp_deform_eff>` |
+--------------------------------------------------------------+------------------------------------------------------+------------------------------------------------------------------------+------------------------------------------------------------+--------------------------------------------------------+------------------------------------------------------------------+
| :doc:`temp/region/eff <compute_temp_region_eff>` | :doc:`temp/rotate <compute_temp_rotate>` | :doc:`xrd <compute_xrd>` | | | |
+--------------------------------------------------------------+------------------------------------------------------+------------------------------------------------------------------------+------------------------------------------------------------+--------------------------------------------------------+------------------------------------------------------------------+
----------
Pair_style potentials
---------------------
See the :doc:`pair_style <pair_style>` command for an overview of pair
potentials. Click on the style itself for a full description. Many
of the styles have accelerated versions, which can be used if LAMMPS
is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`none <pair_none>` | :doc:`hybrid <pair_hybrid>` | :doc:`hybrid/overlay <pair_hybrid>` | :doc:`adp (o) <pair_adp>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`airebo (o) <pair_airebo>` | :doc:`beck (go) <pair_beck>` | :doc:`body <pair_body>` | :doc:`bop <pair_bop>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`born (go) <pair_born>` | :doc:`born/coul/long (cgo) <pair_born>` | :doc:`born/coul/long/cs <pair_born>` | :doc:`born/coul/msm (o) <pair_born>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`born/coul/wolf (go) <pair_born>` | :doc:`brownian (o) <pair_brownian>` | :doc:`brownian/poly (o) <pair_brownian>` | :doc:`buck (cgkio) <pair_buck>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`buck/coul/cut (cgkio) <pair_buck>` | :doc:`buck/coul/long (cgkio) <pair_buck>` | :doc:`buck/coul/long/cs <pair_buck>` | :doc:`buck/coul/msm (o) <pair_buck>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`buck/long/coul/long (o) <pair_buck_long>` | :doc:`colloid (go) <pair_colloid>` | :doc:`comb (o) <pair_comb>` | :doc:`comb3 <pair_comb>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`coul/cut (gko) <pair_coul>` | :doc:`coul/debye (gko) <pair_coul>` | :doc:`coul/dsf (gko) <pair_coul>` | :doc:`coul/long (gko) <pair_coul>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`coul/long/cs <pair_coul>` | :doc:`coul/msm <pair_coul>` | :doc:`coul/streitz <pair_coul>` | :doc:`coul/wolf (ko) <pair_coul>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`dpd (o) <pair_dpd>` | :doc:`dpd/tstat (o) <pair_dpd>` | :doc:`dsmc <pair_dsmc>` | :doc:`eam (cgkot) <pair_eam>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`eam/alloy (cgkot) <pair_eam>` | :doc:`eam/fs (cgkot) <pair_eam>` | :doc:`eim (o) <pair_eim>` | :doc:`gauss (go) <pair_gauss>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`gayberne (gio) <pair_gayberne>` | :doc:`gran/hertz/history (o) <pair_gran>` | :doc:`gran/hooke (co) <pair_gran>` | :doc:`gran/hooke/history (o) <pair_gran>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`hbond/dreiding/lj (o) <pair_hbond_dreiding>` | :doc:`hbond/dreiding/morse (o) <pair_hbond_dreiding>` | :doc:`kim <pair_kim>` | :doc:`lcbop <pair_lcbop>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`line/lj <pair_line_lj>` | :doc:`lj/charmm/coul/charmm (cko) <pair_charmm>` | :doc:`lj/charmm/coul/charmm/implicit (cko) <pair_charmm>` | :doc:`lj/charmm/coul/long (cgiko) <pair_charmm>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`lj/charmm/coul/msm <pair_charmm>` | :doc:`lj/class2 (cgko) <pair_class2>` | :doc:`lj/class2/coul/cut (cko) <pair_class2>` | :doc:`lj/class2/coul/long (cgko) <pair_class2>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`lj/cubic (go) <pair_lj_cubic>` | :doc:`lj/cut (cgikot) <pair_lj>` | :doc:`lj/cut/coul/cut (cgko) <pair_lj>` | :doc:`lj/cut/coul/debye (cgko) <pair_lj>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`lj/cut/coul/dsf (gko) <pair_lj>` | :doc:`lj/cut/coul/long (cgikot) <pair_lj>` | :doc:`lj/cut/coul/long/cs <pair_lj>` | :doc:`lj/cut/coul/msm (go) <pair_lj>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`lj/cut/dipole/cut (go) <pair_dipole>` | :doc:`lj/cut/dipole/long <pair_dipole>` | :doc:`lj/cut/tip4p/cut (o) <pair_lj>` | :doc:`lj/cut/tip4p/long (ot) <pair_lj>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`lj/expand (cgko) <pair_lj_expand>` | :doc:`lj/gromacs (cgko) <pair_gromacs>` | :doc:`lj/gromacs/coul/gromacs (cko) <pair_gromacs>` | :doc:`lj/long/coul/long (o) <pair_lj_long>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`lj/long/dipole/long <pair_dipole>` | :doc:`lj/long/tip4p/long <pair_lj_long>` | :doc:`lj/smooth (co) <pair_lj_smooth>` | :doc:`lj/smooth/linear (o) <pair_lj_smooth_linear>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`lj96/cut (cgo) <pair_lj96>` | :doc:`lubricate (o) <pair_lubricate>` | :doc:`lubricate/poly (o) <pair_lubricate>` | :doc:`lubricateU <pair_lubricateU>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`lubricateU/poly <pair_lubricateU>` | :doc:`meam (o) <pair_meam>` | :doc:`mie/cut (o) <pair_mie>` | :doc:`morse (cgot) <pair_morse>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`nb3b/harmonic (o) <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:`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:`reax <pair_reax>` | :doc:`rebo (o) <pair_airebo>` | :doc:`resquared (go) <pair_resquared>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`snap <pair_snap>` | :doc:`soft (go) <pair_soft>` | :doc:`sw (cgkio) <pair_sw>` | :doc:`table (gko) <pair_table>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`tersoff (cgkio) <pair_tersoff>` | :doc:`tersoff/mod (ko) <pair_tersoff_mod>` | :doc:`tersoff/zbl (ko) <pair_tersoff_zbl>` | :doc:`tip4p/cut (o) <pair_coul>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`tip4p/long (o) <pair_coul>` | :doc:`tri/lj <pair_tri_lj>` | :doc:`vashishta (o) <pair_vashishta>` | :doc:`yukawa (go) <pair_yukawa>` |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
| :doc:`yukawa/colloid (go) <pair_yukawa_colloid>` | :doc:`zbl (go) <pair_zbl>` | | |
+----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------------------+
These are additional pair styles in USER packages, which can be used
if :ref:`LAMMPS is built with the appropriate package <start_3>`.
+-----------------------------------------------------+-----------------------------------------------------------------+--------------------------------------------+---------------------------------------------------+
| :doc:`awpmd/cut <pair_awpmd>` | :doc:`buck/mdf <pair_mdf>` | :doc:`coul/cut/soft (o) <pair_lj_soft>` | :doc:`coul/diel (o) <pair_coul_diel>` |
+-----------------------------------------------------+-----------------------------------------------------------------+--------------------------------------------+---------------------------------------------------+
| :doc:`coul/long/soft (o) <pair_lj_soft>` | :doc:`eam/cd (o) <pair_eam>` | :doc:`edip (o) <pair_edip>` | :doc:`eff/cut <pair_eff>` |
+-----------------------------------------------------+-----------------------------------------------------------------+--------------------------------------------+---------------------------------------------------+
| :doc:`gauss/cut <pair_gauss>` | :doc:`lennard/mdf <pair_mdf>` | :doc:`list <pair_list>` | :doc:`lj/charmm/coul/long/soft (o) <pair_charmm>` |
+-----------------------------------------------------+-----------------------------------------------------------------+--------------------------------------------+---------------------------------------------------+
| :doc:`lj/cut/coul/cut/soft (o) <pair_lj_soft>` | :doc:`lj/cut/coul/long/soft (o) <pair_lj_soft>` | :doc:`lj/cut/dipole/sf (go) <pair_dipole>` | :doc:`lj/cut/soft (o) <pair_lj_soft>` |
+-----------------------------------------------------+-----------------------------------------------------------------+--------------------------------------------+---------------------------------------------------+
| :doc:`lj/cut/tip4p/long/soft (o) <pair_lj_soft>` | :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 (o) <pair_lj_sf>` | :doc:`meam/spline <pair_meam_spline>` | :doc:`meam/sw/spline <pair_meam_sw_spline>` |
+-----------------------------------------------------+-----------------------------------------------------------------+--------------------------------------------+---------------------------------------------------+
| :doc:`mgpt <pair_mgpt>` | :doc:`quip <pair_quip>` | :doc:`reax/c <pair_reax_c>` | :doc:`smd/hertz <pair_smd_hertz>` |
+-----------------------------------------------------+-----------------------------------------------------------------+--------------------------------------------+---------------------------------------------------+
| :doc:`smd/tlsph <pair_smd_tlsph>` | :doc:`smd/triangulated/surface <pair_smd_triangulated_surface>` | :doc:`smd/ulsph <pair_smd_ulsph>` | :doc:`smtbq <pair_smtbq>` |
+-----------------------------------------------------+-----------------------------------------------------------------+--------------------------------------------+---------------------------------------------------+
| :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:`srp <pair_srp>` | :doc:`tersoff/table (o) <pair_tersoff>` |
+-----------------------------------------------------+-----------------------------------------------------------------+--------------------------------------------+---------------------------------------------------+
| :doc:`thole <pair_thole>` | :doc:`tip4p/long/soft (o) <pair_lj_soft>` | | |
+-----------------------------------------------------+-----------------------------------------------------------------+--------------------------------------------+---------------------------------------------------+
----------
Bond_style potentials
---------------------
See the :doc:`bond_style <bond_style>` command for an overview of bond
potentials. Click on the style itself for a full description. Some
of the styles have accelerated versions, which can be used if LAMMPS
is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+-------------------------------------------+--------------------------------------+---------------------------------+---------------------------------------+
| :doc:`none <bond_none>` | :doc:`hybrid <bond_hybrid>` | :doc:`class2 (o) <bond_class2>` | :doc:`fene (ko) <bond_fene>` |
+-------------------------------------------+--------------------------------------+---------------------------------+---------------------------------------+
| :doc:`fene/expand (o) <bond_fene_expand>` | :doc:`harmonic (ko) <bond_harmonic>` | :doc:`morse (o) <bond_morse>` | :doc:`nonlinear (o) <bond_nonlinear>` |
+-------------------------------------------+--------------------------------------+---------------------------------+---------------------------------------+
| :doc:`quartic (o) <bond_quartic>` | :doc:`table (o) <bond_table>` | | |
+-------------------------------------------+--------------------------------------+---------------------------------+---------------------------------------+
These are additional bond styles in USER packages, which can be used
if :ref:`LAMMPS is built with the appropriate package <start_3>`.
+-------------------------------------------------+---------------------------------------------------------+
| :doc:`harmonic/shift (o) <bond_harmonic_shift>` | :doc:`harmonic/shift/cut (o) <bond_harmonic_shift_cut>` |
+-------------------------------------------------+---------------------------------------------------------+
----------
Angle_style potentials
----------------------
See the :doc:`angle_style <angle_style>` command for an overview of
angle potentials. Click on the style itself for a full description.
Some of the styles have accelerated versions, which can be used if
LAMMPS is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+---------------------------------------+----------------------------------------------+----------------------------------------------------+--------------------------------------------------+
| :doc:`none <angle_none>` | :doc:`hybrid <angle_hybrid>` | :doc:`charmm (ko) <angle_charmm>` | :doc:`class2 (o) <angle_class2>` |
+---------------------------------------+----------------------------------------------+----------------------------------------------------+--------------------------------------------------+
| :doc:`cosine (o) <angle_cosine>` | :doc:`cosine/delta (o) <angle_cosine_delta>` | :doc:`cosine/periodic (o) <angle_cosine_periodic>` | :doc:`cosine/squared (o) <angle_cosine_squared>` |
+---------------------------------------+----------------------------------------------+----------------------------------------------------+--------------------------------------------------+
| :doc:`harmonic (ko) <angle_harmonic>` | :doc:`table (o) <angle_table>` | | |
+---------------------------------------+----------------------------------------------+----------------------------------------------------+--------------------------------------------------+
These are additional angle styles in USER packages, which can be used
if :ref:`LAMMPS is built with the appropriate package <start_3>`.
+--------------------------------------------------+------------------------------------------------------+----------------------------------+------------------------------------+
| :doc:`cosine/shift (o) <angle_cosine_shift>` | :doc:`cosine/shift/exp (o) <angle_cosine_shift_exp>` | :doc:`dipole (o) <angle_dipole>` | :doc:`fourier (o) <angle_fourier>` |
+--------------------------------------------------+------------------------------------------------------+----------------------------------+------------------------------------+
| :doc:`fourier/simple (o) <angle_fourier_simple>` | :doc:`quartic (o) <angle_quartic>` | :doc:`sdk <angle_sdk>` | |
+--------------------------------------------------+------------------------------------------------------+----------------------------------+------------------------------------+
----------
Dihedral_style potentials
-------------------------
See the :doc:`dihedral_style <dihedral_style>` command for an overview
of dihedral potentials. Click on the style itself for a full
description. Some of the styles have accelerated versions, which can
be used if LAMMPS is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+-----------------------------------------+-----------------------------------+-----------------------------------------------------+-------------------------------------+
| :doc:`none <dihedral_none>` | :doc:`hybrid <dihedral_hybrid>` | :doc:`charmm (ko) <dihedral_charmm>` | :doc:`class2 (o) <dihedral_class2>` |
+-----------------------------------------+-----------------------------------+-----------------------------------------------------+-------------------------------------+
| :doc:`harmonic (o) <dihedral_harmonic>` | :doc:`helix (o) <dihedral_helix>` | :doc:`multi/harmonic (o) <dihedral_multi_harmonic>` | :doc:`opls (ko) <dihedral_opls>` |
+-----------------------------------------+-----------------------------------+-----------------------------------------------------+-------------------------------------+
These are additional dihedral styles in USER packages, which can be
used if :ref:`LAMMPS is built with the appropriate package <start_3>`.
+---------------------------------------------------------+---------------------------------------+-------------------------------------------+-------------------------------------------+
| :doc:`cosine/shift/exp (o) <dihedral_cosine_shift_exp>` | :doc:`fourier (o) <dihedral_fourier>` | :doc:`nharmonic (o) <dihedral_nharmonic>` | :doc:`quadratic (o) <dihedral_quadratic>` |
+---------------------------------------------------------+---------------------------------------+-------------------------------------------+-------------------------------------------+
| :doc:`table (o) <dihedral_table>` | | | |
+---------------------------------------------------------+---------------------------------------+-------------------------------------------+-------------------------------------------+
----------
Improper_style potentials
-------------------------
See the :doc:`improper_style <improper_style>` command for an overview
of improper potentials. Click on the style itself for a full
description. Some of the styles have accelerated versions, which can
be used if LAMMPS is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+------------------------------------------+-----------------------------------------+-------------------------------------+---------------------------------+
| :doc:`none <improper_none>` | :doc:`hybrid <improper_hybrid>` | :doc:`class2 (o) <improper_class2>` | :doc:`cvff (o) <improper_cvff>` |
+------------------------------------------+-----------------------------------------+-------------------------------------+---------------------------------+
| :doc:`harmonic (ko) <improper_harmonic>` | :doc:`umbrella (o) <improper_umbrella>` | | |
+------------------------------------------+-----------------------------------------+-------------------------------------+---------------------------------+
These are additional improper styles in USER packages, which can be
used if :ref:`LAMMPS is built with the appropriate package <start_3>`.
+-----------------------------------+-------------------------------------+---------------------------------------+---------------------------------+
| :doc:`cossq (o) <improper_cossq>` | :doc:`distance <improper_distance>` | :doc:`fourier (o) <improper_fourier>` | :doc:`ring (o) <improper_ring>` |
+-----------------------------------+-------------------------------------+---------------------------------------+---------------------------------+
----------
Kspace solvers
--------------
See the :doc:`kspace_style <kspace_style>` command for an overview of
Kspace solvers. Click on the style itself for a full description.
Some of the styles have accelerated versions, which can be used if
LAMMPS is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, 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 (cgo) <kspace_style>` | :doc:`pppm/cg (o) <kspace_style>` | :doc:`pppm/disp <kspace_style>` | :doc:`pppm/disp/tip4p <kspace_style>` |
+--------------------------------------+-----------------------------------+---------------------------------+---------------------------------------+
| :doc:`pppm/tip4p (o) <kspace_style>` | | | |
+--------------------------------------+-----------------------------------+---------------------------------+---------------------------------------+
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

8692
doc/_sources/Section_errors.txt Normal file
View File

File diff suppressed because it is too large Load Diff

170
doc/_sources/Section_example.txt Normal file
View File

@ -0,0 +1,170 @@
Example problems
================
The LAMMPS distribution includes an examples sub-directory with
several sample problems. Each problem is in a sub-directory of its
own. Most are 2d models so that they run quickly, 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.*) and dump file
(dump.*) when it runs. Some use a data file (data.*) of initial
coordinates as additional input. A few sample log file outputs 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.crack.foo.P means it ran on P processors of machine "foo".
For examples that use input data files, many of them were produced by
`Pizza.py <http://pizza.sandia.gov>`_ or setup tools described in the
:doc:`Additional Tools <Section_tools>` section of the LAMMPS
documentation and provided with the LAMMPS distribution.
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>`_. It can
also be animated using the xmovie tool described in the :doc:`Additional Tools <Section_tools>` section of the LAMMPS documentation.
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 these examples can be viewed on the Movies
section of the `LAMMPS WWW Site <lws_>`_.
These are the sample problems in the examples sub-directories:
+-------------+----------------------------------------------------------------------------+
| balance | dynamic load balancing, 2d system |
+-------------+----------------------------------------------------------------------------+
| body | body particles, 2d system |
+-------------+----------------------------------------------------------------------------+
| colloid | big colloid particles in a small particle solvent, 2d system |
+-------------+----------------------------------------------------------------------------+
| comb | models using the COMB potential |
+-------------+----------------------------------------------------------------------------+
| crack | crack propagation in a 2d solid |
+-------------+----------------------------------------------------------------------------+
| cuda | use of the USER-CUDA package for GPU acceleration |
+-------------+----------------------------------------------------------------------------+
| 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 |
+-------------+----------------------------------------------------------------------------+
| gpu | use of the GPU package for GPU acceleration |
+-------------+----------------------------------------------------------------------------+
| hugoniostat | Hugoniostat shock dynamics |
+-------------+----------------------------------------------------------------------------+
| indent | spherical indenter into a 2d solid |
+-------------+----------------------------------------------------------------------------+
| intel | use of the USER-INTEL package for CPU or Intel(R) Xeon Phi(TM) coprocessor |
+-------------+----------------------------------------------------------------------------+
| kim | use of potentials in Knowledge Base for Interatomic Models (KIM) |
+-------------+----------------------------------------------------------------------------+
| line | line segment particles in 2d rigid bodies |
+-------------+----------------------------------------------------------------------------+
| meam | MEAM test for SiC and shear (same as shear examples) |
+-------------+----------------------------------------------------------------------------+
| melt | rapid melt of 3d LJ system |
+-------------+----------------------------------------------------------------------------+
| micelle | self-assembly of small lipid-like molecules into 2d bilayers |
+-------------+----------------------------------------------------------------------------+
| min | energy minimization of 2d LJ melt |
+-------------+----------------------------------------------------------------------------+
| msst | MSST shock dynamics |
+-------------+----------------------------------------------------------------------------+
| nb3b | use of nonbonded 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 |
+-------------+----------------------------------------------------------------------------+
| qeq | use of the QEQ pacakge for charge equilibration |
+-------------+----------------------------------------------------------------------------+
| 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 |
+-------------+----------------------------------------------------------------------------+
| tad | temperature-accelerated dynamics of vacancy diffusion in bulk Si |
+-------------+----------------------------------------------------------------------------+
| tri | triangular particles in rigid bodies |
+-------------+----------------------------------------------------------------------------+
vashishta: models using the Vashishta potential
Here is how you might 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 as follows:
.. parsed-literal::
../../tools/xmovie/xmovie -scale dump.indent
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. 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
----------
There is also a COUPLE directory with examples of how to use LAMMPS as
a library, either by itself or in tandem with another code or library.
See the COUPLE/README file to get started.
There is also an ELASTIC directory with an example script for
computing elastic constants at zero temperature, using an Si example. See
the ELASTIC/in.elastic file for more info.
There is also an ELASTIC_T directory with an example script for
computing elastic constants at finite temperature, using an Si example. See
the ELASTIC_T/in.elastic file for more info.
There is also a USER directory which contains subdirectories of
user-provided examples for user packages. See the README files in
those directories for more info. See the
:doc:`Section_start.html <Section_start>` file for more info about user
packages.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

127
doc/_sources/Section_history.txt Normal file
View File

@ -0,0 +1,127 @@
Future and history
==================
This section lists features we plan to add to LAMMPS, features of
previous versions of LAMMPS, and features of other parallel molecular
dynamics codes our group has distributed.
| 13.1 :ref:`Coming attractions <hist_1>`
| 13.2 :ref:`Past versions <hist_2>`
|
.. _hist_1:
Coming attractions
-------------------------------
The `Wish list link <http://lammps.sandia.gov/future.html>`_ on the
LAMMPS WWW page gives a list of features we are hoping to add to
LAMMPS in the future, including contact names of individuals you can
email if you are interested in contributing to the developement or
would be a future user of that feature.
You can also send `email to the developers <http://lammps.sandia.gov/authors.html>`_ if you want to add
your wish to the list.
----------
.. _hist_2:
Past versions
--------------------------
LAMMPS development began in the mid 1990s under a cooperative research
& development agreement (CRADA) between two DOE labs (Sandia and LLNL)
and 3 companies (Cray, Bristol Myers Squibb, and Dupont). The goal was
to develop a large-scale parallel classical MD code; the coding effort
was led by Steve Plimpton at Sandia.
After the CRADA ended, a final F77 version, LAMMPS 99, was
released. As development of LAMMPS continued at Sandia, its memory
management was converted to F90; a final F90 version was released as
LAMMPS 2001.
The current LAMMPS is a rewrite in C++ and was first publicly released
as an open source code in 2004. It includes many new features beyond
those in LAMMPS 99 or 2001. It also includes features from older
parallel MD codes written at Sandia, namely ParaDyn, Warp, and
GranFlow (see below).
In late 2006 we began merging new capabilities into LAMMPS that were
developed by Aidan Thompson at Sandia for his MD code GRASP, which has
a parallel framework similar to LAMMPS. Most notably, these have
included many-body potentials - Stillinger-Weber, Tersoff, ReaxFF -
and the associated charge-equilibration routines needed for ReaxFF.
The `History link <http://lammps.sandia.gov/history.html>`_ on the
LAMMPS WWW page gives a timeline of features added to the
C++ open-source version of LAMMPS over the last several years.
These older codes are available for download from the `LAMMPS WWW site <lws_>`_, except for Warp & GranFlow which were primarily used
internally. A brief listing of their features is given here.
LAMMPS 2001
* F90 + MPI
* dynamic memory
* spatial-decomposition parallelism
* NVE, NVT, NPT, NPH, rRESPA integrators
* LJ and Coulombic pairwise force fields
* all-atom, united-atom, bead-spring polymer force fields
* CHARMM-compatible force fields
* class 2 force fields
* 3d/2d Ewald & PPPM
* various force and temperature constraints
* SHAKE
* Hessian-free truncated-Newton minimizer
* user-defined diagnostics
LAMMPS 99
* F77 + MPI
* static memory allocation
* spatial-decomposition parallelism
* most of the LAMMPS 2001 features with a few exceptions
* no 2d Ewald & PPPM
* molecular force fields are missing a few CHARMM terms
* no SHAKE
Warp
* F90 + MPI
* spatial-decomposition parallelism
* embedded atom method (EAM) metal potentials + LJ
* lattice and grain-boundary atom creation
* NVE, NVT integrators
* boundary conditions for applying shear stresses
* temperature controls for actively sheared systems
* per-atom energy and centro-symmetry computation and output
ParaDyn
* F77 + MPI
* atom- and force-decomposition parallelism
* embedded atom method (EAM) metal potentials
* lattice atom creation
* NVE, NVT, NPT integrators
* all serial DYNAMO features for controls and constraints
GranFlow
* F90 + MPI
* spatial-decomposition parallelism
* frictional granular potentials
* NVE integrator
* boundary conditions for granular flow and packing and walls
* particle insertion
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

3103
doc/_sources/Section_howto.txt Normal file
View File

File diff suppressed because it is too large Load Diff

593
doc/_sources/Section_intro.txt Normal file
View File

@ -0,0 +1,593 @@
Introduction
============
This section provides an overview of what LAMMPS can and can't do,
describes what it means for LAMMPS to be an open-source code, and
acknowledges the funding and people who have contributed to LAMMPS
over the years.
| 1.1 :ref:`What is LAMMPS <intro_1>`
| 1.2 :ref:`LAMMPS features <intro_2>`
| 1.3 :ref:`LAMMPS non-features <intro_3>`
| 1.4 :ref:`Open source distribution <intro_4>`
| 1.5 :ref:`Acknowledgments and citations <intro_5>`
|
.. _intro_1:
What is LAMMPS
--------------
LAMMPS is a classical molecular dynamics code that models an ensemble
of particles in a liquid, solid, or gaseous state. It can model
atomic, polymeric, biological, metallic, granular, and coarse-grained
systems using a variety of force fields and boundary conditions.
For examples of LAMMPS simulations, see the Publications page of the
`LAMMPS WWW Site <lws_>`_.
LAMMPS runs efficiently on single-processor desktop or laptop
machines, but is designed for parallel computers. It will run on any
parallel machine that compiles C++ and supports the `MPI <mpi_>`_
message-passing library. This includes distributed- or shared-memory
parallel machines and Beowulf-style clusters.
.. _mpi: http://www-unix.mcs.anl.gov/mpi
LAMMPS can model systems with only a few particles up to millions or
billions. See :doc:`Section_perf <Section_perf>` for information on
LAMMPS performance and scalability, or the Benchmarks section of the
`LAMMPS WWW Site <lws_>`_.
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. See :ref:`this section <intro_4>` for a
brief discussion of the open-source philosophy.
.. _gnu: http://www.gnu.org/copyleft/gpl.html
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 :doc:`Section_modify <Section_modify>`
for more details.
The current version of LAMMPS is written in C++. Earlier versions
were written in F77 and F90. See
:doc:`Section_history <Section_history>` for more information on
different versions. All versions can be downloaded from the `LAMMPS WWW Site <lws_>`_.
LAMMPS was originally developed under a US Department of Energy CRADA
(Cooperative Research and Development Agreement) between two DOE labs
and 3 companies. It is distributed by `Sandia National Labs <snl_>`_.
See :ref:`this section <intro_5>` for more information on LAMMPS funding and
individuals who have contributed to LAMMPS.
.. _snl: http://www.sandia.gov
In the most general sense, LAMMPS integrates Newton's equations of
motion for collections of atoms, molecules, or macroscopic particles
that interact via short- or long-range forces with a variety of
initial and/or boundary conditions. For computational efficiency
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. On parallel machines, LAMMPS uses spatial-decomposition
techniques to partition the simulation domain into small 3d
sub-domains, one of which is assigned to each processor. Processors
communicate and store "ghost" atom information for atoms that border
their sub-domain. LAMMPS is most efficient (in a parallel sense) for
systems whose particles fill a 3d rectangular box with roughly uniform
density. Papers with technical details of the algorithms used in
LAMMPS are listed in :ref:`this section <intro_5>`.
----------
.. _intro_2:
LAMMPS features
---------------
This section highlights LAMMPS features, with pointers to specific
commands which give more details. If LAMMPS doesn't have your
favorite interatomic potential, boundary condition, or atom type, see
:doc:`Section_modify <Section_modify>`, which describes how you can add
it to LAMMPS.
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(R) Xeon Phi(TM) coprocessors, 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 thru library interface or provided Python wrapper
* couple with other codes: LAMMPS calls other code, other code calls LAMMPS, umbrella code calls both
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
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
* manybody 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>`, :ref:`core/shell model <howto_26>`, :ref:`Drude dipole model <howto_27>`
* 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 `KIM archive <http://openkim.org>`_ of potentials via :doc:`pair kim <pair_kim>`
* hybrid potentials: multiple pair, bond, angle, dihedral, improper potentials can be used in one simulation
* overlaid potentials: superposition of multiple pair potentials
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
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, Parinello/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
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
Diagnostics
^^^^^^^^^^^
* see the various flavors of the :doc:`fix <fix>` and :doc:`compute <compute>` commands
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
Multi-replica models
^^^^^^^^^^^^^^^^^^^^
:doc:`nudged elastic band <neb>`
:doc:`parallel replica dynamics <prd>`
:doc:`temperature accelerated dynamics <tad>`
:doc:`parallel tempering <temper>`
Pre- and post-processing
^^^^^^^^^^^^^^^^^^^^^^^^
* Various pre- and post-processing serial tools are packaged
with LAMMPS; see these :doc:`doc pages <Section_tools>`.
* 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
Specialized features
^^^^^^^^^^^^^^^^^^^^
These are LAMMPS capabilities which you may not think of as typical
molecular dynamics options:
* :doc:`static <balance>` and :doc:`dynamic load-balancing <fix_balance>`
* :doc:`generalized aspherical particles <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>`
* :doc:`path-integral molecular dynamics (PIMD) <fix_ipi>` and :doc:`this as well <fix_pimd>`
* Monte Carlo via :doc:`GCMC <fix_gcmc>` and :doc:`tfMC <fix_tfmc>` and :doc:`atom swapping <fix_swap>`
* :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>`
----------
.. _intro_3:
LAMMPS non-features
-------------------
LAMMPS is designed to efficiently compute Newton's equations of motion
for a system of interacting particles. Many of the tools needed to
pre- and post-process the data for such simulations are not included
in the LAMMPS kernel for several reasons:
* the desire to keep LAMMPS simple
* they are not parallel operations
* other codes already do them
* limited development resources
Specifically, LAMMPS itself does not:
* run thru a GUI
* build molecular systems
* assign force-field coefficients automagically
* perform sophisticated analyses of your MD simulation
* visualize your MD simulation
* plot your output data
A few tools for pre- and post-processing tasks are provided as part of
the LAMMPS package; they are described in :doc:`this section <Section_tools>`. However, many people use other codes or
write their own tools for these tasks.
As noted above, our group has also written and released a separate
toolkit called `Pizza.py <pizza_>`_ which addresses some of the listed
bullets. It 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_>`_.
LAMMPS requires as input a list of initial atom coordinates and types,
molecular topology information, and force-field coefficients assigned
to all atoms and bonds. LAMMPS will not build molecular systems and
assign force-field parameters for you.
For atomic systems LAMMPS provides a :doc:`create_atoms <create_atoms>`
command which places atoms on solid-state lattices (fcc, bcc,
user-defined, etc). Assigning small numbers of force field
coefficients can be done via the :doc:`pair coeff <pair_coeff>`, :doc:`bond coeff <bond_coeff>`, :doc:`angle coeff <angle_coeff>`, etc commands.
For molecular systems or more complicated simulation geometries, users
typically use another code as a builder and convert its output to
LAMMPS input format, or write their own code to generate atom
coordinate and molecular topology for LAMMPS to read in.
For complicated molecular systems (e.g. a protein), a multitude of
topology information and hundreds of force-field coefficients must
typically be specified. We suggest you use a program like
`CHARMM <charmm_>`_ or `AMBER <amber_>`_ or other molecular builders to setup
such problems and dump its information to a file. You can then
reformat the file as LAMMPS input. Some of the tools in :doc:`this section <Section_tools>` can assist in this process.
Similarly, LAMMPS creates output files in a simple format. Most users
post-process these files with their own analysis tools or re-format
them for input into other programs, including visualization packages.
If you are convinced you need to compute something on-the-fly as
LAMMPS runs, see :doc:`Section_modify <Section_modify>` for a discussion
of how you can use the :doc:`dump <dump>` and :doc:`compute <compute>` and
:doc:`fix <fix>` commands to print out data of your choosing. Keep in
mind that complicated computations can slow down the molecular
dynamics timestepping, particularly if the computations are not
parallel, so it is often better to leave such analysis to
post-processing codes.
A very simple (yet fast) visualizer is provided with the LAMMPS
package - see the :ref:`xmovie <xmovie>` tool in :doc:`this section <Section_tools>`. It creates xyz projection views of
atomic coordinates and animates them. We find it very useful for
debugging purposes. For high-quality visualization we recommend the
following packages:
* `VMD <http://www.ks.uiuc.edu/Research/vmd>`_
* `AtomEye <http://mt.seas.upenn.edu/Archive/Graphics/A>`_
* `PyMol <http://pymol.sourceforge.net>`_
* `Raster3d <http://www.bmsc.washington.edu/raster3d/raster3d.html>`_
* `RasMol <http://www.openrasmol.org>`_
Other features that LAMMPS does not yet (and may never) support are
discussed in :doc:`Section_history <Section_history>`.
Finally, these are freely-available molecular dynamics codes, most of
them parallel, which may be well-suited to the problems you want to
model. They can also be used in conjunction with LAMMPS to perform
complementary modeling tasks.
* `CHARMM <charmm_>`_
* `AMBER <amber_>`_
* `NAMD <namd_>`_
* `NWCHEM <nwchem_>`_
* `DL_POLY <dlpoly_>`_
* `Tinker <tinker_>`_
.. _charmm: http://www.scripps.edu/brooks
.. _amber: http://amber.scripps.edu
.. _namd: http://www.ks.uiuc.edu/Research/namd/
.. _nwchem: http://www.emsl.pnl.gov/docs/nwchem/nwchem.html
.. _dlpoly: http://www.cse.clrc.ac.uk/msi/software/DL_POLY
.. _tinker: http://dasher.wustl.edu/tinker
CHARMM, AMBER, NAMD, NWCHEM, and Tinker are designed primarily for
modeling biological molecules. CHARMM and AMBER use
atom-decomposition (replicated-data) strategies for parallelism; NAMD
and NWCHEM use spatial-decomposition approaches, similar to LAMMPS.
Tinker is a serial code. DL_POLY includes potentials for a variety of
biological and non-biological materials; both a replicated-data and
spatial-decomposition version exist.
----------
.. _intro_4:
Open source distribution
------------------------
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_>`_ for more
details. The legal text of the GPL is in the LICENSE file that is
included in the LAMMPS distribution.
.. _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.
In the spirit of an open-source code, these are various ways you can
contribute to making LAMMPS better. You can send email to the
`developers <http://lammps.sandia.gov/authors.html>`_ on any of these
items.
* Point prospective users to the `LAMMPS WWW Site <lws_>`_. Mention it in
talks or link to it from your WWW site.
* If you find an error or omission in this manual or on the `LAMMPS WWW Site <lws_>`_, or have a suggestion for something to clarify or include,
send an email to the
`developers <http://lammps.sandia.gov/authors.html>`_.
* If you find a bug, :ref:`Section_errors 2 <err_2>`
describes how to report it.
* If you publish a paper using LAMMPS results, send the citation (and
any cool pictures or movies if you like) to add to the Publications,
Pictures, and Movies pages of the `LAMMPS WWW Site <lws_>`_, with links
and attributions back to you.
* Create a new Makefile.machine that can be added to the src/MAKE
directory.
* The tools sub-directory of the LAMMPS distribution has various
stand-alone codes for pre- and post-processing of LAMMPS data. More
details are given in :doc:`Section_tools <Section_tools>`. If you write
a new tool that users will find useful, it can be added to the LAMMPS
distribution.
* LAMMPS is designed to be easy to extend with new code for features
like potentials, boundary conditions, diagnostic computations, etc.
:doc:`This section <Section_modify>` gives details. If you add a
feature of general interest, it can be added to the LAMMPS
distribution.
* The Benchmark page of the `LAMMPS WWW Site <lws_>`_ lists LAMMPS
performance on various platforms. The files needed to run the
benchmarks are part of the LAMMPS distribution. If your machine is
sufficiently different from those listed, your timing data can be
added to the page.
* You can send feedback for the User Comments page of the `LAMMPS WWW Site <lws_>`_. It might be added to the page. No promises.
* Cash. Small denominations, unmarked bills preferred. Paper sack OK.
Leave on desk. VISA also accepted. Chocolate chip cookies
encouraged.
----------
.. _intro_5:
Acknowledgments and citations
-------------------------------------------
LAMMPS development has been funded by the `US Department of Energy <doe_>`_ (DOE), through its CRADA, LDRD, ASCI, and Genomes-to-Life
programs and its `OASCR <oascr_>`_ and `OBER <ober_>`_ offices.
Specifically, work on the latest version was funded in part by the US
Department of Energy's Genomics:GTL program
(`www.doegenomestolife.org <gtl_>`_) under the `project <ourgtl_>`_, "Carbon
Sequestration in Synechococcus Sp.: From Molecular Machines to
Hierarchical Modeling".
.. _doe: http://www.doe.gov
.. _gtl: http://www.doegenomestolife.org
.. _ourgtl: http://www.genomes2life.org
.. _oascr: http://www.sc.doe.gov/ascr/home.html
.. _ober: http://www.er.doe.gov/production/ober/ober_top.html
The following paper describe the basic parallel algorithms used in
LAMMPS. If you use LAMMPS results in your published work, please cite
this paper and include a pointer to the `LAMMPS WWW Site <lws_>`_
(http://lammps.sandia.gov):
S. J. Plimpton, **Fast Parallel Algorithms for Short-Range Molecular
Dynamics**, J Comp Phys, 117, 1-19 (1995).
Other papers describing specific algorithms used in LAMMPS are listed
under the `Citing LAMMPS link <http://lammps.sandia.gov/cite.html>`_ of
the LAMMPS WWW page.
The `Publications link <http://lammps.sandia.gov/papers.html>`_ on the
LAMMPS WWW page lists papers that have cited LAMMPS. If your paper is
not listed there for some reason, feel free to send us the info. If
the simulations in your paper produced cool pictures or animations,
we'll be pleased to add them to the
`Pictures <http://lammps.sandia.gov/pictures.html>`_ or
`Movies <http://lammps.sandia.gov/movies.html>`_ pages of the LAMMPS WWW
site.
The core group of LAMMPS developers is at Sandia National Labs:
* Steve Plimpton, sjplimp at sandia.gov
* Aidan Thompson, athomps at sandia.gov
* Paul Crozier, pscrozi at sandia.gov
The following folks are responsible for significant contributions to
the code, or other aspects of the LAMMPS development effort. Many of
the packages they have written are somewhat unique to LAMMPS and the
code would not be as general-purpose as it is without their expertise
and efforts.
* Axel Kohlmeyer (Temple U), akohlmey at gmail.com, SVN and Git repositories, indefatigable mail list responder, USER-CG-CMM and USER-OMP packages
* Roy Pollock (LLNL), Ewald and PPPM solvers
* Mike Brown (ORNL), brownw at ornl.gov, GPU package
* Greg Wagner (Sandia), gjwagne at sandia.gov, MEAM package for MEAM potential
* Mike Parks (Sandia), mlparks at sandia.gov, PERI package for Peridynamics
* Rudra Mukherjee (JPL), Rudranarayan.M.Mukherjee at jpl.nasa.gov, POEMS package for articulated rigid body motion
* Reese Jones (Sandia) and collaborators, rjones at sandia.gov, USER-ATC package for atom/continuum coupling
* Ilya Valuev (JIHT), valuev at physik.hu-berlin.de, USER-AWPMD package for wave-packet MD
* Christian Trott (U Tech Ilmenau), christian.trott at tu-ilmenau.de, USER-CUDA package
* Andres Jaramillo-Botero (Caltech), ajaramil at wag.caltech.edu, USER-EFF package for electron force field
* Christoph Kloss (JKU), Christoph.Kloss at jku.at, USER-LIGGGHTS package for granular models and granular/fluid coupling
* Metin Aktulga (LBL), hmaktulga at lbl.gov, USER-REAXC package for C version of ReaxFF
* Georg Gunzenmuller (EMI), georg.ganzenmueller at emi.fhg.de, USER-SPH package
As discussed in :doc:`Section_history <Section_history>`, 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 (LLNL)
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

984
doc/_sources/Section_modify.txt Normal file
View File

@ -0,0 +1,984 @@
Modifying & extending LAMMPS
============================
This section describes how to customize LAMMPS by modifying
and extending its source code.
| 10.1 :ref:`Atom styles <mod_1>`
| 10.2 :ref:`Bond, angle, dihedral, improper potentials <mod_2>`
| 10.3 :ref:`Compute styles <mod_3>`
| 10.4 :ref:`Dump styles <mod_4>`
| 10.5 :ref:`Dump custom output options <mod_5>`
| 10.6 :ref:`Fix styles <mod_6>` which include integrators, temperature and pressure control, force constraints, boundary conditions, diagnostic output, etc
| 10.7 :ref:`Input script commands <mod_7>`
| 10.8 :ref:`Kspace computations <mod_8>`
| 10.9 :ref:`Minimization styles <mod_9>`
| 10.10 :ref:`Pairwise potentials <mod_10>`
| 10.11 :ref:`Region styles <mod_11>`
| 10.12 :ref:`Body styles <mod_12>`
| 10.13 :ref:`Thermodynamic output options <mod_13>`
| 10.14 :ref:`Variable options <mod_14>`
| 10.15 :ref:`Submitting new features for inclusion in LAMMPS <mod_15>`
|
LAMMPS is designed in a modular fashion so as to be easy to modify and
extend with new functionality. In fact, about 75% of its source code
is files added in this fashion.
In this section, changes and additions users can make are listed along
with minimal instructions. If you add a new feature to LAMMPS and
think it will be of interest to general users, we encourage you to
submit it to the developers for inclusion in the released version of
LAMMPS. Information about how to do this is provided
:ref:`below <mod_14>`.
The best way to add a new feature is to find a similar feature in
LAMMPS and look at the corresponding source and header files to figure
out what it does. You will need some knowledge of C++ to be able to
understand the hi-level structure of LAMMPS and its class
organization, but functions (class methods) that do actual
computations are written in vanilla C-style code and operate on simple
C-style data structures (vectors and arrays).
Most of the new features described in this section require you to
write a new C++ derived class (except for exceptions described below,
where you can make small edits to existing files). Creating a new
class requires 2 files, a source code file (*.cpp) and a header file
(*.h). The derived class must provide certain methods to work as a
new option. Depending on how different your new feature is compared
to existing features, you can either derive from the base class
itself, or from a derived class that already exists. Enabling LAMMPS
to invoke the new class is as simple as putting the two source
files in the src dir and re-building LAMMPS.
The advantage of C++ and its object-orientation is that all the code
and variables needed to define the new feature are in the 2 files you
write, and thus shouldn't make the rest of LAMMPS more complex or
cause side-effect bugs.
Here is a concrete example. Suppose you write 2 files pair_foo.cpp
and pair_foo.h that define a new class PairFoo that computes pairwise
potentials described in the classic 1997 :ref:`paper <Foo>` by Foo, et al.
If you wish to invoke those potentials in a LAMMPS input script with a
command like
.. parsed-literal::
pair_style foo 0.1 3.5
then your pair_foo.h file should be structured as follows:
.. parsed-literal::
#ifdef PAIR_CLASS
PairStyle(foo,PairFoo)
#else
...
(class definition for PairFoo)
...
#endif
where "foo" is the style keyword in the pair_style command, and
PairFoo is the class name defined in your pair_foo.cpp and pair_foo.h
files.
When you re-build LAMMPS, your new pairwise potential becomes part of
the executable and can be invoked with a pair_style command like the
example above. Arguments like 0.1 and 3.5 can be defined and
processed by your new class.
As illustrated by this pairwise example, many kinds of options are
referred to in the LAMMPS documentation as the "style" of a particular
command.
The instructions below give the header file for the base class that
these styles are derived from. Public variables in that file are ones
used and set by the derived classes which are also used by the base
class. Sometimes they are also used by the rest of LAMMPS. Virtual
functions in the base class header file which are set = 0 are ones you
must define in your new derived class to give it the functionality
LAMMPS expects. Virtual functions that are not set to 0 are functions
you can optionally define.
Additionally, new output options can be added directly to the
thermo.cpp, dump_custom.cpp, and variable.cpp files as explained
below.
Here are additional guidelines for modifying LAMMPS and adding new
functionality:
* Think about whether what you want to do would be better as a pre- or
post-processing step. Many computations are more easily and more
quickly done that way.
* Don't do anything within the timestepping of a run that isn't
parallel. E.g. don't accumulate a bunch of data on a single processor
and analyze it. You run the risk of seriously degrading the parallel
efficiency.
* If your new feature reads arguments or writes output, make sure you
follow the unit conventions discussed by the :doc:`units <units>`
command.
* If you add something you think is truly useful and doesn't impact
LAMMPS performance when it isn't used, send an email to the
`developers <http://lammps.sandia.gov/authors.html>`_. We might be
interested in adding it to the LAMMPS distribution. See further
details on this at the bottom of this page.
.. _mod_1:
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 | retreive 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 | retreive 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 | retreive 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.
----------
.. _mod_2:
Bond, angle, dihedral, improper potentials
------------------------------------------
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) |
+----------------------+---------------------------------------------------------------------------+
----------
.. _mod_3:
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.
----------
.. _mod_4:
Dump styles
-----------
.. _mod_5:
Dump custom output options
--------------------------
Classes that dump per-atom info to files are derived from the Dump
class. To dump new quantities or in a new format, a new derived dump
class can be added, but it is typically simpler to modify the
DumpCustom class contained in the dump_custom.cpp file.
Dump_atom.cpp is a simple example of a derived dump class.
Here is a brief description of methods you define in your new derived
class. See dump.h for details.
+--------------+---------------------------------------------------+
| write_header | write the header section of a snapshot of atoms |
+--------------+---------------------------------------------------+
| count | count the number of lines a processor will output |
+--------------+---------------------------------------------------+
| pack | pack a proc's output data into a buffer |
+--------------+---------------------------------------------------+
| write_data | write a proc's data to a file |
+--------------+---------------------------------------------------+
See the :doc:`dump <dump>` command and its *custom* style for a list of
keywords for atom information that can already be dumped by
DumpCustom. It includes options to dump per-atom info from Compute
classes, so adding a new derived Compute class is one way to calculate
new quantities to dump.
Alternatively, you can add new keywords to the dump custom command.
Search for the word "customize" in dump_custom.cpp to see the
half-dozen or so locations where code will need to be added.
----------
.. _mod_6:
Fix styles
----------
In LAMMPS, a "fix" is any operation that is computed during
timestepping that alters some property of the system. Essentially
everything that happens during a simulation besides force computation,
neighbor list construction, and output, is a "fix". This includes
time integration (update of coordinates and velocities), force
constraints or boundary conditions (SHAKE or walls), and diagnostics
(compute a diffusion coefficient). New styles can be created to add
new options to LAMMPS.
Fix_setforce.cpp is a simple example of setting forces on atoms to
prescribed values. There are dozens of fix options already in LAMMPS;
choose one as a template that is similar to what you want to
implement.
Here is a brief description of methods you can define in your new
derived class. See fix.h for details.
+-------------------------+-------------------------------------------------------------------------------------------+
| setmask | determines when the fix is called during the timestep (required) |
+-------------------------+-------------------------------------------------------------------------------------------+
| init | initialization before a run (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| setup_pre_exchange | called before atom exchange in setup (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| setup_pre_force | called before force computation in setup (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| setup | called immediately before the 1st timestep and after forces are computed (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_setup_pre_force | like setup_pre_force, but for minimizations instead of MD runs (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_setup | like setup, but for minimizations instead of MD runs (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| initial_integrate | called at very beginning of each timestep (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pre_exchange | called before atom exchange on re-neighboring steps (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pre_neighbor | called before neighbor list build (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pre_force | called before pair & molecular forces are computed (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| post_force | called after pair & molecular forces are computed and communicated (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| final_integrate | called at end of each timestep (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| end_of_step | called at very end of timestep (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| write_restart | dumps fix info to restart file (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| restart | uses info from restart file to re-initialize the fix (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| grow_arrays | allocate memory for atom-based arrays used by fix (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| copy_arrays | copy atom info when an atom migrates to a new processor (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pack_exchange | store atom's data in a buffer (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| unpack_exchange | retrieve atom's data from a buffer (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pack_restart | store atom's data for writing to restart file (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| unpack_restart | retrieve atom's data from a restart file buffer (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| size_restart | size of atom's data (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| maxsize_restart | max size of atom's data (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| setup_pre_force_respa | same as setup_pre_force, but for rRESPA (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| initial_integrate_respa | same as initial_integrate, but for rRESPA (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| post_integrate_respa | called after the first half integration step is done in rRESPA (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pre_force_respa | same as pre_force, but for rRESPA (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| post_force_respa | same as post_force, but for rRESPA (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| final_integrate_respa | same as final_integrate, but for rRESPA (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_pre_force | called after pair & molecular forces are computed in minimizer (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_post_force | called after pair & molecular forces are computed and communicated in minmizer (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_store | store extra data for linesearch based minimization on a LIFO stack (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_pushstore | push the minimization LIFO stack one element down (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_popstore | pop the minimization LIFO stack one element up (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_clearstore | clear minimization LIFO stack (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_step | reset or move forward on line search minimization (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_dof | report number of degrees of freedom *added* by this fix in minimization (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| max_alpha | report maximum allowed step size during linesearch minimization (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pack_comm | pack a buffer to communicate a per-atom quantity (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| unpack_comm | unpack a buffer to communicate a per-atom quantity (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pack_reverse_comm | pack a buffer to reverse communicate a per-atom quantity (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| unpack_reverse_comm | unpack a buffer to reverse communicate a per-atom quantity (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| dof | report number of degrees of freedom *removed* by this fix during MD (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| compute_scalar | return a global scalar property that the fix computes (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| compute_vector | return a component of a vector property that the fix computes (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| compute_array | return a component of an array property that the fix computes (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| deform | called when the box size is changed (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| reset_target | called when a change of the target temperature is requested during a run (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| reset_dt | is called when a change of the time step is requested during a run (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| modify_param | called when a fix_modify request is executed (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| memory_usage | report memory used by fix (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| thermo | compute quantities for thermodynamic output (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
Typically, only a small fraction of these methods are defined for a
particular fix. Setmask is mandatory, as it determines when the fix
will be invoked during the timestep. Fixes that perform time
integration (*nve*, *nvt*, *npt*) implement initial_integrate() and
final_integrate() to perform velocity Verlet updates. Fixes that
constrain forces implement post_force().
Fixes that perform diagnostics typically implement end_of_step(). For
an end_of_step fix, one of your fix arguments must be the variable
"nevery" which is used to determine when to call the fix and you must
set this variable in the constructor of your fix. By convention, this
is the first argument the fix defines (after the ID, group-ID, style).
If the fix needs to store information for each atom that persists from
timestep to timestep, it can manage that memory and migrate the info
with the atoms as they move from processors to processor by
implementing the grow_arrays, copy_arrays, pack_exchange, and
unpack_exchange methods. Similarly, the pack_restart and
unpack_restart methods can be implemented to store information about
the fix in restart files. If you wish an integrator or force
constraint fix to work with rRESPA (see the :doc:`run_style <run_style>`
command), the initial_integrate, post_force_integrate, and
final_integrate_respa methods can be implemented. The thermo method
enables a fix to contribute values to thermodynamic output, as printed
quantities and/or to be summed to the potential energy of the system.
----------
.. _mod_7:
Input script commands
---------------------
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.
----------
.. _mod_8:
Kspace computations
-------------------
Classes that compute long-range Coulombic interactions via K-space
representations (Ewald, PPPM) are derived from the KSpace class. New
styles can be created to add new K-space options to LAMMPS.
Ewald.cpp is an example of computing K-space interactions.
Here is a brief description of methods you define in your new derived
class. See kspace.h for details.
+--------------+----------------------------------------------+
| init | initialize the calculation before a run |
+--------------+----------------------------------------------+
| setup | computation before the 1st timestep of a run |
+--------------+----------------------------------------------+
| compute | every-timestep computation |
+--------------+----------------------------------------------+
| memory_usage | tally of memory usage |
+--------------+----------------------------------------------+
----------
.. _mod_9:
Minimization styles
-------------------
Classes that perform energy minimization derived from the Min class.
New styles can be created to add new minimization algorithms to
LAMMPS.
Min_cg.cpp is an example of conjugate gradient minimization.
Here is a brief description of methods you define in your new derived
class. See min.h for details.
+--------------+------------------------------------------+
| init | initialize the minimization before a run |
+--------------+------------------------------------------+
| run | perform the minimization |
+--------------+------------------------------------------+
| memory_usage | tally of memory usage |
+--------------+------------------------------------------+
----------
.. _mod_10:
Pairwise potentials
-------------------
Classes that compute pairwise interactions are derived from the Pair
class. In LAMMPS, pairwise calculation include manybody potentials
such as EAM or Tersoff where particles interact without a static bond
topology. New styles can be created to add new pair potentials to
LAMMPS.
Pair_lj_cut.cpp is a simple example of a Pair class, though it
includes some optional methods to enable its use with rRESPA.
Here is a brief description of the class methods in pair.h:
+-------------------------------+-------------------------------------------------------------------+
| compute | workhorse routine that computes pairwise interactions |
+-------------------------------+-------------------------------------------------------------------+
| settings | reads the input script line with arguments you define |
+-------------------------------+-------------------------------------------------------------------+
| coeff | set coefficients for one i,j type pair |
+-------------------------------+-------------------------------------------------------------------+
| init_one | perform initialization for one i,j type pair |
+-------------------------------+-------------------------------------------------------------------+
| init_style | initialization specific to this pair style |
+-------------------------------+-------------------------------------------------------------------+
| write & read_restart | write/read i,j pair coeffs to restart files |
+-------------------------------+-------------------------------------------------------------------+
| write & read_restart_settings | write/read global settings to restart files |
+-------------------------------+-------------------------------------------------------------------+
| single | force and energy of a single pairwise interaction between 2 atoms |
+-------------------------------+-------------------------------------------------------------------+
| compute_inner/middle/outer | versions of compute used by rRESPA |
+-------------------------------+-------------------------------------------------------------------+
The inner/middle/outer routines are optional.
----------
.. _mod_11:
Region styles
-------------
Classes that define geometric regions are derived from the Region
class. Regions are used elsewhere in LAMMPS to group atoms, delete
atoms to create a void, insert atoms in a specified region, etc. New
styles can be created to add new region shapes to LAMMPS.
Region_sphere.cpp is an example of a spherical region.
Here is a brief description of methods you define in your new derived
class. See region.h for details.
+-------+--------------------------------------------+
| match | determine whether a point is in the region |
+-------+--------------------------------------------+
----------
.. _mod_12:
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 :ref:`Section_howto 14 <howto_14>` of the manual for
an overview of using body particles and the :doc:`body <body>` doc page
for details on 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 |
+--------------------+-----------------------------------------------------------+
----------
.. _mod_13:
Thermodynamic output options
----------------------------
There is one class that computes and prints thermodynamic information
to the screen and log file; see the file thermo.cpp.
There are two styles defined in thermo.cpp: "one" and "multi". There
is also a flexible "custom" style which allows the user to explicitly
list keywords for quantities to print when thermodynamic info is
output. See the :doc:`thermo_style <thermo_style>` command for a list
of defined quantities.
The thermo styles (one, multi, etc) are simply lists of keywords.
Adding a new style thus only requires defining a new list of keywords.
Search for the word "customize" with references to "thermo style" in
thermo.cpp to see the two locations where code will need to be added.
New keywords can also be added to thermo.cpp to compute new quantities
for output. Search for the word "customize" with references to
"keyword" in thermo.cpp to see the several locations where code will
need to be added.
Note that the :doc:`thermo_style custom <thermo>` command already allows
for thermo output of quantities calculated by :doc:`fixes <fix>`,
:doc:`computes <compute>`, and :doc:`variables <variable>`. Thus, it may
be simpler to compute what you wish via one of those constructs, than
by adding a new keyword to the thermo command.
----------
.. _mod_14:
Variable options
----------------
There is one class that computes and stores :doc:`variable <variable>`
information in LAMMPS; see the file variable.cpp. The value
associated with a variable can be periodically printed to the screen
via the :doc:`print <print>`, :doc:`fix print <fix_print>`, or
:doc:`thermo_style custom <thermo_style>` commands. Variables of style
"equal" can compute complex equations that involve the following types
of arguments:
.. parsed-literal::
thermo keywords = ke, vol, atoms, ...
other variables = v_a, v_myvar, ...
math functions = div(x,y), mult(x,y), add(x,y), ...
group functions = mass(group), xcm(group,x), ...
atom values = x[123], y[3], vx[34], ...
compute values = c_mytemp[0], c_thermo_press[3], ...
Adding keywords for the :doc:`thermo_style custom <thermo_style>` command
(which can then be accessed by variables) was discussed
:ref:`here <thermo>` on this page.
Adding a new math function of one or two arguments can be done by
editing one section of the Variable::evaulate() method. Search for
the word "customize" to find the appropriate location.
Adding a new group function can be done by editing one section of the
Variable::evaulate() method. Search for the word "customize" to find
the appropriate location. You may need to add a new method to the
Group class as well (see the group.cpp file).
Accessing a new atom-based vector can be done by editing one section
of the Variable::evaulate() method. Search for the word "customize"
to find the appropriate location.
Adding new :doc:`compute styles <compute>` (whose calculated values can
then be accessed by variables) was discussed
:ref:`here <compute>` on this page.
.. _mod_15:
Submitting new features for inclusion in LAMMPS
-----------------------------------------------
We encourage users to submit new features to `the developers <http://lammps.sandia.gov/authors.html>`_ that they add to
LAMMPS, especially if you think they will be of interest to other
users. If they are broadly useful we may add them as core files to
LAMMPS or as part of a :ref:`standard package <start_3>`.
Else we will add them as a user-contributed file or package. Examples
of user packages are in src sub-directories that start with USER. The
USER-MISC package is simply a collection of (mostly) unrelated single
files, which is the simplest way to have your contribution quickly
added to the LAMMPS distribution. You can see a list of the both
standard and user packages by typing "make package" in the LAMMPS src
directory.
Note that by providing us the files to release, you are agreeing to
make them open-source, i.e. we can release them under the terms of the
GPL, used as a license for the rest of LAMMPS. See :ref:`Section 1.4 <intro_4>` for details.
With user packages and files, all we are really providing (aside from
the fame and fortune that accompanies having your name in the source
code and on the `Authors page <http://lammps.sandia.gov/authors.html>`_
of the `LAMMPS WWW site <lws_>`_), is a means for you to distribute your
work to the LAMMPS user community, and a mechanism for others to
easily try out your new feature. This may help you find bugs or make
contact with new collaborators. Note that you're also implicitly
agreeing to support your code which means answer questions, fix bugs,
and maintain it if LAMMPS changes in some way that breaks it (an
unusual event).
.. note::
If you prefer to actively develop and support your add-on
feature yourself, then you may wish to make it available for download
from your own website, as a user package that LAMMPS users can add to
their copy of LAMMPS. See the `Offsite LAMMPS packages and tools <http://lammps.sandia.gov/offsite.html>`_ page of the LAMMPS web
site for examples of groups that do this. We are happy to advertise
your package and web site from that page. Simply email the
`developers <http://lammps.sandia.gov/authors.html>`_ with info about
your package and we will post it there.
The previous sections of this doc page describe how to add new "style"
files of various kinds to LAMMPS. Packages are simply collections of
one or more new class files which are invoked as a new style within a
LAMMPS input script. If designed correctly, these additions typically
do not require changes to the main core of LAMMPS; they are simply
add-on files. If you think your new feature requires non-trivial
changes in core LAMMPS files, you'll need to `communicate with the developers <http://lammps.sandia.gov/authors.html>`_, since we may or may
not want to make those changes. An example of a trivial change is
making a parent-class method "virtual" when you derive a new child
class from it.
Here are the steps you need to follow to submit a single file or user
package for our consideration. Following these steps will save both
you and us time. See existing files in packages in the src dir for
examples.
* All source files you provide must compile with the most current
version of LAMMPS.
* If you want your file(s) to be added to main LAMMPS or one of its
standard packages, then it needs to be written in a style compatible
with other LAMMPS source files. This is so the developers can
understand it and hopefully maintain it. This basically means that
the code accesses data structures, performs its operations, and is
formatted similar to other LAMMPS source files, including the use of
the error class for error and warning messages.
* If you want your contribution to be added as a user-contributed
feature, and it's a single file (actually a *.cpp and *.h file) it can
rapidly be added to the USER-MISC directory. Send us the one-line
entry to add to the USER-MISC/README file in that dir, along with the
2 source files. You can do this multiple times if you wish to
contribute several individual features.
* If you want your contribution to be added as a user-contribution and
it is several related featues, it is probably best to make it a user
package directory with a name like USER-FOO. In addition to your new
files, the directory should contain a README text file. The README
should contain your name and contact information and a brief
description of what your new package does. If your files depend on
other LAMMPS style files also being installed (e.g. because your file
is a derived class from the other LAMMPS class), then an Install.sh
file is also needed to check for those dependencies. See other README
and Install.sh files in other USER directories as examples. Send us a
tarball of this USER-FOO directory.
* Your new source files need to have the LAMMPS copyright, GPL notice,
and your name and email address at the top, like other
user-contributed LAMMPS source files. They need to create a class
that is inside the LAMMPS namespace. If the file is for one of the
USER packages, including USER-MISC, then we are not as picky about the
coding style (see above). I.e. the files do not need to be in the
same stylistic format and syntax as other LAMMPS files, though that
would be nice for developers as well as users who try to read your
code.
* You must also create a documentation file for each new command or
style you are adding to LAMMPS. This will be one file for a
single-file feature. For a package, it might be several files. These
are simple text files which we auto-convert to HTML. Thus they must
be in the same format as other *.txt files in the lammps/doc directory
for similar commands and styles; use one or more of them as a starting
point. As appropriate, the text files can include links to equations
(see doc/Eqs/*.tex for examples, we auto-create the associated JPG
files), or figures (see doc/JPG for examples), or even additional PDF
files with further details (see doc/PDF for examples). The doc page
should also include literature citations as appropriate; see the
bottom of doc/fix_nh.txt for examples and the earlier part of the same
file for how to format the cite itself. The "Restrictions" section of
the doc page should indicate that your command is only available if
LAMMPS is built with the appropriate USER-MISC or USER-FOO package.
See other user package doc files for examples of how to do this. The
txt2html tool we use to convert to HTML can be downloaded from `this site <http://www.sandia.gov/~sjplimp/download.html>`_, so you can perform
the HTML conversion yourself to proofread your doc page.
* For a new package (or even a single command) you can include one or
more example scripts. These should run in no more than 1 minute, even
on a single processor, and not require large data files as input. See
directories under examples/USER for examples of input scripts other
users provided for their packages.
* If there is a paper of yours describing your feature (either the
algorithm/science behind the feature itself, or its initial usage, or
its implementation in LAMMPS), you can add the citation to the *.cpp
source file. See src/USER-EFF/atom_vec_electron.cpp for an example.
A LaTeX citation is stored in a variable at the top of the file and a
single line of code that references the variable is added to the
constructor of the class. Whenever a user invokes your feature from
their input script, this will cause LAMMPS to output the citation to a
log.cite file and prompt the user to examine the file. Note that you
should only use this for a paper you or your group authored.
E.g. adding a cite in the code for a paper by Nose and Hoover if you
write a fix that implements their integrator is not the intended
usage. That kind of citation should just be in the doc page you
provide.
Finally, as a general rule-of-thumb, the more clear and
self-explanatory you make your doc and README files, and the easier
you make it for people to get started, e.g. by providing example
scripts, the more likely it is that users will try out your new
feature.
.. _Foo:
**(Foo)** Foo, Morefoo, and Maxfoo, J of Classic Potentials, 75, 345 (1997).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

1017
doc/_sources/Section_packages.txt Normal file
View File

File diff suppressed because it is too large Load Diff

74
doc/_sources/Section_perf.txt Normal file
View File

@ -0,0 +1,74 @@
Performance & scalability
=========================
LAMMPS performance on several prototypical benchmarks and machines is
discussed on the Benchmarks page of the `LAMMPS WWW Site <lws_>`_ where
CPU timings and parallel efficiencies are listed. Here, the
benchmarks are described briefly and some useful rules of thumb about
their performance are highlighted.
These are the 5 benchmark problems:
#. LJ = atomic fluid, Lennard-Jones potential with 2.5 sigma cutoff (55
neighbors per atom), NVE integration
#. Chain = bead-spring polymer melt of 100-mer chains, FENE bonds and LJ
pairwise interactions with a 2^(1/6) sigma cutoff (5 neighbors per
atom), NVE integration
#. EAM = metallic solid, Cu EAM potential with 4.95 Angstrom cutoff (45
neighbors per atom), NVE integration
#. Chute = granular chute flow, frictional history potential with 1.1
sigma cutoff (7 neighbors per atom), NVE integration
#. Rhodo = rhodopsin protein in solvated lipid bilayer, CHARMM force
field with a 10 Angstrom LJ cutoff (440 neighbors per atom),
particle-particle particle-mesh (PPPM) for long-range Coulombics, NPT
integration
The input files for running the benchmarks are included in the LAMMPS
distribution, as are sample output files. Each of the 5 problems has
32,000 atoms and runs for 100 timesteps. Each can be run as a serial
benchmarks (on one processor) or in parallel. In parallel, each
benchmark can be run as a fixed-size or scaled-size problem. For
fixed-size benchmarking, the same 32K atom problem is run on various
numbers of processors. For scaled-size benchmarking, the model size
is increased with the number of processors. E.g. on 8 processors, a
256K-atom problem is run; on 1024 processors, a 32-million atom
problem is run, etc.
A useful metric from the benchmarks is the CPU cost per atom per
timestep. Since LAMMPS performance scales roughly linearly with
problem size and timesteps, the run time of any problem using the same
model (atom style, force field, cutoff, etc) can then be estimated.
For example, on a 1.7 GHz Pentium desktop machine (Intel icc compiler
under Red Hat Linux), the CPU run-time in seconds/atom/timestep for
the 5 problems is
+----------------+---------+---------+---------+---------+-----------+
| Problem: | LJ | Chain | EAM | Chute | Rhodopsin |
+----------------+---------+---------+---------+---------+-----------+
| CPU/atom/step: | 4.55E-6 | 2.18E-6 | 9.38E-6 | 2.18E-6 | 1.11E-4 |
+----------------+---------+---------+---------+---------+-----------+
| Ratio to LJ: | 1.0 | 0.48 | 2.06 | 0.48 | 24.5 |
+----------------+---------+---------+---------+---------+-----------+
The ratios mean that if the atomic LJ system has a normalized cost of
1.0, the bead-spring chains and granular systems run 2x faster, while
the EAM metal and solvated protein models run 2x and 25x slower
respectively. The bulk of these cost differences is due to the
expense of computing a particular pairwise force field for a given
number of neighbors per atom.
Performance on a parallel machine can also be predicted from the
one-processor timings if the parallel efficiency can be estimated.
The communication bandwidth and latency of a particular parallel
machine affects the efficiency. On most machines LAMMPS will give
fixed-size parallel efficiencies on these benchmarks above 50% so long
as the atoms/processor count is a few 100 or greater - i.e. on 64 to
128 processors. Likewise, scaled-size parallel efficiencies will
typically be 80% or greater up to very large processor counts. The
benchmark data on the `LAMMPS WWW Site <lws_>`_ gives specific examples on
some different machines, including a run of 3/4 of a billion LJ atoms
on 1500 processors that ran at 85% parallel efficiency.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

1009
doc/_sources/Section_python.txt Normal file
View File

File diff suppressed because it is too large Load Diff

2154
doc/_sources/Section_start.txt Normal file
View File

File diff suppressed because it is too large Load Diff

737
doc/_sources/Section_tools.txt Normal file
View File

@ -0,0 +1,737 @@
Additional tools
================
LAMMPS is designed to be a computational kernel for performing
molecular dynamics computations. Additional pre- and post-processing
steps are often necessary to setup and analyze a simulation. A few
additional tools are provided with the LAMMPS distribution and are
described in this section.
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
Note that many users write their own setup or analysis tools or use
other existing codes and convert their output to a LAMMPS input format
or vice versa. The tools listed here are included in the LAMMPS
distribution as examples of auxiliary tools. Some of them are not
actively supported by Sandia, as they were contributed by LAMMPS
users. If you have problems using them, we can direct you to the
authors.
The source code for each of these codes is in the tools sub-directory
of the LAMMPS distribution. There is a Makefile (which you may need
to edit for your platform) which will build several of the tools which
reside in that directory. Some of them are larger packages in their
own sub-directories with their own Makefiles.
* :ref:`amber2lmp <amber>`
* :ref:`binary2txt <binary>`
* :ref:`ch2lmp <charmm>`
* :ref:`chain <chain>`
* :ref:`colvars <colvars>`
* :ref:`createatoms <create>`
* :ref:`data2xmovie <data>`
* :ref:`eam database <eamdb>`
* :ref:`eam generate <eamgn>`
* :ref:`eff <eff>`
* :ref:`emacs <emacs>`
* :ref:`fep <fep>`
* :ref:`i-pi <ipi>`
* :ref:`ipp <ipp>`
* :ref:`kate <kate>`
* :ref:`lmp2arc <arc>`
* :ref:`lmp2cfg <cfg>`
* :ref:`lmp2vmd <vmd>`
* :ref:`matlab <matlab>`
* :ref:`micelle2d <micelle>`
* :ref:`moltemplate <moltemplate>`
* :ref:`msi2lmp <msi>`
* :ref:`phonon <phonon>`
* :ref:`polymer bonding <polybond>`
* :ref:`pymol_asphere <pymol>`
* :ref:`python <pythontools>`
* :ref:`reax <reax>`
* :ref:`restart2data <restart>`
* :ref:`vim <vim>`
* :ref:`xmgrace <xmgrace>`
* :ref:`xmovie <xmovie>`
----------
.. _amber:
amber2lmp tool
--------------------------
The amber2lmp sub-directory contains two Python scripts for converting
files back-and-forth between the AMBER MD code and LAMMPS. See the
README file in amber2lmp for more information.
These tools were written by Keir Novik while he was at Queen Mary
University of London. Keir is no longer there and cannot support
these tools which are out-of-date with respect to the current LAMMPS
version (and maybe with respect to AMBER as well). Since we don't use
these tools at Sandia, you'll need to experiment with them and make
necessary modifications yourself.
----------
.. _binary:
binary2txt tool
----------------------------
The file binary2txt.cpp converts one or more binary LAMMPS dump file
into ASCII text files. The syntax for running the tool is
.. parsed-literal::
binary2txt file1 file2 ...
which creates file1.txt, file2.txt, etc. This tool must be compiled
on a platform that can read the binary file created by a LAMMPS run,
since binary files are not compatible across all platforms.
----------
.. _charmm:
ch2lmp tool
------------------------
The ch2lmp sub-directory contains tools for converting files
back-and-forth between the CHARMM MD code and LAMMPS.
They are intended to make it easy to use CHARMM as a builder and as a
post-processor for LAMMPS. Using charmm2lammps.pl, you can convert an
ensemble built in CHARMM into its LAMMPS equivalent. Using
lammps2pdb.pl you can convert LAMMPS atom dumps into pdb files.
See the README file in the ch2lmp sub-directory for more information.
These tools were created by Pieter in't Veld (pjintve at sandia.gov)
and Paul Crozier (pscrozi at sandia.gov) at Sandia.
----------
.. _chain:
chain tool
----------------------
The file chain.f creates a LAMMPS data file containing bead-spring
polymer chains and/or monomer solvent atoms. It uses a text file
containing chain definition parameters as an input. The created
chains and solvent atoms can strongly overlap, so LAMMPS needs to run
the system initially with a "soft" pair potential to un-overlap it.
The syntax for running the tool is
.. parsed-literal::
chain < def.chain > data.file
See the def.chain or def.chain.ab files in the tools directory for
examples of definition files. This tool was used to create the
system for the :doc:`chain benchmark <Section_perf>`.
----------
.. _colvars:
colvars tools
---------------------------
The colvars directory contains a collection of tools for postprocessing
data produced by the colvars collective variable library.
To compile the tools, edit the makefile for your system and run "make".
Please report problems and issues the colvars library and its tools
at: https://github.com/colvars/colvars/issues
abf_integrate:
MC-based integration of multidimensional free energy gradient
Version 20110511
.. parsed-literal::
Syntax: ./abf_integrate < filename > [-n < nsteps >] [-t < temp >] [-m [0|1] (metadynamics)] [-h < hill_height >] [-f < variable_hill_factor >]
The LAMMPS interface to the colvars collective variable library, as
well as these tools, were created by Axel Kohlmeyer (akohlmey at
gmail.com) at ICTP, Italy.
----------
.. _create:
createatoms tool
-----------------------------
The tools/createatoms directory contains a Fortran program called
createAtoms.f which can generate a variety of interesting crystal
structures and geometries and output the resulting list of atom
coordinates in LAMMPS or other formats.
See the included Manual.pdf for details.
The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov.
----------
.. _data:
data2xmovie tool
---------------------------
The file data2xmovie.c converts a LAMMPS data file into a snapshot
suitable for visualizing with the :ref:`xmovie <xmovie>` tool, as if it had
been output with a dump command from LAMMPS itself. The syntax for
running the tool is
.. parsed-literal::
data2xmovie [options] < infile > outfile
See the top of the data2xmovie.c file for a discussion of the options.
----------
.. _eamdb:
eam database tool
-----------------------------
The tools/eam_database directory contains a Fortran program that will
generate EAM alloy setfl potential files for any combination of 16
elements: Cu, Ag, Au, Ni, Pd, Pt, Al, Pb, Fe, Mo, Ta, W, Mg, Co, Ti,
Zr. The files can then be used with the :doc:`pair_style eam/alloy <pair_eam>` command.
The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov,
and is based on his paper:
X. W. Zhou, R. A. Johnson, and H. N. G. Wadley, Phys. Rev. B, 69,
144113 (2004).
----------
.. _eamgn:
eam generate tool
-----------------------------
The tools/eam_generate directory contains several one-file C programs
that convert an analytic formula into a tabulated :doc:`embedded atom method (EAM) <pair_eam>` setfl potential file. The potentials they
produce are in the potentials directory, and can be used with the
:doc:`pair_style eam/alloy <pair_eam>` command.
The source files and potentials were provided by Gerolf Ziegenhain
(gerolf at ziegenhain.com).
----------
.. _eff:
eff tool
------------------
The tools/eff directory contains various scripts for generating
structures and post-processing output for simulations using the
electron force field (eFF).
These tools were provided by Andres Jaramillo-Botero at CalTech
(ajaramil at wag.caltech.edu).
----------
.. _emacs:
emacs tool
----------------------
The tools/emacs directory contains a Lips add-on file for Emacs that
enables a lammps-mode for editing of input scripts when using Emacs,
with various highlighting options setup.
These tools were provided by Aidan Thompson at Sandia
(athomps at sandia.gov).
----------
.. _fep:
fep tool
------------------
The tools/fep directory contains Python scripts useful for
post-processing results from performing free-energy perturbation
simulations using the USER-FEP package.
The scripts were contributed by Agilio Padua (Universite Blaise
Pascal Clermont-Ferrand), agilio.padua at univ-bpclermont.fr.
See README file in the tools/fep directory.
----------
.. _ipi:
i-pi tool
-------------------
The tools/i-pi directory contains a version of the i-PI package, with
all the LAMMPS-unrelated files removed. It is provided so that it can
be used with the :doc:`fix ipi <fix_ipi>` command to perform
path-integral molecular dynamics (PIMD).
The i-PI package was created and is maintained by Michele Ceriotti,
michele.ceriotti at gmail.com, to interface to a variety of molecular
dynamics codes.
See the tools/i-pi/manual.pdf file for an overview of i-PI, and the
:doc:`fix ipi <fix_ipi>` doc page for further details on running PIMD
calculations with LAMMPS.
----------
.. _ipp:
ipp tool
------------------
The tools/ipp directory contains a Perl script ipp which can be used
to facilitate the creation of a complicated file (say, a lammps input
script or tools/createatoms input file) using a template file.
ipp was created and is maintained by Reese Jones (Sandia), rjones at
sandia.gov.
See two examples in the tools/ipp directory. One of them is for the
tools/createatoms tool's input file.
----------
.. _kate:
kate tool
--------------------
The file in the tools/kate directory is an add-on to the Kate editor
in the KDE suite that allow syntax highlighting of LAMMPS input
scripts. See the README.txt file for details.
The file was provided by Alessandro Luigi Sellerio
(alessandro.sellerio at ieni.cnr.it).
----------
.. _arc:
lmp2arc tool
----------------------
The lmp2arc sub-directory contains a tool for converting LAMMPS output
files to the format for Accelrys' Insight MD code (formerly
MSI/Biosym and its Discover MD code). See the README file for more
information.
This tool was written by John Carpenter (Cray), Michael Peachey
(Cray), and Steve Lustig (Dupont). John is now at the Mayo Clinic
(jec at mayo.edu), but still fields questions about the tool.
This tool was updated for the current LAMMPS C++ version by Jeff
Greathouse at Sandia (jagreat at sandia.gov).
----------
.. _cfg:
lmp2cfg tool
----------------------
The lmp2cfg sub-directory contains a tool for converting LAMMPS output
files into a series of *.cfg files which can be read into the
`AtomEye <http://mt.seas.upenn.edu/Archive/Graphics/A>`_ visualizer. See
the README file for more information.
This tool was written by Ara Kooser at Sandia (askoose at sandia.gov).
----------
.. _vmd:
lmp2vmd tool
----------------------
The lmp2vmd sub-directory contains a README.txt file that describes
details of scripts and plugin support within the `VMD package <http://www.ks.uiuc.edu/Research/vmd>`_ for visualizing LAMMPS
dump files.
The VMD plugins and other supporting scripts were written by Axel
Kohlmeyer (akohlmey at cmm.chem.upenn.edu) at U Penn.
----------
.. _matlab:
matlab tool
------------------------
The matlab sub-directory contains several :ref:`MATLAB <matlab>` scripts for
post-processing LAMMPS output. The scripts include readers for log
and dump files, a reader for EAM potential files, and a converter that
reads LAMMPS dump files and produces CFG files that can be visualized
with the `AtomEye <http://mt.seas.upenn.edu/Archive/Graphics/A>`_
visualizer.
See the README.pdf file for more information.
These scripts were written by Arun Subramaniyan at Purdue Univ
(asubrama at purdue.edu).
.. _matlab: http://www.mathworks.com
----------
.. _micelle:
micelle2d tool
----------------------------
The file micelle2d.f creates a LAMMPS data file containing short lipid
chains in a monomer solution. It uses a text file containing lipid
definition parameters as an input. The created molecules and solvent
atoms can strongly overlap, so LAMMPS needs to run the system
initially with a "soft" pair potential to un-overlap it. The syntax
for running the tool is
.. parsed-literal::
micelle2d < def.micelle2d > data.file
See the def.micelle2d file in the tools directory for an example of a
definition file. This tool was used to create the system for the
:doc:`micelle example <Section_example>`.
----------
.. _moltemplate:
moltemplate tool
----------------------------------
The moltemplate sub-directory contains a Python-based tool for
building molecular systems based on a text-file description, and
creating LAMMPS data files that encode their molecular topology as
lists of bonds, angles, dihedrals, etc. See the README.TXT file for
more information.
This tool was written by Andrew Jewett (jewett.aij at gmail.com), who
supports it. It has its own WWW page at
`http://moltemplate.org <http://moltemplate.org>`_.
----------
.. _msi:
msi2lmp tool
----------------------
The msi2lmp sub-directory contains a tool for creating LAMMPS input
data files from Accelrys' Insight MD code (formerly MSI/Biosym and
its Discover MD code). See the README file for more information.
This tool was written by John Carpenter (Cray), Michael Peachey
(Cray), and Steve Lustig (Dupont). John is now at the Mayo Clinic
(jec at mayo.edu), but still fields questions about the tool.
This tool may be out-of-date with respect to the current LAMMPS and
Insight versions. Since we don't use it at Sandia, you'll need to
experiment with it yourself.
----------
.. _phonon:
phonon tool
------------------------
The phonon sub-directory contains a post-processing tool useful for
analyzing the output of the :doc:`fix phonon <fix_phonon>` command in
the USER-PHONON package.
See the README file for instruction on building the tool and what
library it needs. And see the examples/USER/phonon directory
for example problems that can be post-processed with this tool.
This tool was written by Ling-Ti Kong at Shanghai Jiao Tong
University.
----------
.. _polybond:
polymer bonding tool
-----------------------------------
The polybond sub-directory contains a Python-based tool useful for
performing "programmable polymer bonding". The Python file
lmpsdata.py provides a "Lmpsdata" class with various methods which can
be invoked by a user-written Python script to create data files with
complex bonding topologies.
See the Manual.pdf for details and example scripts.
This tool was written by Zachary Kraus at Georgia Tech.
----------
.. _pymol:
pymol_asphere tool
------------------------------
The pymol_asphere sub-directory contains a tool for converting a
LAMMPS dump file that contains orientation info for ellipsoidal
particles into an input file for the :ref:`PyMol visualization package <pymol>`.
.. _pymol: http://pymol.sourceforge.net
Specifically, the tool triangulates the ellipsoids so they can be
viewed as true ellipsoidal particles within PyMol. See the README and
examples directory within pymol_asphere for more information.
This tool was written by Mike Brown at Sandia.
----------
.. _pythontools:
python tool
-----------------------------
The python sub-directory contains several Python scripts
that perform common LAMMPS post-processing tasks, such as:
* extract thermodynamic info from a log file as columns of numbers
* plot two columns of thermodynamic info from a log file using GnuPlot
* sort the snapshots in a dump file by atom ID
* convert multiple :doc:`NEB <neb>` dump files into one dump file for viz
* convert dump files into XYZ, CFG, or PDB format for viz by other packages
These are simple scripts built on `Pizza.py <pizza_>`_ modules. See the
README for more info on Pizza.py and how to use these scripts.
----------
.. _reax:
reax tool
--------------------
The reax sub-directory contains stand-alond codes that can
post-process the output of the :doc:`fix reax/bonds <fix_reax_bonds>`
command from a LAMMPS simulation using :doc:`ReaxFF <pair_reax>`. See
the README.txt file for more info.
These tools were written by Aidan Thompson at Sandia.
----------
.. _restart:
restart2data tool
-------------------------------
.. note::
This tool is now obsolete and is not included in the current
LAMMPS distribution. This is becaues there is now a
:doc:`write_data <write_data>` command, which can create a data file
from within an input script. Running LAMMPS with the "-r"
:ref:`command-line switch <start_7>` as follows:
lmp_g++ -r restartfile datafile
is the same as running a 2-line input script:
read_restart restartfile
write_data datafile
which will produce the same data file that the restart2data tool used
to create. The following information is included in case you have an
older version of LAMMPS which still includes the restart2data tool.
The file restart2data.cpp converts a binary LAMMPS restart file into
an ASCII data file. The syntax for running the tool is
.. parsed-literal::
restart2data restart-file data-file (input-file)
Input-file is optional and if specified will contain LAMMPS input
commands for the masses and force field parameters, instead of putting
those in the data-file. Only a few force field styles currently
support this option.
This tool must be compiled on a platform that can read the binary file
created by a LAMMPS run, since binary files are not compatible across
all platforms.
Note that a text data file has less precision than a binary restart
file. Hence, continuing a run from a converted data file will
typically not conform as closely to a previous run as will restarting
from a binary restart file.
If a "%" appears in the specified restart-file, the tool expects a set
of multiple files to exist. See the :doc:`restart <restart>` and
:doc:`write_restart <write_restart>` commands for info on how such sets
of files are written by LAMMPS, and how the files are named.
----------
.. _vim:
vim tool
------------------
The files in the tools/vim directory are add-ons to the VIM editor
that allow easier editing of LAMMPS input scripts. See the README.txt
file for details.
These files were provided by Gerolf Ziegenhain (gerolf at
ziegenhain.com)
----------
.. _xmgrace:
xmgrace tool
--------------------------
The files in the tools/xmgrace directory can be used to plot the
thermodynamic data in LAMMPS log files via the xmgrace plotting
package. There are several tools in the directory that can be used in
post-processing mode. The lammpsplot.cpp file can be compiled and
used to create plots from the current state of a running LAMMPS
simulation.
See the README file for details.
These files were provided by Vikas Varshney (vv0210 at gmail.com)
----------
.. _xmovie:
xmovie tool
------------------------
The xmovie tool is an X-based visualization package that can read
LAMMPS dump files and animate them. It is in its own sub-directory
with the tools directory. You may need to modify its Makefile so that
it can find the appropriate X libraries to link against.
The syntax for running xmovie is
.. parsed-literal::
xmovie [options] dump.file1 dump.file2 ...
If you just type "xmovie" you will see a list of options. Note that
by default, LAMMPS dump files are in scaled coordinates, so you
typically need to use the -scale option with xmovie. When xmovie runs
it opens a visualization window and a control window. The control
options are straightforward to use.
Xmovie was mostly written by Mike Uttormark (U Wisconsin) while he
spent a summer at Sandia. It displays 2d projections of a 3d domain.
While simple in design, it is an amazingly fast program that can
render large numbers of atoms very quickly. It's a useful tool for
debugging LAMMPS input and output and making sure your simulation is
doing what you think it should. The animations on the Examples page
of the `LAMMPS WWW site <lws_>`_ were created with xmovie.
I've lost contact with Mike, so I hope he's comfortable with us
distributing his great tool!
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

223
doc/_sources/accelerate_cuda.txt Normal file
View File

@ -0,0 +1,223 @@
:doc:`Return to Section accelerate overview <Section_accelerate>`
5.USER-CUDA package
-------------------
The USER-CUDA package was developed by Christian Trott (Sandia) while
at U Technology Ilmenau in Germany. It provides NVIDIA GPU versions
of many pair styles, many fixes, a few computes, and for long-range
Coulombics via the PPPM command. It has the following general
features:
* The package is designed to allow an entire LAMMPS calculation, for
many timesteps, to run entirely on the GPU (except for inter-processor
MPI communication), so that atom-based data (e.g. coordinates, forces)
do not have to move back-and-forth between the CPU and GPU.
* The speed-up advantage of this approach is typically better when the
number of atoms per GPU is large
* Data will stay on the GPU until a timestep where a non-USER-CUDA fix
or compute is invoked. Whenever a non-GPU operation occurs (fix,
compute, output), data automatically moves back to the CPU as needed.
This may incur a performance penalty, but should otherwise work
transparently.
* Neighbor lists are constructed on the GPU.
* The package only supports use of a single MPI task, running on a
single CPU (core), assigned to each GPU.
Here is a quick overview of how to use the USER-CUDA package:
* build the library in lib/cuda for your GPU hardware with desired precision
* include the USER-CUDA package and build LAMMPS
* use the mpirun command to specify 1 MPI task per GPU (on each node)
* enable the USER-CUDA package via the "-c on" command-line switch
* specify the # of GPUs per node
* use USER-CUDA styles in your input script
The latter two steps can be done using the "-pk cuda" and "-sf cuda"
:ref:`command-line switches <start_7>` respectively. Or
the effect of the "-pk" or "-sf" switches can be duplicated by adding
the :doc:`package cuda <package>` or :doc:`suffix cuda <suffix>` commands
respectively to your input script.
**Required hardware/software:**
To use this package, you need to have one or more NVIDIA GPUs and
install the NVIDIA Cuda software on your system:
Your NVIDIA GPU needs to support Compute Capability 1.3. This list may
help you to find out the Compute Capability of your card:
http://en.wikipedia.org/wiki/Comparison_of_Nvidia_graphics_processing_units
Install the Nvidia Cuda Toolkit (version 3.2 or higher) and the
corresponding GPU drivers. The Nvidia Cuda SDK is not required, but
we recommend it also be installed. You can then make sure its sample
projects can be compiled without problems.
**Building LAMMPS with the USER-CUDA package:**
This requires two steps (a,b): build the USER-CUDA library, then build
LAMMPS with the USER-CUDA package.
You can do both these steps in one line, using the src/Make.py script,
described in :ref:`Section 2.4 <start_4>` of the manual.
Type "Make.py -h" for help. If run from the src directory, this
command will create src/lmp_cuda using src/MAKE/Makefile.mpi as the
starting Makefile.machine:
.. parsed-literal::
Make.py -p cuda -cuda mode=single arch=20 -o cuda -a lib-cuda file mpi
Or you can follow these two (a,b) steps:
(a) Build the USER-CUDA library
The USER-CUDA library is in lammps/lib/cuda. If your *CUDA* toolkit
is not installed in the default system directoy */usr/local/cuda* edit
the file *lib/cuda/Makefile.common* accordingly.
To build the library with the settings in lib/cuda/Makefile.default,
simply type:
.. parsed-literal::
make
To set options when the library is built, type "make OPTIONS", where
*OPTIONS* are one or more of the following. The settings will be
written to the *lib/cuda/Makefile.defaults* before the build.
.. parsed-literal::
*precision=N* to set the precision level
N = 1 for single precision (default)
N = 2 for double precision
N = 3 for positions in double precision
N = 4 for positions and velocities in double precision
*arch=M* to set GPU compute capability
M = 35 for Kepler GPUs
M = 20 for CC2.0 (GF100/110, e.g. C2050,GTX580,GTX470) (default)
M = 21 for CC2.1 (GF104/114, e.g. GTX560, GTX460, GTX450)
M = 13 for CC1.3 (GF200, e.g. C1060, GTX285)
*prec_timer=0/1* to use hi-precision timers
0 = do not use them (default)
1 = use them
this is usually only useful for Mac machines
*dbg=0/1* to activate debug mode
0 = no debug mode (default)
1 = yes debug mode
this is only useful for developers
*cufft=1* for use of the CUDA FFT library
0 = no CUFFT support (default)
in the future other CUDA-enabled FFT libraries might be supported
If the build is successful, it will produce the files liblammpscuda.a and
Makefile.lammps.
Note that if you change any of the options (like precision), you need
to re-build the entire library. Do a "make clean" first, followed by
"make".
(b) Build LAMMPS with the USER-CUDA package
.. parsed-literal::
cd lammps/src
make yes-user-cuda
make machine
No additional compile/link flags are needed in Makefile.machine.
Note that if you change the USER-CUDA library precision (discussed
above) and rebuild the USER-CUDA library, then you also need to
re-install the USER-CUDA package and re-build LAMMPS, so that all
affected files are re-compiled and linked to the new USER-CUDA
library.
**Run with the USER-CUDA package from the command line:**
The mpirun or mpiexec command sets the total number of MPI tasks used
by LAMMPS (one or multiple per compute node) and the number of MPI
tasks used per node. E.g. the mpirun command in MPICH does this via
its -np and -ppn switches. Ditto for OpenMPI via -np and -npernode.
When using the USER-CUDA package, you must use exactly one MPI task
per physical GPU.
You must use the "-c on" :ref:`command-line switch <start_7>` to enable the USER-CUDA package.
The "-c on" switch also issues a default :doc:`package cuda 1 <package>`
command which sets various USER-CUDA options to default values, as
discussed on the :doc:`package <package>` command doc page.
Use the "-sf cuda" :ref:`command-line switch <start_7>`,
which will automatically append "cuda" to styles that support it. Use
the "-pk cuda Ng" :ref:`command-line switch <start_7>` to
set Ng = # of GPUs per node to a different value than the default set
by the "-c on" switch (1 GPU) or change other :doc:`package cuda <package>` options.
.. parsed-literal::
lmp_machine -c on -sf cuda -pk cuda 1 -in in.script # 1 MPI task uses 1 GPU
mpirun -np 2 lmp_machine -c on -sf cuda -pk cuda 2 -in in.script # 2 MPI tasks use 2 GPUs on a single 16-core (or whatever) node
mpirun -np 24 -ppn 2 lmp_machine -c on -sf cuda -pk cuda 2 -in in.script # ditto on 12 16-core nodes
The syntax for the "-pk" switch is the same as same as the "package
cuda" command. See the :doc:`package <package>` command doc page for
details, including the default values used for all its options if it
is not specified.
Note that the default for the :doc:`package cuda <package>` command is
to set the Newton flag to "off" for both pairwise and bonded
interactions. This typically gives fastest performance. If the
:doc:`newton <newton>` command is used in the input script, it can
override these defaults.
**Or run with the USER-CUDA package by editing an input script:**
The discussion above for the mpirun/mpiexec command and the requirement
of one MPI task per GPU is the same.
You must still use the "-c on" :ref:`command-line switch <start_7>` to enable the USER-CUDA package.
Use the :doc:`suffix cuda <suffix>` command, or you can explicitly add a
"cuda" suffix to individual styles in your input script, e.g.
.. parsed-literal::
pair_style lj/cut/cuda 2.5
You only need to use the :doc:`package cuda <package>` command if you
wish to change any of its option defaults, including the number of
GPUs/node (default = 1), as set by the "-c on" :ref:`command-line switch <start_7>`.
**Speed-ups to expect:**
The performance of a GPU versus a multi-core CPU is a function of your
hardware, which pair style is used, the number of atoms/GPU, and the
precision used on the GPU (double, single, mixed).
See the `Benchmark page <http://lammps.sandia.gov/bench.html>`_ of the
LAMMPS web site for performance of the USER-CUDA package on different
hardware.
**Guidelines for best performance:**
* The USER-CUDA package offers more speed-up relative to CPU performance
when the number of atoms per GPU is large, e.g. on the order of tens
or hundreds of 1000s.
* As noted above, this package will continue to run a simulation
entirely on the GPU(s) (except for inter-processor MPI communication),
for multiple timesteps, until a CPU calculation is required, either by
a fix or compute that is non-GPU-ized, or until output is performed
(thermo or dump snapshot or restart file). The less often this
occurs, the faster your simulation will run.
Restrictions
""""""""""""
None.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

249
doc/_sources/accelerate_gpu.txt Normal file
View File

@ -0,0 +1,249 @@
:doc:`Return to Section accelerate overview <Section_accelerate>`
5.GPU package
-------------
The GPU package was developed by Mike Brown at ORNL and his
collaborators, particularly Trung Nguyen (ORNL). It provides GPU
versions of many pair styles, including the 3-body Stillinger-Weber
pair style, and for :doc:`kspace_style pppm <kspace_style>` for
long-range Coulombics. It has the following general features:
* It is designed to exploit common GPU hardware configurations where one
or more GPUs are coupled to many cores of one or more multi-core CPUs,
e.g. within a node of a parallel machine.
* Atom-based data (e.g. coordinates, forces) moves back-and-forth
between the CPU(s) and GPU every timestep.
* Neighbor lists can be built on the CPU or on the GPU
* The charge assignement and force interpolation portions of PPPM can be
run on the GPU. The FFT portion, which requires MPI communication
between processors, runs on the CPU.
* Asynchronous force computations can be performed simultaneously on the
CPU(s) and GPU.
* It allows for GPU computations to be performed in single or double
precision, or in mixed-mode precision, where pairwise forces are
computed in single precision, but accumulated into double-precision
force vectors.
* LAMMPS-specific code is in the GPU package. It makes calls to a
generic GPU library in the lib/gpu directory. This library provides
NVIDIA support as well as more general OpenCL support, so that the
same functionality can eventually be supported on a variety of GPU
hardware.
Here is a quick overview of how to use the GPU package:
* build the library in lib/gpu for your GPU hardware wity desired precision
* include the GPU package and build LAMMPS
* use the mpirun command to set the number of MPI tasks/node which determines the number of MPI tasks/GPU
* specify the # of GPUs per node
* use GPU styles in your input script
The latter two steps can be done using the "-pk gpu" and "-sf gpu"
:ref:`command-line switches <start_7>` respectively. Or
the effect of the "-pk" or "-sf" switches can be duplicated by adding
the :doc:`package gpu <package>` or :doc:`suffix gpu <suffix>` commands
respectively to your input script.
**Required hardware/software:**
To use this package, you currently need to have an NVIDIA GPU and
install the NVIDIA Cuda software on your system:
* Check if you have an NVIDIA GPU: cat /proc/driver/nvidia/gpus/0/information
* Go to http://www.nvidia.com/object/cuda_get.html
* Install a driver and toolkit appropriate for your system (SDK is not necessary)
* Run lammps/lib/gpu/nvc_get_devices (after building the GPU library, see below) to list supported devices and properties
**Building LAMMPS with the GPU package:**
This requires two steps (a,b): build the GPU library, then build
LAMMPS with the GPU package.
You can do both these steps in one line, using the src/Make.py script,
described in :ref:`Section 2.4 <start_4>` of the manual.
Type "Make.py -h" for help. If run from the src directory, this
command will create src/lmp_gpu using src/MAKE/Makefile.mpi as the
starting Makefile.machine:
.. parsed-literal::
Make.py -p gpu -gpu mode=single arch=31 -o gpu -a lib-gpu file mpi
Or you can follow these two (a,b) steps:
(a) Build the GPU library
The GPU library is in lammps/lib/gpu. Select a Makefile.machine (in
lib/gpu) appropriate for your system. You should pay special
attention to 3 settings in this makefile.
* CUDA_HOME = needs to be where NVIDIA Cuda software is installed on your system
* CUDA_ARCH = needs to be appropriate to your GPUs
* CUDA_PREC = precision (double, mixed, single) you desire
See lib/gpu/Makefile.linux.double for examples of the ARCH settings
for different GPU choices, e.g. Fermi vs Kepler. It also lists the
possible precision settings:
.. parsed-literal::
CUDA_PREC = -D_SINGLE_SINGLE # single precision for all calculations
CUDA_PREC = -D_DOUBLE_DOUBLE # double precision for all calculations
CUDA_PREC = -D_SINGLE_DOUBLE # accumulation of forces, etc, in double
The last setting is the mixed mode referred to above. Note that your
GPU must support double precision to use either the 2nd or 3rd of
these settings.
To build the library, type:
.. parsed-literal::
make -f Makefile.machine
If successful, it will produce the files libgpu.a and Makefile.lammps.
The latter file has 3 settings that need to be appropriate for the
paths and settings for the CUDA system software on your machine.
Makefile.lammps is a copy of the file specified by the EXTRAMAKE
setting in Makefile.machine. You can change EXTRAMAKE or create your
own Makefile.lammps.machine if needed.
Note that to change the precision of the GPU library, you need to
re-build the entire library. Do a "clean" first, e.g. "make -f
Makefile.linux clean", followed by the make command above.
(b) Build LAMMPS with the GPU package
.. parsed-literal::
cd lammps/src
make yes-gpu
make machine
No additional compile/link flags are needed in Makefile.machine.
Note that if you change the GPU library precision (discussed above)
and rebuild the GPU library, then you also need to re-install the GPU
package and re-build LAMMPS, so that all affected files are
re-compiled and linked to the new GPU library.
**Run with the GPU package from the command line:**
The mpirun or mpiexec command sets the total number of MPI tasks used
by LAMMPS (one or multiple per compute node) and the number of MPI
tasks used per node. E.g. the mpirun command in MPICH does this via
its -np and -ppn switches. Ditto for OpenMPI via -np and -npernode.
When using the GPU package, you cannot assign more than one GPU to a
single MPI task. However multiple MPI tasks can share the same GPU,
and in many cases it will be more efficient to run this way. Likewise
it may be more efficient to use less MPI tasks/node than the available
# of CPU cores. Assignment of multiple MPI tasks to a GPU will happen
automatically if you create more MPI tasks/node than there are
GPUs/mode. E.g. with 8 MPI tasks/node and 2 GPUs, each GPU will be
shared by 4 MPI tasks.
Use the "-sf gpu" :ref:`command-line switch <start_7>`,
which will automatically append "gpu" to styles that support it. Use
the "-pk gpu Ng" :ref:`command-line switch <start_7>` to
set Ng = # of GPUs/node to use.
.. parsed-literal::
lmp_machine -sf gpu -pk gpu 1 -in in.script # 1 MPI task uses 1 GPU
mpirun -np 12 lmp_machine -sf gpu -pk gpu 2 -in in.script # 12 MPI tasks share 2 GPUs on a single 16-core (or whatever) node
mpirun -np 48 -ppn 12 lmp_machine -sf gpu -pk gpu 2 -in in.script # ditto on 4 16-core nodes
Note that if the "-sf gpu" switch is used, it also issues a default
:doc:`package gpu 1 <package>` command, which sets the number of
GPUs/node to 1.
Using the "-pk" switch explicitly allows for setting of the number of
GPUs/node to use and additional options. Its syntax is the same as
same as the "package gpu" command. See the :doc:`package <package>`
command doc page for details, including the default values used for
all its options if it is not specified.
Note that the default for the :doc:`package gpu <package>` command is to
set the Newton flag to "off" pairwise interactions. It does not
affect the setting for bonded interactions (LAMMPS default is "on").
The "off" setting for pairwise interaction is currently required for
GPU package pair styles.
**Or run with the GPU package by editing an input script:**
The discussion above for the mpirun/mpiexec command, MPI tasks/node,
and use of multiple MPI tasks/GPU is the same.
Use the :doc:`suffix gpu <suffix>` command, or you can explicitly add an
"gpu" suffix to individual styles in your input script, e.g.
.. parsed-literal::
pair_style lj/cut/gpu 2.5
You must also use the :doc:`package gpu <package>` command to enable the
GPU package, unless the "-sf gpu" or "-pk gpu" :ref:`command-line switches <start_7>` were used. It specifies the
number of GPUs/node to use, as well as other options.
**Speed-ups to expect:**
The performance of a GPU versus a multi-core CPU is a function of your
hardware, which pair style is used, the number of atoms/GPU, and the
precision used on the GPU (double, single, mixed).
See the `Benchmark page <http://lammps.sandia.gov/bench.html>`_ of the
LAMMPS web site for performance of the GPU package on various
hardware, including the Titan HPC platform at ORNL.
You should also experiment with how many MPI tasks per GPU to use to
give the best performance for your problem and machine. This is also
a function of the problem size and the pair style being using.
Likewise, you should experiment with the precision setting for the GPU
library to see if single or mixed precision will give accurate
results, since they will typically be faster.
**Guidelines for best performance:**
* Using multiple MPI tasks per GPU will often give the best performance,
as allowed my most multi-core CPU/GPU configurations.
* If the number of particles per MPI task is small (e.g. 100s of
particles), it can be more efficient to run with fewer MPI tasks per
GPU, even if you do not use all the cores on the compute node.
* The :doc:`package gpu <package>` command has several options for tuning
performance. Neighbor lists can be built on the GPU or CPU. Force
calculations can be dynamically balanced across the CPU cores and
GPUs. GPU-specific settings can be made which can be optimized
for different hardware. See the :doc:`packakge <package>` command
doc page for details.
* As described by the :doc:`package gpu <package>` command, GPU
accelerated pair styles can perform computations asynchronously with
CPU computations. The "Pair" time reported by LAMMPS will be the
maximum of the time required to complete the CPU pair style
computations and the time required to complete the GPU pair style
computations. Any time spent for GPU-enabled pair styles for
computations that run simultaneously with :doc:`bond <bond_style>`,
:doc:`angle <angle_style>`, :doc:`dihedral <dihedral_style>`,
:doc:`improper <improper_style>`, and :doc:`long-range <kspace_style>`
calculations will not be included in the "Pair" time.
* When the *mode* setting for the package gpu command is force/neigh,
the time for neighbor list calculations on the GPU will be added into
the "Pair" time, not the "Neigh" time. An additional breakdown of the
times required for various tasks on the GPU (data copy, neighbor
calculations, force computations, etc) are output only with the LAMMPS
screen output (not in the log file) at the end of each run. These
timings represent total time spent on the GPU for each routine,
regardless of asynchronous CPU calculations.
* The output section "GPU Time Info (average)" reports "Max Mem / Proc".
This is the maximum memory used at one time on the GPU for data
storage by a single MPI process.
Restrictions
""""""""""""
None.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

317
doc/_sources/accelerate_intel.txt Normal file
View File

@ -0,0 +1,317 @@
:doc:`Return to Section accelerate overview <Section_accelerate>`
5.USER-INTEL package
--------------------
The USER-INTEL package was developed by Mike Brown at Intel
Corporation. It provides two methods for accelerating simulations,
depending on the hardware you have. The first is acceleration on
Intel(R) CPUs by running in single, mixed, or double precision with
vectorization. The second is acceleration on Intel(R) Xeon Phi(TM)
coprocessors via offloading neighbor list and non-bonded force
calculations to the Phi. The same C++ code is used in both cases.
When offloading to a coprocessor from a CPU, the same routine is run
twice, once on the CPU and once with an offload flag.
Note that the USER-INTEL package supports use of the Phi in "offload"
mode, not "native" mode like the :doc:`KOKKOS package <accelerate_kokkos>`.
Also note that the USER-INTEL package can be used in tandem with the
:doc:`USER-OMP package <accelerate_omp>`. This is useful when
offloading pair style computations to the Phi, so that other styles
not supported by the USER-INTEL package, e.g. bond, angle, dihedral,
improper, and long-range electrostatics, can run simultaneously in
threaded mode on the CPU cores. Since less MPI tasks than CPU cores
will typically be invoked when running with coprocessors, this enables
the extra CPU cores to be used for useful computation.
As illustrated below, if LAMMPS is built with both the USER-INTEL and
USER-OMP packages, this dual mode of operation is made easier to use,
via the "-suffix hybrid intel omp" :ref:`command-line switch <start_7>` or the :doc:`suffix hybrid intel omp <suffix>` command. Both set a second-choice suffix to "omp" so
that styles from the USER-INTEL package will be used if available,
with styles from the USER-OMP package as a second choice.
Here is a quick overview of how to use the USER-INTEL package for CPU
acceleration, assuming one or more 16-core nodes. More details
follow.
.. parsed-literal::
use an Intel compiler
use these CCFLAGS settings in Makefile.machine: -fopenmp, -DLAMMPS_MEMALIGN=64, -restrict, -xHost, -fno-alias, -ansi-alias, -override-limits
use these LINKFLAGS settings in Makefile.machine: -fopenmp, -xHost
make yes-user-intel yes-user-omp # including user-omp is optional
make mpi # build with the USER-INTEL package, if settings (including compiler) added to Makefile.mpi
make intel_cpu # or Makefile.intel_cpu already has settings, uses Intel MPI wrapper
Make.py -v -p intel omp -intel cpu -a file mpich_icc # or one-line build via Make.py for MPICH
Make.py -v -p intel omp -intel cpu -a file ompi_icc # or for OpenMPI
Make.py -v -p intel omp -intel cpu -a file intel_cpu # or for Intel MPI wrapper
.. parsed-literal::
lmp_machine -sf intel -pk intel 0 omp 16 -in in.script # 1 node, 1 MPI task/node, 16 threads/task, no USER-OMP
mpirun -np 32 lmp_machine -sf intel -in in.script # 2 nodess, 16 MPI tasks/node, no threads, no USER-OMP
lmp_machine -sf hybrid intel omp -pk intel 0 omp 16 -pk omp 16 -in in.script # 1 node, 1 MPI task/node, 16 threads/task, with USER-OMP
mpirun -np 32 -ppn 4 lmp_machine -sf hybrid intel omp -pk omp 4 -pk omp 4 -in in.script # 8 nodes, 4 MPI tasks/node, 4 threads/task, with USER-OMP
Here is a quick overview of how to use the USER-INTEL package for the
same CPUs as above (16 cores/node), with an additional Xeon Phi(TM)
coprocessor per node. More details follow.
.. parsed-literal::
Same as above for building, with these additions/changes:
add the flag -DLMP_INTEL_OFFLOAD to CCFLAGS in Makefile.machine
add the flag -offload to LINKFLAGS in Makefile.machine
for Make.py change "-intel cpu" to "-intel phi", and "file intel_cpu" to "file intel_phi"
.. parsed-literal::
mpirun -np 32 lmp_machine -sf intel -pk intel 1 -in in.script # 2 nodes, 16 MPI tasks/node, 240 total threads on coprocessor, no USER-OMP
mpirun -np 16 -ppn 8 lmp_machine -sf intel -pk intel 1 omp 2 -in in.script # 2 nodes, 8 MPI tasks/node, 2 threads/task, 240 total threads on coprocessor, no USER-OMP
mpirun -np 32 -ppn 8 lmp_machine -sf hybrid intel omp -pk intel 1 omp 2 -pk omp 2 -in in.script # 4 nodes, 8 MPI tasks/node, 2 threads/task, 240 total threads on coprocessor, with USER-OMP
**Required hardware/software:**
Your compiler must support the OpenMP interface. Use of an Intel(R)
C++ compiler is recommended, but not required. However, g++ will not
recognize some of the settings listed above, so they cannot be used.
Optimizations for vectorization have only been tested with the
Intel(R) compiler. Use of other compilers may not result in
vectorization, or give poor performance.
The recommended version of the Intel(R) compiler is 14.0.1.106.
Versions 15.0.1.133 and later are also supported. If using Intel(R)
MPI, versions 15.0.2.044 and later are recommended.
To use the offload option, you must have one or more Intel(R) Xeon
Phi(TM) coprocessors and use an Intel(R) C++ compiler.
**Building LAMMPS with the USER-INTEL package:**
The lines above illustrate how to include/build with the USER-INTEL
package, for either CPU or Phi support, in two steps, using the "make"
command. Or how to do it with one command via the src/Make.py script,
described in :ref:`Section 2.4 <start_4>` of the manual.
Type "Make.py -h" for help. Because the mechanism for specifing what
compiler to use (Intel in this case) is different for different MPI
wrappers, 3 versions of the Make.py command are shown.
Note that if you build with support for a Phi coprocessor, the same
binary can be used on nodes with or without coprocessors installed.
However, if you do not have coprocessors on your system, building
without offload support will produce a smaller binary.
If you also build with the USER-OMP package, you can use styles from
both packages, as described below.
Note that the CCFLAGS and LINKFLAGS settings in Makefile.machine must
include "-fopenmp". Likewise, if you use an Intel compiler, the
CCFLAGS setting must include "-restrict". For Phi support, the
"-DLMP_INTEL_OFFLOAD" (CCFLAGS) and "-offload" (LINKFLAGS) settings
are required. The other settings listed above are optional, but will
typically improve performance. The Make.py command will add all of
these automatically.
If you are compiling on the same architecture that will be used for
the runs, adding the flag *-xHost* to CCFLAGS enables vectorization
with the Intel(R) compiler. Otherwise, you must provide the correct
compute node architecture to the -x option (e.g. -xAVX).
Example machines makefiles Makefile.intel_cpu and Makefile.intel_phi
are included in the src/MAKE/OPTIONS directory with settings that
perform well with the Intel(R) compiler. The latter has support for
offload to Phi coprocessors; the former does not.
**Run with the USER-INTEL package from the command line:**
The mpirun or mpiexec command sets the total number of MPI tasks used
by LAMMPS (one or multiple per compute node) and the number of MPI
tasks used per node. E.g. the mpirun command in MPICH does this via
its -np and -ppn switches. Ditto for OpenMPI via -np and -npernode.
If you compute (any portion of) pairwise interactions using USER-INTEL
pair styles on the CPU, or use USER-OMP styles on the CPU, you need to
choose how many OpenMP threads per MPI task to use. If both packages
are used, it must be done for both packages, and the same thread count
value should be used for both. Note that the product of MPI tasks *
threads/task should not exceed the physical number of cores (on a
node), otherwise performance will suffer.
When using the USER-INTEL package for the Phi, you also need to
specify the number of coprocessor/node and optionally the number of
coprocessor threads per MPI task to use. Note that coprocessor
threads (which run on the coprocessor) are totally independent from
OpenMP threads (which run on the CPU). The default values for the
settings that affect coprocessor threads are typically fine, as
discussed below.
As in the lines above, use the "-sf intel" or "-sf hybrid intel omp"
:ref:`command-line switch <start_7>`, which will
automatically append "intel" to styles that support it. In the second
case, "omp" will be appended if an "intel" style does not exist.
Note that if either switch is used, it also invokes a default command:
:doc:`package intel 1 <package>`. If the "-sf hybrid intel omp" switch
is used, the default USER-OMP command :doc:`package omp 0 <package>` is
also invoked (if LAMMPS was built with USER-OMP). Both set the number
of OpenMP threads per MPI task via the OMP_NUM_THREADS environment
variable. The first command sets the number of Xeon Phi(TM)
coprocessors/node to 1 (ignored if USER-INTEL is built for CPU-only),
and the precision mode to "mixed" (default value).
You can also use the "-pk intel Nphi" :ref:`command-line switch <start_7>` to explicitly set Nphi = # of Xeon
Phi(TM) coprocessors/node, as well as additional options. Nphi should
be >= 1 if LAMMPS was built with coprocessor support, otherswise Nphi
= 0 for a CPU-only build. All the available coprocessor threads on
each Phi will be divided among MPI tasks, unless the *tptask* option
of the "-pk intel" :ref:`command-line switch <start_7>` is
used to limit the coprocessor threads per MPI task. See the :doc:`package intel <package>` command for details, including the default values
used for all its options if not specified, and how to set the number
of OpenMP threads via the OMP_NUM_THREADS environment variable if
desired.
If LAMMPS was built with the USER-OMP package, you can also use the
"-pk omp Nt" :ref:`command-line switch <start_7>` to
explicitly set Nt = # of OpenMP threads per MPI task to use, as well
as additional options. Nt should be the same threads per MPI task as
set for the USER-INTEL package, e.g. via the "-pk intel Nphi omp Nt"
command. Again, see the :doc:`package omp <package>` command for
details, including the default values used for all its options if not
specified, and how to set the number of OpenMP threads via the
OMP_NUM_THREADS environment variable if desired.
**Or run with the USER-INTEL package by editing an input script:**
The discussion above for the mpirun/mpiexec command, MPI tasks/node,
OpenMP threads per MPI task, and coprocessor threads per MPI task is
the same.
Use the :doc:`suffix intel <suffix>` or :doc:`suffix hybrid intel omp <suffix>` commands, or you can explicitly add an "intel" or
"omp" suffix to individual styles in your input script, e.g.
.. parsed-literal::
pair_style lj/cut/intel 2.5
You must also use the :doc:`package intel <package>` command, unless the
"-sf intel" or "-pk intel" :ref:`command-line switches <start_7>` were used. It specifies how many
coprocessors/node to use, as well as other OpenMP threading and
coprocessor options. The :doc:`package <package>` doc page explains how
to set the number of OpenMP threads via an environment variable if
desired.
If LAMMPS was also built with the USER-OMP package, you must also use
the :doc:`package omp <package>` command to enable that package, unless
the "-sf hybrid intel omp" or "-pk omp" :ref:`command-line switches <start_7>` were used. It specifies how many
OpenMP threads per MPI task to use (should be same as the setting for
the USER-INTEL package), as well as other options. Its doc page
explains how to set the number of OpenMP threads via an environment
variable if desired.
**Speed-ups to expect:**
If LAMMPS was not built with coprocessor support (CPU only) when
including the USER-INTEL package, then acclerated styles will run on
the CPU using vectorization optimizations and the specified precision.
This may give a substantial speed-up for a pair style, particularly if
mixed or single precision is used.
If LAMMPS was built with coproccesor support, the pair styles will run
on one or more Intel(R) Xeon Phi(TM) coprocessors (per node). The
performance of a Xeon Phi versus a multi-core CPU is a function of
your hardware, which pair style is used, the number of
atoms/coprocessor, and the precision used on the coprocessor (double,
single, mixed).
See the `Benchmark page <http://lammps.sandia.gov/bench.html>`_ of the
LAMMPS web site for performance of the USER-INTEL package on different
hardware.
.. note::
Setting core affinity is often used to pin MPI tasks and OpenMP
threads to a core or group of cores so that memory access can be
uniform. Unless disabled at build time, affinity for MPI tasks and
OpenMP threads on the host (CPU) will be set by default on the host
when using offload to a coprocessor. In this case, it is unnecessary
to use other methods to control affinity (e.g. taskset, numactl,
I_MPI_PIN_DOMAIN, etc.). This can be disabled in an input script with
the *no_affinity* option to the :doc:`package intel <package>` command
or by disabling the option at build time (by adding
-DINTEL_OFFLOAD_NOAFFINITY to the CCFLAGS line of your Makefile).
Disabling this option is not recommended, especially when running on a
machine with hyperthreading disabled.
**Guidelines for best performance on an Intel(R) Xeon Phi(TM)
coprocessor:**
* The default for the :doc:`package intel <package>` command is to have
all the MPI tasks on a given compute node use a single Xeon Phi(TM)
coprocessor. In general, running with a large number of MPI tasks on
each node will perform best with offload. Each MPI task will
automatically get affinity to a subset of the hardware threads
available on the coprocessor. For example, if your card has 61 cores,
with 60 cores available for offload and 4 hardware threads per core
(240 total threads), running with 24 MPI tasks per node will cause
each MPI task to use a subset of 10 threads on the coprocessor. Fine
tuning of the number of threads to use per MPI task or the number of
threads to use per core can be accomplished with keyword settings of
the :doc:`package intel <package>` command.
* If desired, only a fraction of the pair style computation can be
offloaded to the coprocessors. This is accomplished by using the
*balance* keyword in the :doc:`package intel <package>` command. A
balance of 0 runs all calculations on the CPU. A balance of 1 runs
all calculations on the coprocessor. A balance of 0.5 runs half of
the calculations on the coprocessor. Setting the balance to -1 (the
default) will enable dynamic load balancing that continously adjusts
the fraction of offloaded work throughout the simulation. This option
typically produces results within 5 to 10 percent of the optimal fixed
balance.
* When using offload with CPU hyperthreading disabled, it may help
performance to use fewer MPI tasks and OpenMP threads than available
cores. This is due to the fact that additional threads are generated
internally to handle the asynchronous offload tasks.
* If running short benchmark runs with dynamic load balancing, adding a
short warm-up run (10-20 steps) will allow the load-balancer to find a
near-optimal setting that will carry over to additional runs.
* If pair computations are being offloaded to an Intel(R) Xeon Phi(TM)
coprocessor, a diagnostic line is printed to the screen (not to the
log file), during the setup phase of a run, indicating that offload
mode is being used and indicating the number of coprocessor threads
per MPI task. Additionally, an offload timing summary is printed at
the end of each run. When offloading, the frequency for :doc:`atom sorting <atom_modify>` is changed to 1 so that the per-atom data is
effectively sorted at every rebuild of the neighbor lists.
* For simulations with long-range electrostatics or bond, angle,
dihedral, improper calculations, computation and data transfer to the
coprocessor will run concurrently with computations and MPI
communications for these calculations on the host CPU. The USER-INTEL
package has two modes for deciding which atoms will be handled by the
coprocessor. This choice is controlled with the *ghost* keyword of
the :doc:`package intel <package>` command. When set to 0, ghost atoms
(atoms at the borders between MPI tasks) are not offloaded to the
card. This allows for overlap of MPI communication of forces with
computation on the coprocessor when the :doc:`newton <newton>` setting
is "on". The default is dependent on the style being used, however,
better performance may be achieved by setting this option
explictly.
Restrictions
""""""""""""
When offloading to a coprocessor, :doc:`hybrid <pair_hybrid>` styles
that require skip lists for neighbor builds cannot be offloaded.
Using :doc:`hybrid/overlay <pair_hybrid>` is allowed. Only one intel
accelerated style may be used with hybrid styles.
:doc:`Special_bonds <special_bonds>` exclusion lists are not currently
supported with offload, however, the same effect can often be
accomplished by setting cutoffs for excluded atom types to 0. None of
the pair styles in the USER-INTEL package currently support the
"inner", "middle", "outer" options for rRESPA integration via the
:doc:`run_style respa <run_style>` command; only the "pair" option is
supported.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

527
doc/_sources/accelerate_kokkos.txt Normal file
View File

@ -0,0 +1,527 @@
:doc:`Return to Section accelerate overview <Section_accelerate>`
5.KOKKOS package
----------------
The KOKKOS package was developed primarily by Christian Trott (Sandia)
with contributions of various styles by others, including Sikandar
Mashayak (UIUC), Stan Moore (Sandia), and Ray Shan (Sandia). The
underlying Kokkos library was written primarily by Carter Edwards,
Christian Trott, and Dan Sunderland (all Sandia).
The KOKKOS package contains versions of pair, fix, and atom styles
that use data structures and macros provided by the Kokkos library,
which is included with LAMMPS in lib/kokkos.
The Kokkos library is part of
`Trilinos <http://trilinos.sandia.gov/packages/kokkos>`_ and can also be
downloaded from `Github <https://github.com/kokkos/kokkos>`_. Kokkos is a
templated C++ library that provides two key abstractions for an
application like LAMMPS. First, it allows a single implementation of
an application kernel (e.g. a pair style) to run efficiently on
different kinds of hardware, such as a GPU, Intel Phi, or many-core
CPU.
The Kokkos library also provides data abstractions to adjust (at
compile time) the memory layout of basic data structures like 2d and
3d arrays and allow the transparent utilization of special hardware
load and store operations. Such data structures are used in LAMMPS to
store atom coordinates or forces or neighbor lists. The layout is
chosen to optimize performance on different platforms. Again this
functionality is hidden from the developer, and does not affect how
the kernel is coded.
These abstractions are set at build time, when LAMMPS is compiled with
the KOKKOS package installed. All Kokkos operations occur within the
context of an individual MPI task running on a single node of the
machine. The total number of MPI tasks used by LAMMPS (one or
multiple per compute node) is set in the usual manner via the mpirun
or mpiexec commands, and is independent of Kokkos.
Kokkos currently provides support for 3 modes of execution (per MPI
task). These are OpenMP (for many-core CPUs), Cuda (for NVIDIA GPUs),
and OpenMP (for Intel Phi). Note that the KOKKOS package supports
running on the Phi in native mode, not offload mode like the
USER-INTEL package supports. You choose the mode at build time to
produce an executable compatible with specific hardware.
Here is a quick overview of how to use the KOKKOS package
for CPU acceleration, assuming one or more 16-core nodes.
More details follow.
use a C++11 compatible compiler
make yes-kokkos
make mpi KOKKOS_DEVICES=OpenMP # build with the KOKKOS package
make kokkos_omp # or Makefile.kokkos_omp already has variable set
Make.py -v -p kokkos -kokkos omp -o mpi -a file mpi # or one-line build via Make.py
.. parsed-literal::
mpirun -np 16 lmp_mpi -k on -sf kk -in in.lj # 1 node, 16 MPI tasks/node, no threads
mpirun -np 2 -ppn 1 lmp_mpi -k on t 16 -sf kk -in in.lj # 2 nodes, 1 MPI task/node, 16 threads/task
mpirun -np 2 lmp_mpi -k on t 8 -sf kk -in in.lj # 1 node, 2 MPI tasks/node, 8 threads/task
mpirun -np 32 -ppn 4 lmp_mpi -k on t 4 -sf kk -in in.lj # 8 nodes, 4 MPI tasks/node, 4 threads/task
* specify variables and settings in your Makefile.machine that enable OpenMP, GPU, or Phi support
* include the KOKKOS package and build LAMMPS
* enable the KOKKOS package and its hardware options via the "-k on" command-line switch use KOKKOS styles in your input script
Here is a quick overview of how to use the KOKKOS package for GPUs,
assuming one or more nodes, each with 16 cores and a GPU. More
details follow.
discuss use of NVCC, which Makefiles to examine
use a C++11 compatible compiler
KOKKOS_DEVICES = Cuda, OpenMP
KOKKOS_ARCH = Kepler35
make yes-kokkos
make machine
Make.py -p kokkos -kokkos cuda arch=31 -o kokkos_cuda -a file kokkos_cuda
.. parsed-literal::
mpirun -np 1 lmp_cuda -k on t 6 -sf kk -in in.lj # one MPI task, 6 threads on CPU
mpirun -np 4 -ppn 1 lmp_cuda -k on t 6 -sf kk -in in.lj # ditto on 4 nodes
.. parsed-literal::
mpirun -np 2 lmp_cuda -k on t 8 g 2 -sf kk -in in.lj # two MPI tasks, 8 threads per CPU
mpirun -np 32 -ppn 2 lmp_cuda -k on t 8 g 2 -sf kk -in in.lj # ditto on 16 nodes
Here is a quick overview of how to use the KOKKOS package
for the Intel Phi:
.. parsed-literal::
use a C++11 compatible compiler
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = KNC
make yes-kokkos
make machine
Make.py -p kokkos -kokkos phi -o kokkos_phi -a file mpi
host=MIC, Intel Phi with 61 cores (240 threads/phi via 4x hardware threading):
mpirun -np 1 lmp_g++ -k on t 240 -sf kk -in in.lj # 1 MPI task on 1 Phi, 1*240 = 240
mpirun -np 30 lmp_g++ -k on t 8 -sf kk -in in.lj # 30 MPI tasks on 1 Phi, 30*8 = 240
mpirun -np 12 lmp_g++ -k on t 20 -sf kk -in in.lj # 12 MPI tasks on 1 Phi, 12*20 = 240
mpirun -np 96 -ppn 12 lmp_g++ -k on t 20 -sf kk -in in.lj # ditto on 8 Phis
**Required hardware/software:**
Kokkos support within LAMMPS must be built with a C++11 compatible
compiler. If using gcc, version 4.8.1 or later is required.
To build with Kokkos support for CPUs, your compiler must support the
OpenMP interface. You should have one or more multi-core CPUs so that
multiple threads can be launched by each MPI task running on a CPU.
To build with Kokkos support for NVIDIA GPUs, NVIDIA Cuda software
version 6.5 or later must be installed on your system. See the
discussion for the :doc:`USER-CUDA <accelerate_cuda>` and
:doc:`GPU <accelerate_gpu>` packages for details of how to check and do
this.
.. note::
For good performance of the KOKKOS package on GPUs, you must
have Kepler generation GPUs (or later). The Kokkos library exploits
texture cache options not supported by Telsa generation GPUs (or
older).
To build with Kokkos support for Intel Xeon Phi coprocessors, your
sysmte must be configured to use them in "native" mode, not "offload"
mode like the USER-INTEL package supports.
**Building LAMMPS with the KOKKOS package:**
You must choose at build time whether to build for CPUs (OpenMP),
GPUs, or Phi.
You can do any of these in one line, using the src/Make.py script,
described in :ref:`Section 2.4 <start_4>` of the manual.
Type "Make.py -h" for help. If run from the src directory, these
commands will create src/lmp_kokkos_omp, lmp_kokkos_cuda, and
lmp_kokkos_phi. Note that the OMP and PHI options use
src/MAKE/Makefile.mpi as the starting Makefile.machine. The CUDA
option uses src/MAKE/OPTIONS/Makefile.kokkos_cuda.
The latter two steps can be done using the "-k on", "-pk kokkos" and
"-sf kk" :ref:`command-line switches <start_7>`
respectively. Or the effect of the "-pk" or "-sf" switches can be
duplicated by adding the :doc:`package kokkos <package>` or :doc:`suffix kk <suffix>` commands respectively to your input script.
Or you can follow these steps:
CPU-only (run all-MPI or with OpenMP threading):
.. parsed-literal::
cd lammps/src
make yes-kokkos
make g++ KOKKOS_DEVICES=OpenMP
Intel Xeon Phi:
.. parsed-literal::
cd lammps/src
make yes-kokkos
make g++ KOKKOS_DEVICES=OpenMP KOKKOS_ARCH=KNC
CPUs and GPUs:
.. parsed-literal::
cd lammps/src
make yes-kokkos
make cuda KOKKOS_DEVICES=Cuda
These examples set the KOKKOS-specific OMP, MIC, CUDA variables on the
make command line which requires a GNU-compatible make command. Try
"gmake" if your system's standard make complains.
.. note::
If you build using make line variables and re-build LAMMPS twice
with different KOKKOS options and the *same* target, e.g. g++ in the
first two examples above, then you *must* perform a "make clean-all"
or "make clean-machine" before each build. This is to force all the
KOKKOS-dependent files to be re-compiled with the new options.
You can also hardwire these make variables in the specified machine
makefile, e.g. src/MAKE/Makefile.g++ in the first two examples above,
with a line like:
.. parsed-literal::
KOKKOS_ARCH = KNC
Note that if you build LAMMPS multiple times in this manner, using
different KOKKOS options (defined in different machine makefiles), you
do not have to worry about doing a "clean" in between. This is
because the targets will be different.
.. note::
The 3rd example above for a GPU, uses a different machine
makefile, in this case src/MAKE/Makefile.cuda, which is included in
the LAMMPS distribution. To build the KOKKOS package for a GPU, this
makefile must use the NVIDA "nvcc" compiler. And it must have a
KOKKOS_ARCH setting that is appropriate for your NVIDIA hardware and
installed software. Typical values for KOKKOS_ARCH are given below,
as well as other settings that must be included in the machine
makefile, if you create your own.
.. note::
Currently, there are no precision options with the KOKKOS
package. All compilation and computation is performed in double
precision.
There are other allowed options when building with the KOKKOS package.
As above, they can be set either as variables on the make command line
or in Makefile.machine. This is the full list of options, including
those discussed above, Each takes a value shown below. The
default value is listed, which is set in the
lib/kokkos/Makefile.kokkos file.
#Default settings specific options
#Options: force_uvm,use_ldg,rdc
* KOKKOS_DEVICES, values = *OpenMP*, *Serial*, *Pthreads*, *Cuda*, default = *OpenMP*
* KOKKOS_ARCH, values = *KNC*, *SNB*, *HSW*, *Kepler*, *Kepler30*, *Kepler32*, *Kepler35*, *Kepler37*, *Maxwell*, *Maxwell50*, *Maxwell52*, *Maxwell53*, *ARMv8*, *BGQ*, *Power7*, *Power8*, default = *none*
* KOKKOS_DEBUG, values = *yes*, *no*, default = *no*
* KOKKOS_USE_TPLS, values = *hwloc*, *librt*, default = *none*
* KOKKOS_CUDA_OPTIONS, values = *force_uvm*, *use_ldg*, *rdc*
KOKKOS_DEVICE sets the parallelization method used for Kokkos code
(within LAMMPS). KOKKOS_DEVICES=OpenMP means that OpenMP will be
used. KOKKOS_DEVICES=Pthreads means that pthreads will be used.
KOKKOS_DEVICES=Cuda means an NVIDIA GPU running CUDA will be used.
If KOKKOS_DEVICES=Cuda, then the lo-level Makefile in the src/MAKE
directory must use "nvcc" as its compiler, via its CC setting. For
best performance its CCFLAGS setting should use -O3 and have a
KOKKOS_ARCH setting that matches the compute capability of your NVIDIA
hardware and software installation, e.g. KOKKOS_ARCH=Kepler30. Note
the minimal required compute capability is 2.0, but this will give
signicantly reduced performance compared to Kepler generation GPUs
with compute capability 3.x. For the LINK setting, "nvcc" should not
be used; instead use g++ or another compiler suitable for linking C++
applications. Often you will want to use your MPI compiler wrapper
for this setting (i.e. mpicxx). Finally, the lo-level Makefile must
also have a "Compilation rule" for creating *.o files from *.cu files.
See src/Makefile.cuda for an example of a lo-level Makefile with all
of these settings.
KOKKOS_USE_TPLS=hwloc binds threads to hardware cores, so they do not
migrate during a simulation. KOKKOS_USE_TPLS=hwloc should always be
used if running with KOKKOS_DEVICES=Pthreads for pthreads. It is not
necessary for KOKKOS_DEVICES=OpenMP for OpenMP, because OpenMP
provides alternative methods via environment variables for binding
threads to hardware cores. More info on binding threads to cores is
given in :ref:`this section <acc_8>`.
KOKKOS_ARCH=KNC enables compiler switches needed when compling for an
Intel Phi processor.
KOKKOS_USE_TPLS=librt enables use of a more accurate timer mechanism
on most Unix platforms. This library is not available on all
platforms.
KOKKOS_DEBUG is only useful when developing a Kokkos-enabled style
within LAMMPS. KOKKOS_DEBUG=yes enables printing of run-time
debugging information that can be useful. It also enables runtime
bounds checking on Kokkos data structures.
KOKKOS_CUDA_OPTIONS are additional options for CUDA.
For more information on Kokkos see the Kokkos programmers' guide here:
/lib/kokkos/doc/Kokkos_PG.pdf.
**Run with the KOKKOS package from the command line:**
The mpirun or mpiexec command sets the total number of MPI tasks used
by LAMMPS (one or multiple per compute node) and the number of MPI
tasks used per node. E.g. the mpirun command in MPICH does this via
its -np and -ppn switches. Ditto for OpenMPI via -np and -npernode.
When using KOKKOS built with host=OMP, you need to choose how many
OpenMP threads per MPI task will be used (via the "-k" command-line
switch discussed below). Note that the product of MPI tasks * OpenMP
threads/task should not exceed the physical number of cores (on a
node), otherwise performance will suffer.
When using the KOKKOS package built with device=CUDA, you must use
exactly one MPI task per physical GPU.
When using the KOKKOS package built with host=MIC for Intel Xeon Phi
coprocessor support you need to insure there are one or more MPI tasks
per coprocessor, and choose the number of coprocessor threads to use
per MPI task (via the "-k" command-line switch discussed below). The
product of MPI tasks * coprocessor threads/task should not exceed the
maximum number of threads the coproprocessor is designed to run,
otherwise performance will suffer. This value is 240 for current
generation Xeon Phi(TM) chips, which is 60 physical cores * 4
threads/core. Note that with the KOKKOS package you do not need to
specify how many Phi coprocessors there are per node; each
coprocessors is simply treated as running some number of MPI tasks.
You must use the "-k on" :ref:`command-line switch <start_7>` to enable the KOKKOS package. It
takes additional arguments for hardware settings appropriate to your
system. Those arguments are :ref:`documented here <start_7>`. The two most commonly used
options are:
.. parsed-literal::
-k on t Nt g Ng
The "t Nt" option applies to host=OMP (even if device=CUDA) and
host=MIC. For host=OMP, it specifies how many OpenMP threads per MPI
task to use with a node. For host=MIC, it specifies how many Xeon Phi
threads per MPI task to use within a node. The default is Nt = 1.
Note that for host=OMP this is effectively MPI-only mode which may be
fine. But for host=MIC you will typically end up using far less than
all the 240 available threads, which could give very poor performance.
The "g Ng" option applies to device=CUDA. It specifies how many GPUs
per compute node to use. The default is 1, so this only needs to be
specified is you have 2 or more GPUs per compute node.
The "-k on" switch also issues a "package kokkos" command (with no
additional arguments) which sets various KOKKOS options to default
values, as discussed on the :doc:`package <package>` command doc page.
Use the "-sf kk" :ref:`command-line switch <start_7>`,
which will automatically append "kk" to styles that support it. Use
the "-pk kokkos" :ref:`command-line switch <start_7>` if
you wish to change any of the default :doc:`package kokkos <package>`
optionns set by the "-k on" :ref:`command-line switch <start_7>`.
Note that the default for the :doc:`package kokkos <package>` command is
to use "full" neighbor lists and set the Newton flag to "off" for both
pairwise and bonded interactions. This typically gives fastest
performance. If the :doc:`newton <newton>` command is used in the input
script, it can override the Newton flag defaults.
However, when running in MPI-only mode with 1 thread per MPI task, it
will typically be faster to use "half" neighbor lists and set the
Newton flag to "on", just as is the case for non-accelerated pair
styles. You can do this with the "-pk" :ref:`command-line switch <start_7>`.
**Or run with the KOKKOS package by editing an input script:**
The discussion above for the mpirun/mpiexec command and setting
appropriate thread and GPU values for host=OMP or host=MIC or
device=CUDA are the same.
You must still use the "-k on" :ref:`command-line switch <start_7>` to enable the KOKKOS package, and
specify its additional arguments for hardware options appopriate to
your system, as documented above.
Use the :doc:`suffix kk <suffix>` command, or you can explicitly add a
"kk" suffix to individual styles in your input script, e.g.
.. parsed-literal::
pair_style lj/cut/kk 2.5
You only need to use the :doc:`package kokkos <package>` command if you
wish to change any of its option defaults, as set by the "-k on"
:ref:`command-line switch <start_7>`.
**Speed-ups to expect:**
The performance of KOKKOS running in different modes is a function of
your hardware, which KOKKOS-enable styles are used, and the problem
size.
Generally speaking, the following rules of thumb apply:
* When running on CPUs only, with a single thread per MPI task,
performance of a KOKKOS style is somewhere between the standard
(un-accelerated) styles (MPI-only mode), and those provided by the
USER-OMP package. However the difference between all 3 is small (less
than 20%).
* When running on CPUs only, with multiple threads per MPI task,
performance of a KOKKOS style is a bit slower than the USER-OMP
package.
* When running on GPUs, KOKKOS is typically faster than the USER-CUDA
and GPU packages.
* When running on Intel Xeon Phi, KOKKOS is not as fast as
the USER-INTEL package, which is optimized for that hardware.
See the `Benchmark page <http://lammps.sandia.gov/bench.html>`_ of the
LAMMPS web site for performance of the KOKKOS package on different
hardware.
**Guidelines for best performance:**
Here are guidline for using the KOKKOS package on the different
hardware configurations listed above.
Many of the guidelines use the :doc:`package kokkos <package>` command
See its doc page for details and default settings. Experimenting with
its options can provide a speed-up for specific calculations.
**Running on a multi-core CPU:**
If N is the number of physical cores/node, then the number of MPI
tasks/node * number of threads/task should not exceed N, and should
typically equal N. Note that the default threads/task is 1, as set by
the "t" keyword of the "-k" :ref:`command-line switch <start_7>`. If you do not change this, no
additional parallelism (beyond MPI) will be invoked on the host
CPU(s).
You can compare the performance running in different modes:
* run with 1 MPI task/node and N threads/task
* run with N MPI tasks/node and 1 thread/task
* run with settings in between these extremes
Examples of mpirun commands in these modes are shown above.
When using KOKKOS to perform multi-threading, it is important for
performance to bind both MPI tasks to physical cores, and threads to
physical cores, so they do not migrate during a simulation.
If you are not certain MPI tasks are being bound (check the defaults
for your MPI installation), binding can be forced with these flags:
.. parsed-literal::
OpenMPI 1.8: mpirun -np 2 -bind-to socket -map-by socket ./lmp_openmpi ...
Mvapich2 2.0: mpiexec -np 2 -bind-to socket -map-by socket ./lmp_mvapich ...
For binding threads with the KOKKOS OMP option, use thread affinity
environment variables to force binding. With OpenMP 3.1 (gcc 4.7 or
later, intel 12 or later) setting the environment variable
OMP_PROC_BIND=true should be sufficient. For binding threads with the
KOKKOS pthreads option, compile LAMMPS the KOKKOS HWLOC=yes option, as
discussed in :ref:`Section 2.3.4 <start_3_4>` of the
manual.
**Running on GPUs:**
Insure the -arch setting in the machine makefile you are using,
e.g. src/MAKE/Makefile.cuda, is correct for your GPU hardware/software
(see :ref:`this section <start_3_4>` of the manual for
details).
The -np setting of the mpirun command should set the number of MPI
tasks/node to be equal to the # of physical GPUs on the node.
Use the "-k" :ref:`command-line switch <start_7>` to
specify the number of GPUs per node, and the number of threads per MPI
task. As above for multi-core CPUs (and no GPU), if N is the number
of physical cores/node, then the number of MPI tasks/node * number of
threads/task should not exceed N. With one GPU (and one MPI task) it
may be faster to use less than all the available cores, by setting
threads/task to a smaller value. This is because using all the cores
on a dual-socket node will incur extra cost to copy memory from the
2nd socket to the GPU.
Examples of mpirun commands that follow these rules are shown above.
.. note::
When using a GPU, you will achieve the best performance if your
input script does not use any fix or compute styles which are not yet
Kokkos-enabled. This allows data to stay on the GPU for multiple
timesteps, without being copied back to the host CPU. Invoking a
non-Kokkos fix or compute, or performing I/O for
:doc:`thermo <thermo_style>` or :doc:`dump <dump>` output will cause data
to be copied back to the CPU.
You cannot yet assign multiple MPI tasks to the same GPU with the
KOKKOS package. We plan to support this in the future, similar to the
GPU package in LAMMPS.
You cannot yet use both the host (multi-threaded) and device (GPU)
together to compute pairwise interactions with the KOKKOS package. We
hope to support this in the future, similar to the GPU package in
LAMMPS.
**Running on an Intel Phi:**
Kokkos only uses Intel Phi processors in their "native" mode, i.e.
not hosted by a CPU.
As illustrated above, build LAMMPS with OMP=yes (the default) and
MIC=yes. The latter insures code is correctly compiled for the Intel
Phi. The OMP setting means OpenMP will be used for parallelization on
the Phi, which is currently the best option within Kokkos. In the
future, other options may be added.
Current-generation Intel Phi chips have either 61 or 57 cores. One
core should be excluded for running the OS, leaving 60 or 56 cores.
Each core is hyperthreaded, so there are effectively N = 240 (4*60) or
N = 224 (4*56) cores to run on.
The -np setting of the mpirun command sets the number of MPI
tasks/node. The "-k on t Nt" command-line switch sets the number of
threads/task as Nt. The product of these 2 values should be N, i.e.
240 or 224. Also, the number of threads/task should be a multiple of
4 so that logical threads from more than one MPI task do not run on
the same physical core.
Examples of mpirun commands that follow these rules are shown above.
Restrictions
""""""""""""
As noted above, if using GPUs, the number of MPI tasks per compute
node should equal to the number of GPUs per compute node. In the
future Kokkos will support assigning multiple MPI tasks to a single
GPU.
Currently Kokkos does not support AMD GPUs due to limits in the
available backend programming models. Specifically, Kokkos requires
extensive C++ support from the Kernel language. This is expected to
change in the future.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

178
doc/_sources/accelerate_omp.txt Normal file
View File

@ -0,0 +1,178 @@
:doc:`Return to Section accelerate overview <Section_accelerate>`
5.USER-OMP package
------------------
The USER-OMP package was developed by Axel Kohlmeyer at Temple
University. It provides multi-threaded versions of most pair styles,
nearly all bonded styles (bond, angle, dihedral, improper), several
Kspace styles, and a few fix styles. The package currently uses the
OpenMP interface for multi-threading.
Here is a quick overview of how to use the USER-OMP package, assuming
one or more 16-core nodes. More details follow.
.. parsed-literal::
use -fopenmp with CCFLAGS and LINKFLAGS in Makefile.machine
make yes-user-omp
make mpi # build with USER-OMP package, if settings added to Makefile.mpi
make omp # or Makefile.omp already has settings
Make.py -v -p omp -o mpi -a file mpi # or one-line build via Make.py
.. parsed-literal::
lmp_mpi -sf omp -pk omp 16 < in.script # 1 MPI task, 16 threads
mpirun -np 4 lmp_mpi -sf omp -pk omp 4 -in in.script # 4 MPI tasks, 4 threads/task
mpirun -np 32 -ppn 4 lmp_mpi -sf omp -pk omp 4 -in in.script # 8 nodes, 4 MPI tasks/node, 4 threads/task
**Required hardware/software:**
Your compiler must support the OpenMP interface. You should have one
or more multi-core CPUs so that multiple threads can be launched by
each MPI task running on a CPU.
**Building LAMMPS with the USER-OMP package:**
The lines above illustrate how to include/build with the USER-OMP
package in two steps, using the "make" command. Or how to do it with
one command via the src/Make.py script, described in :ref:`Section 2.4 <start_4>` of the manual. Type "Make.py -h" for
help.
Note that the CCFLAGS and LINKFLAGS settings in Makefile.machine must
include "-fopenmp". Likewise, if you use an Intel compiler, the
CCFLAGS setting must include "-restrict". The Make.py command will
add these automatically.
**Run with the USER-OMP package from the command line:**
The mpirun or mpiexec command sets the total number of MPI tasks used
by LAMMPS (one or multiple per compute node) and the number of MPI
tasks used per node. E.g. the mpirun command in MPICH does this via
its -np and -ppn switches. Ditto for OpenMPI via -np and -npernode.
You need to choose how many OpenMP threads per MPI task will be used
by the USER-OMP package. Note that the product of MPI tasks *
threads/task should not exceed the physical number of cores (on a
node), otherwise performance will suffer.
As in the lines above, use the "-sf omp" :ref:`command-line switch <start_7>`, which will automatically append
"omp" to styles that support it. The "-sf omp" switch also issues a
default :doc:`package omp 0 <package>` command, which will set the
number of threads per MPI task via the OMP_NUM_THREADS environment
variable.
You can also use the "-pk omp Nt" :ref:`command-line switch <start_7>`, to explicitly set Nt = # of OpenMP
threads per MPI task to use, as well as additional options. Its
syntax is the same as the :doc:`package omp <package>` command whose doc
page gives details, including the default values used if it is not
specified. It also gives more details on how to set the number of
threads via the OMP_NUM_THREADS environment variable.
**Or run with the USER-OMP package by editing an input script:**
The discussion above for the mpirun/mpiexec command, MPI tasks/node,
and threads/MPI task is the same.
Use the :doc:`suffix omp <suffix>` command, or you can explicitly add an
"omp" suffix to individual styles in your input script, e.g.
.. parsed-literal::
pair_style lj/cut/omp 2.5
You must also use the :doc:`package omp <package>` command to enable the
USER-OMP package. When you do this you also specify how many threads
per MPI task to use. The command doc page explains other options and
how to set the number of threads via the OMP_NUM_THREADS environment
variable.
**Speed-ups to expect:**
Depending on which styles are accelerated, you should look for a
reduction in the "Pair time", "Bond time", "KSpace time", and "Loop
time" values printed at the end of a run.
You may see a small performance advantage (5 to 20%) when running a
USER-OMP style (in serial or parallel) with a single thread per MPI
task, versus running standard LAMMPS with its standard un-accelerated
styles (in serial or all-MPI parallelization with 1 task/core). This
is because many of the USER-OMP styles contain similar optimizations
to those used in the OPT package, described in :doc:`Section accelerate 5.3.6 <accelerate_opt>`.
With multiple threads/task, the optimal choice of number of MPI
tasks/node and OpenMP threads/task can vary a lot and should always be
tested via benchmark runs for a specific simulation running on a
specific machine, paying attention to guidelines discussed in the next
sub-section.
A description of the multi-threading strategy used in the USER-OMP
package and some performance examples are `presented here <http://sites.google.com/site/akohlmey/software/lammps-icms/lammps-icms-tms2011-talk.pdf?attredirects=0&d=1>`_
**Guidelines for best performance:**
For many problems on current generation CPUs, running the USER-OMP
package with a single thread/task is faster than running with multiple
threads/task. This is because the MPI parallelization in LAMMPS is
often more efficient than multi-threading as implemented in the
USER-OMP package. The parallel efficiency (in a threaded sense) also
varies for different USER-OMP styles.
Using multiple threads/task can be more effective under the following
circumstances:
* Individual compute nodes have a significant number of CPU cores but
the CPU itself has limited memory bandwidth, e.g. for Intel Xeon 53xx
(Clovertown) and 54xx (Harpertown) quad-core processors. Running one
MPI task per CPU core will result in significant performance
degradation, so that running with 4 or even only 2 MPI tasks per node
is faster. Running in hybrid MPI+OpenMP mode will reduce the
inter-node communication bandwidth contention in the same way, but
offers an additional speedup by utilizing the otherwise idle CPU
cores.
* The interconnect used for MPI communication does not provide
sufficient bandwidth for a large number of MPI tasks per node. For
example, this applies to running over gigabit ethernet or on Cray XT4
or XT5 series supercomputers. As in the aforementioned case, this
effect worsens when using an increasing number of nodes.
* The system has a spatially inhomogeneous particle density which does
not map well to the :doc:`domain decomposition scheme <processors>` or
:doc:`load-balancing <balance>` options that LAMMPS provides. This is
because multi-threading achives parallelism over the number of
particles, not via their distribution in space.
* A machine is being used in "capability mode", i.e. near the point
where MPI parallelism is maxed out. For example, this can happen when
using the :doc:`PPPM solver <kspace_style>` for long-range
electrostatics on large numbers of nodes. The scaling of the KSpace
calculation (see the :doc:`kspace_style <kspace_style>` command) becomes
the performance-limiting factor. Using multi-threading allows less
MPI tasks to be invoked and can speed-up the long-range solver, while
increasing overall performance by parallelizing the pairwise and
bonded calculations via OpenMP. Likewise additional speedup can be
sometimes be achived by increasing the length of the Coulombic cutoff
and thus reducing the work done by the long-range solver. Using the
:doc:`run_style verlet/split <run_style>` command, which is compatible
with the USER-OMP package, is an alternative way to reduce the number
of MPI tasks assigned to the KSpace calculation.
Additional performance tips are as follows:
* The best parallel efficiency from *omp* styles is typically achieved
when there is at least one MPI task per physical CPU chip, i.e. socket
or die.
* It is usually most efficient to restrict threading to a single
socket, i.e. use one or more MPI task per socket.
* NOTE: By default, several current MPI implementations use a processor
affinity setting that restricts each MPI task to a single CPU core.
Using multi-threading in this mode will force all threads to share the
one core and thus is likely to be counterproductive. Instead, binding
MPI tasks to a (multi-core) socket, should solve this issue.
Restrictions
""""""""""""
None.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

74
doc/_sources/accelerate_opt.txt Normal file
View File

@ -0,0 +1,74 @@
:doc:`Return to Section accelerate overview <Section_accelerate>`
5.OPT package
-------------
The OPT package was developed by James Fischer (High Performance
Technologies), David Richie, and Vincent Natoli (Stone Ridge
Technologies). It contains a handful of pair styles whose compute()
methods were rewritten in C++ templated form to reduce the overhead
due to if tests and other conditional code.
Here is a quick overview of how to use the OPT package. More details
follow.
.. parsed-literal::
make yes-opt
make mpi # build with the OPT pacakge
Make.py -v -p opt -o mpi -a file mpi # or one-line build via Make.py
.. parsed-literal::
lmp_mpi -sf opt -in in.script # run in serial
mpirun -np 4 lmp_mpi -sf opt -in in.script # run in parallel
**Required hardware/software:**
None.
**Building LAMMPS with the OPT package:**
The lines above illustrate how to build LAMMPS with the OPT package in
two steps, using the "make" command. Or how to do it with one command
via the src/Make.py script, described in :ref:`Section 2.4 <start_4>` of the manual. Type "Make.py -h" for
help.
Note that if you use an Intel compiler to build with the OPT package,
the CCFLAGS setting in your Makefile.machine must include "-restrict".
The Make.py command will add this automatically.
**Run with the OPT package from the command line:**
As in the lines above, use the "-sf opt" :ref:`command-line switch <start_7>`, which will automatically append
"opt" to styles that support it.
**Or run with the OPT package by editing an input script:**
Use the :doc:`suffix opt <suffix>` command, or you can explicitly add an
"opt" suffix to individual styles in your input script, e.g.
.. parsed-literal::
pair_style lj/cut/opt 2.5
**Speed-ups to expect:**
You should see a reduction in the "Pair time" value printed at the end
of a run. On most machines for reasonable problem sizes, it will be a
5 to 20% savings.
**Guidelines for best performance:**
Just try out an OPT pair style to see how it performs.
Restrictions
""""""""""""
None.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

113
doc/_sources/angle_charmm.txt Normal file
View File

@ -0,0 +1,113 @@
.. index:: angle_style charmm
angle_style charmm command
==========================
angle_style charmm/intel command
================================
angle_style charmm/kk command
=============================
angle_style charmm/omp command
==============================
Syntax
""""""
.. parsed-literal::
angle_style charmm
Examples
""""""""
.. parsed-literal::
angle_style charmm
angle_coeff 1 300.0 107.0 50.0 3.0
Description
"""""""""""
The *charmm* angle style uses the potential
.. image:: Eqs/angle_charmm.jpg
:align: center
with an additional Urey_Bradley term based on the distance *r* between
the 1st and 3rd atoms in the angle. K, theta0, Kub, and Rub are
coefficients defined for each angle type.
See :ref:`(MacKerell) <MacKerell>` for a description of the CHARMM force
field.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy/radian^2)
* theta0 (degrees)
* K_ub (energy/distance^2)
* r_ub (distance)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of K are in energy/radian^2.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
----------
.. _MacKerell:
**(MacKerell)** MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field,
Fischer, Gao, Guo, Ha, et al, J Phys Chem, 102, 3586 (1998).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

139
doc/_sources/angle_class2.txt Normal file
View File

@ -0,0 +1,139 @@
.. index:: angle_style class2
angle_style class2 command
==========================
angle_style class2/omp command
==============================
Syntax
""""""
.. parsed-literal::
angle_style class2
Examples
""""""""
.. parsed-literal::
angle_style class2
angle_coeff * 75.0
angle_coeff 1 bb 10.5872 1.0119 1.5228
angle_coeff * ba 3.6551 24.895 1.0119 1.5228
Description
"""""""""""
The *class2* angle style uses the potential
.. image:: Eqs/angle_class2.jpg
:align: center
where Ea is the angle term, Ebb is a bond-bond term, and Eba is a
bond-angle term. Theta0 is the equilibrium angle and r1 and r2 are
the equilibrium bond lengths.
See :ref:`(Sun) <Sun>` for a description of the COMPASS class2 force field.
Coefficients for the Ea, Ebb, and Eba formulas must be defined for
each angle type via the :doc:`angle_coeff <angle_coeff>` command as in
the example above, or in the data file or restart files read by the
:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
commands.
These are the 4 coefficients for the Ea formula:
* theta0 (degrees)
* K2 (energy/radian^2)
* K3 (energy/radian^3)
* K4 (energy/radian^4)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of the various K are in per-radian.
For the Ebb formula, each line in a :doc:`angle_coeff <angle_coeff>`
command in the input script lists 4 coefficients, the first of which
is "bb" to indicate they are BondBond coefficients. In a data file,
these coefficients should be listed under a "BondBond Coeffs" heading
and you must leave out the "bb", i.e. only list 3 coefficients after
the angle type.
* bb
* M (energy/distance^2)
* r1 (distance)
* r2 (distance)
For the Eba formula, each line in a :doc:`angle_coeff <angle_coeff>`
command in the input script lists 5 coefficients, the first of which
is "ba" to indicate they are BondAngle coefficients. In a data file,
these coefficients should be listed under a "BondAngle Coeffs" heading
and you must leave out the "ba", i.e. only list 4 coefficients after
the angle type.
* ba
* N1 (energy/distance^2)
* N2 (energy/distance^2)
* r1 (distance)
* r2 (distance)
The theta0 value in the Eba formula is not specified, since it is the
same value from the Ea formula.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the CLASS2
package. See the :ref:`Making LAMMPS <start_3>` section
for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
----------
.. _Sun:
**(Sun)** Sun, J Phys Chem B 102, 7338-7364 (1998).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

116
doc/_sources/angle_coeff.txt Normal file
View File

@ -0,0 +1,116 @@
.. index:: angle_coeff
angle_coeff command
===================
Syntax
""""""
.. parsed-literal::
angle_coeff N args
* N = angle type (see asterisk form below)
* args = coefficients for one or more angle types
Examples
""""""""
.. parsed-literal::
angle_coeff 1 300.0 107.0
angle_coeff * 5.0
angle_coeff 2*10 5.0
Description
"""""""""""
Specify the angle force field coefficients for one or more angle types.
The number and meaning of the coefficients depends on the angle style.
Angle coefficients can also be set in the data file read by the
:doc:`read_data <read_data>` command or in a restart file.
N can be specified in one of two ways. An explicit numeric value can
be used, as in the 1st example above. Or a wild-card asterisk can be
used to set the coefficients for multiple angle types. This takes the
form "*" or "*n" or "n*" or "m*n". If N = the number of angle types,
then an asterisk with no numeric values means all types from 1 to N. A
leading asterisk means all types from 1 to n (inclusive). A trailing
asterisk means all types from n to N (inclusive). A middle asterisk
means all types from m to n (inclusive).
Note that using an angle_coeff command can override a previous setting
for the same angle type. For example, these commands set the coeffs
for all angle types, then overwrite the coeffs for just angle type 2:
.. parsed-literal::
angle_coeff * 200.0 107.0 1.2
angle_coeff 2 50.0 107.0
A line in a data file that specifies angle coefficients uses the exact
same format as the arguments of the angle_coeff command in an input
script, except that wild-card asterisks should not be used since
coefficients for all N types must be listed in the file. For example,
under the "Angle Coeffs" section of a data file, the line that
corresponds to the 1st example above would be listed as
.. parsed-literal::
1 300.0 107.0
The :doc:`angle_style class2 <angle_class2>` is an exception to this
rule, in that an additional argument is used in the input script to
allow specification of the cross-term coefficients. See its
doc page for details.
----------
Here is an alphabetic list of angle styles defined in LAMMPS. Click on
the style to display the formula it computes and coefficients
specified by the associated :doc:`angle_coeff <angle_coeff>` command.
Note that there are also additional angle styles submitted by users
which are included in the LAMMPS distribution. The list of these with
links to the individual styles are given in the angle section of :ref:`this page <cmd_5>`.
* :doc:`angle_style none <angle_none>` - turn off angle interactions
* :doc:`angle_style hybrid <angle_hybrid>` - define multiple styles of angle interactions
* :doc:`angle_style charmm <angle_charmm>` - CHARMM angle
* :doc:`angle_style class2 <angle_class2>` - COMPASS (class 2) angle
* :doc:`angle_style cosine <angle_cosine>` - cosine angle potential
* :doc:`angle_style cosine/delta <angle_cosine_delta>` - difference of cosines angle potential
* :doc:`angle_style cosine/periodic <angle_cosine_periodic>` - DREIDING angle
* :doc:`angle_style cosine/squared <angle_cosine_squared>` - cosine squared angle potential
* :doc:`angle_style harmonic <angle_harmonic>` - harmonic angle
* :doc:`angle_style table <angle_table>` - tabulated by angle
----------
Restrictions
""""""""""""
This command must come after the simulation box is defined by a
:doc:`read_data <read_data>`, :doc:`read_restart <read_restart>`, or
:doc:`create_box <create_box>` command.
An angle style must be defined before any angle coefficients are
set, either in the input script or in a data file.
Related commands
""""""""""""""""
:doc:`angle_style <angle_style>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

85
doc/_sources/angle_cosine.txt Normal file
View File

@ -0,0 +1,85 @@
.. index:: angle_style cosine
angle_style cosine command
==========================
angle_style cosine/omp command
==============================
Syntax
""""""
.. parsed-literal::
angle_style cosine
Examples
""""""""
.. parsed-literal::
angle_style cosine
angle_coeff * 75.0
Description
"""""""""""
The *cosine* angle style uses the potential
.. image:: Eqs/angle_cosine.jpg
:align: center
where K is defined for each angle type.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

90
doc/_sources/angle_cosine_delta.txt Normal file
View File

@ -0,0 +1,90 @@
.. index:: angle_style cosine/delta
angle_style cosine/delta command
================================
angle_style cosine/delta/omp command
====================================
Syntax
""""""
.. parsed-literal::
angle_style cosine/delta
Examples
""""""""
.. parsed-literal::
angle_style cosine/delta
angle_coeff 2*4 75.0 100.0
Description
"""""""""""
The *cosine/delta* angle style uses the potential
.. image:: Eqs/angle_cosine_delta.jpg
:align: center
where theta0 is the equilibrium value of the angle, and K is a
prefactor. Note that the usual 1/2 factor is included in K.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy)
* theta0 (degrees)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_style cosine/squared <angle_cosine_squared>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

109
doc/_sources/angle_cosine_periodic.txt Normal file
View File

@ -0,0 +1,109 @@
.. index:: angle_style cosine/periodic
angle_style cosine/periodic command
===================================
angle_style cosine/periodic/omp command
=======================================
Syntax
""""""
.. parsed-literal::
angle_style cosine/periodic
Examples
""""""""
.. parsed-literal::
angle_style cosine/periodic
angle_coeff * 75.0 1 6
Description
"""""""""""
The *cosine/periodic* angle style uses the following potential, which
is commonly used in the :ref:`DREIDING <howto_4>` force
field, particularly for organometallic systems where *n* = 4 might be
used for an octahedral complex and *n* = 3 might be used for a
trigonal center:
.. image:: Eqs/angle_cosine_periodic.jpg
:align: center
where C, B and n are coefficients defined for each angle type.
See :ref:`(Mayo) <Mayo>` for a description of the DREIDING force field
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* C (energy)
* B = 1 or -1
* n = 1, 2, 3, 4, 5 or 6 for periodicity
Note that the prefactor C is specified and not the overall force
constant K = C / n^2. When B = 1, it leads to a minimum for the
linear geometry. When B = -1, it leads to a maximum for the linear
geometry.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
----------
.. _Mayo:
**(Mayo)** Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909
(1990).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

90
doc/_sources/angle_cosine_shift.txt Normal file
View File

@ -0,0 +1,90 @@
.. index:: angle_style cosine/shift
angle_style cosine/shift command
================================
angle_style cosine/shift/omp command
====================================
Syntax
""""""
.. parsed-literal::
angle_style cosine/shift
Examples
""""""""
.. parsed-literal::
angle_style cosine/shift
angle_coeff * 10.0 45.0
Description
"""""""""""
The *cosine/shift* angle style uses the potential
.. image:: Eqs/angle_cosine_shift.jpg
:align: center
where theta0 is the equilibrium angle. The potential is bounded
between -Umin and zero. In the neighborhood of the minimum E=- Umin +
Umin/4(theta-theta0)^2 hence the spring constant is umin/2.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* umin (energy)
* theta (angle)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER-MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`,
:doc:`angle_cosineshiftexp <angle_cosineshiftexp>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

103
doc/_sources/angle_cosine_shift_exp.txt Normal file
View File

@ -0,0 +1,103 @@
.. index:: angle_style cosine/shift/exp
angle_style cosine/shift/exp command
====================================
angle_style cosine/shift/exp/omp command
========================================
Syntax
""""""
.. parsed-literal::
angle_style cosine/shift/exp
Examples
""""""""
.. parsed-literal::
angle_style cosine/shift/exp
angle_coeff * 10.0 45.0 2.0
Description
"""""""""""
The *cosine/shift/exp* angle style uses the potential
.. image:: Eqs/angle_cosine_shift_exp.jpg
:align: center
where Umin, theta, and a are defined for each angle type.
The potential is bounded between [-Umin:0] and the minimum is
located at the angle theta0. The a parameter can be both positive or
negative and is used to control the spring constant at the
equilibrium.
The spring constant is given by k = A exp(A) Umin / [2 (Exp(a)-1)].
For a > 3, k/Umin = a/2 to better than 5% relative error. For negative
values of the a parameter, the spring constant is essentially zero,
and anharmonic terms takes over. The potential is furthermore well
behaved in the limit a -> 0, where it has been implemented to linear
order in a for a < 0.001. In this limit the potential reduces to the
cosineshifted potential.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* umin (energy)
* theta (angle)
* A (real number)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER-MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`,
:doc:`angle_cosineshift <angle_cosineshift>`,
:doc:`dihedral_cosineshift <dihedral_cosineshift>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

90
doc/_sources/angle_cosine_squared.txt Normal file
View File

@ -0,0 +1,90 @@
.. index:: angle_style cosine/squared
angle_style cosine/squared command
==================================
angle_style cosine/squared/omp command
======================================
Syntax
""""""
.. parsed-literal::
angle_style cosine/squared
Examples
""""""""
.. parsed-literal::
angle_style cosine/squared
angle_coeff 2*4 75.0 100.0
Description
"""""""""""
The *cosine/squared* angle style uses the potential
.. image:: Eqs/angle_cosine_squared.jpg
:align: center
where theta0 is the equilibrium value of the angle, and K is a
prefactor. Note that the usual 1/2 factor is included in K.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy)
* theta0 (degrees)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

152
doc/_sources/angle_dipole.txt Normal file
View File

@ -0,0 +1,152 @@
.. index:: angle_style dipole
angle_style dipole command
==========================
angle_style dipole/omp command
==============================
Syntax
""""""
.. parsed-literal::
angle_style dipole
Examples
""""""""
.. parsed-literal::
angle_style dipole
angle_coeff 6 2.1 180.0
Description
"""""""""""
The *dipole* angle style is used to control the orientation of a dipolar
atom within a molecule :ref:`(Orsi) <Orsi>`. Specifically, the *dipole* angle
style restrains the orientation of a point dipole mu_j (embedded in atom
'j') with respect to a reference (bond) vector r_ij = r_i - r_j, where 'i'
is another atom of the same molecule (typically, 'i' and 'j' are also
covalently bonded).
It is convenient to define an angle gamma between the 'free' vector mu_j
and the reference (bond) vector r_ij:
.. image:: Eqs/angle_dipole_gamma.jpg
:align: center
The *dipole* angle style uses the potential:
.. image:: Eqs/angle_dipole_potential.jpg
:align: center
where K is a rigidity constant and gamma0 is an equilibrium (reference)
angle.
The torque on the dipole can be obtained by differentiating the
potential using the 'chain rule' as in appendix C.3 of
:ref:`(Allen) <Allen>`:
.. image:: Eqs/angle_dipole_torque.jpg
:align: center
Example: if gamma0 is set to 0 degrees, the torque generated by
the potential will tend to align the dipole along the reference
direction defined by the (bond) vector r_ij (in other words, mu_j is
restrained to point towards atom 'i').
The dipolar torque T_j must be counterbalanced in order to conserve
the local angular momentum. This is achieved via an additional force
couple generating a torque equivalent to the opposite of T_j:
.. image:: Eqs/angle_dipole_couple.jpg
:align: center
where F_i and F_j are applied on atoms i and j, respectively.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy)
* gamma0 (degrees)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_6>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER-MISC package. See the :ref:`Making LAMMPS <2_3>`
section for more info on packages.
.. note::
In the "Angles" section of the data file, the atom ID 'j'
corresponding to the dipole to restrain must come before the atom ID
of the reference atom 'i'. A third atom ID 'k' must also be provided,
although 'k' is just a 'dummy' atom which can be any atom; it may be
useful to choose a convention (e.g., 'k'='i') and adhere to it. For
example, if ID=1 for the dipolar atom to restrain, and ID=2 for the
reference atom, the corresponding line in the "Angles" section of the
data file would read: X X 1 2 2
The "newton" command for intramolecular interactions must be "on"
(which is the default).
This angle style should not be used with SHAKE.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_hybrid <angle_hybrid>`
**Default:** none
----------
.. _Orsi:
**(Orsi)** Orsi & Essex, The ELBA force field for coarse-grain modeling of
lipid membranes, PloS ONE 6(12): e28637, 2011.
.. _Allen:
**(Allen)** Allen & Tildesley, Computer Simulation of Liquids,
Clarendon Press, Oxford, 1987.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

85
doc/_sources/angle_fourier.txt Normal file
View File

@ -0,0 +1,85 @@
.. index:: angle_style fourier
angle_style fourier command
===========================
angle_style fourier/omp command
===============================
Syntax
""""""
.. parsed-literal::
angle_style fourier
Examples
""""""""
angle_style fourier
angle_coeff 75.0 1.0 1.0 1.0
Description
"""""""""""
The *fourier* angle style uses the potential
.. image:: Eqs/angle_fourier.jpg
:align: center
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy)
* C0 (real)
* C1 (real)
* C2 (real)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER_MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

84
doc/_sources/angle_fourier_simple.txt Normal file
View File

@ -0,0 +1,84 @@
.. index:: angle_style fourier/simple
angle_style fourier/simple command
==================================
angle_style fourier/simple/omp command
======================================
Syntax
""""""
.. parsed-literal::
angle_style fourier/simple
Examples
""""""""
angle_style fourier/simple
angle_coeff 100.0 -1.0 1.0
Description
"""""""""""
The *fourier/simple* angle style uses the potential
.. image:: Eqs/angle_fourier_simple.jpg
:align: center
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy)
* c (real)
* n (real)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER_MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

93
doc/_sources/angle_harmonic.txt Normal file
View File

@ -0,0 +1,93 @@
.. index:: angle_style harmonic
angle_style harmonic command
============================
angle_style harmonic/kk command
===============================
angle_style harmonic/omp command
================================
Syntax
""""""
.. parsed-literal::
angle_style harmonic
Examples
""""""""
.. parsed-literal::
angle_style harmonic
angle_coeff 1 300.0 107.0
Description
"""""""""""
The *harmonic* angle style uses the potential
.. image:: Eqs/angle_harmonic.jpg
:align: center
where theta0 is the equilibrium value of the angle, and K is a
prefactor. Note that the usual 1/2 factor is included in K.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy/radian^2)
* theta0 (degrees)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of K are in energy/radian^2.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
none
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

109
doc/_sources/angle_hybrid.txt Normal file
View File

@ -0,0 +1,109 @@
.. index:: angle_style hybrid
angle_style hybrid command
==========================
Syntax
""""""
.. parsed-literal::
angle_style hybrid style1 style2 ...
* style1,style2 = list of one or more angle styles
Examples
""""""""
.. parsed-literal::
angle_style hybrid harmonic cosine
angle_coeff 1 harmonic 80.0 30.0
angle_coeff 2* cosine 50.0
Description
"""""""""""
The *hybrid* style enables the use of multiple angle styles in one
simulation. An angle style is assigned to each angle type. For
example, angles in a polymer flow (of angle type 1) could be computed
with a *harmonic* potential and angles in the wall boundary (of angle
type 2) could be computed with a *cosine* potential. The assignment
of angle type to style is made via the :doc:`angle_coeff <angle_coeff>`
command or in the data file.
In the angle_coeff commands, the name of an angle style must be added
after the angle type, with the remaining coefficients being those
appropriate to that style. In the example above, the 2 angle_coeff
commands set angles of angle type 1 to be computed with a *harmonic*
potential with coefficients 80.0, 30.0 for K, theta0. All other angle
types (2-N) are computed with a *cosine* potential with coefficient
50.0 for K.
If angle coefficients are specified in the data file read via the
:doc:`read_data <read_data>` command, then the same rule applies.
E.g. "harmonic" or "cosine", must be added after the angle type, for each
line in the "Angle Coeffs" section, e.g.
.. parsed-literal::
Angle Coeffs
.. parsed-literal::
1 harmonic 80.0 30.0
2 cosine 50.0
...
If *class2* is one of the angle hybrid styles, the same rule holds for
specifying additional BondBond (and BondAngle) coefficients either via
the input script or in the data file. I.e. *class2* must be added to
each line after the angle type. For lines in the BondBond (or
BondAngle) section of the data file for angle types that are not
*class2*, you must use an angle style of *skip* as a placeholder, e.g.
.. parsed-literal::
BondBond Coeffs
.. parsed-literal::
1 skip
2 class2 3.6512 1.0119 1.0119
...
Note that it is not necessary to use the angle style *skip* in the
input script, since BondBond (or BondAngle) coefficients need not be
specified at all for angle types that are not *class2*.
An angle style of *none* with no additional coefficients can be used
in place of an angle style, either in a input script angle_coeff
command or in the data file, if you desire to turn off interactions
for specific angle types.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Unlike other angle styles, the hybrid angle style does not store angle
coefficient info for individual sub-styles in a :doc:`binary restart files <restart>`. Thus when retarting a simulation from a restart
file, you need to re-specify angle_coeff commands.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

38
doc/_sources/angle_none.txt Normal file
View File

@ -0,0 +1,38 @@
.. index:: angle_style none
angle_style none command
========================
Syntax
""""""
.. parsed-literal::
angle_style none
Examples
""""""""
.. parsed-literal::
angle_style none
Description
"""""""""""
Using an angle style of none means angle forces are not computed, even
if triplets of angle atoms were listed in the data file read by the
:doc:`read_data <read_data>` command.
Restrictions
""""""""""""
none
**Related commands:** none
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

93
doc/_sources/angle_quartic.txt Normal file
View File

@ -0,0 +1,93 @@
.. index:: angle_style quartic
angle_style quartic command
===========================
angle_style quartic/omp command
===============================
Syntax
""""""
.. parsed-literal::
angle_style quartic
Examples
""""""""
.. parsed-literal::
angle_style quartic
angle_coeff 1 129.1948 56.8726 -25.9442 -14.2221
Description
"""""""""""
The *quartic* angle style uses the potential
.. image:: Eqs/angle_quartic.jpg
:align: center
where theta0 is the equilibrium value of the angle, and K is a
prefactor. Note that the usual 1/2 factor is included in K.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* theta0 (degrees)
* K2 (energy/radian^2)
* K3 (energy/radian^3)
* K4 (energy/radian^4)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of K are in energy/radian^2.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER_MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

70
doc/_sources/angle_sdk.txt Normal file
View File

@ -0,0 +1,70 @@
.. index:: angle_style sdk
angle_style sdk command
=======================
Syntax
""""""
.. parsed-literal::
angle_style sdk
.. parsed-literal::
angle_style sdk/omp
Examples
""""""""
.. parsed-literal::
angle_style sdk
angle_coeff 1 300.0 107.0
Description
"""""""""""
The *sdk* angle style is a combination of the harmonic angle potential,
.. image:: Eqs/angle_harmonic.jpg
:align: center
where theta0 is the equilibrium value of the angle and K a prefactor,
with the *repulsive* part of the non-bonded *lj/sdk* pair style
between the atoms 1 and 3. This angle potential is intended for
coarse grained MD simulations with the CMM parametrization using the
:doc:`pair_style lj/sdk <pair_sdk>`. Relative to the pair_style
*lj/sdk*, however, the energy is shifted by *epsilon*, to avoid sudden
jumps. Note that the usual 1/2 factor is included in K.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above:
* K (energy/radian^2)
* theta0 (degrees)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of K are in energy/radian^2.
The also required *lj/sdk* parameters will be extracted automatically
from the pair_style.
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER-CG-CMM package. See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_style harmonic <angle_harmonic>`, :doc:`pair_style lj/sdk <pair_sdk>`,
:doc:`pair_style lj/sdk/coul/long <pair_sdk>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

112
doc/_sources/angle_style.txt Normal file
View File

@ -0,0 +1,112 @@
.. index:: angle_style
angle_style command
===================
Syntax
""""""
.. parsed-literal::
angle_style style
* style = *none* or *hybrid* or *charmm* or *class2* or *cosine* or *cosine/squared* or *harmonic*
Examples
""""""""
.. parsed-literal::
angle_style harmonic
angle_style charmm
angle_style hybrid harmonic cosine
Description
"""""""""""
Set the formula(s) LAMMPS uses to compute angle interactions between
triplets of atoms, which remain in force for the duration of the
simulation. The list of angle triplets is read in by a
:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>` command
from a data or restart file.
Hybrid models where angles are computed using different angle
potentials can be setup using the *hybrid* angle style.
The coefficients associated with a angle style can be specified in a
data or restart file or via the :doc:`angle_coeff <angle_coeff>` command.
All angle potentials store their coefficient data in binary restart
files which means angle_style and :doc:`angle_coeff <angle_coeff>`
commands do not need to be re-specified in an input script that
restarts a simulation. See the :doc:`read_restart <read_restart>`
command for details on how to do this. The one exception is that
angle_style *hybrid* only stores the list of sub-styles in the restart
file; angle coefficients need to be re-specified.
.. note::
When both an angle and pair style is defined, the
:doc:`special_bonds <special_bonds>` command often needs to be used to
turn off (or weight) the pairwise interaction that would otherwise
exist between 3 bonded atoms.
In the formulas listed for each angle style, *theta* is the angle
between the 3 atoms in the angle.
----------
Here is an alphabetic list of angle styles defined in LAMMPS. Click on
the style to display the formula it computes and coefficients
specified by the associated :doc:`angle_coeff <angle_coeff>` command.
Note that there are also additional angle styles submitted by users
which are included in the LAMMPS distribution. The list of these with
links to the individual styles are given in the angle section of :ref:`this page <cmd_5>`.
* :doc:`angle_style none <angle_none>` - turn off angle interactions
* :doc:`angle_style hybrid <angle_hybrid>` - define multiple styles of angle interactions
* :doc:`angle_style charmm <angle_charmm>` - CHARMM angle
* :doc:`angle_style class2 <angle_class2>` - COMPASS (class 2) angle
* :doc:`angle_style cosine <angle_cosine>` - cosine angle potential
* :doc:`angle_style cosine/delta <angle_cosine_delta>` - difference of cosines angle potential
* :doc:`angle_style cosine/periodic <angle_cosine_periodic>` - DREIDING angle
* :doc:`angle_style cosine/squared <angle_cosine_squared>` - cosine squared angle potential
* :doc:`angle_style harmonic <angle_harmonic>` - harmonic angle
* :doc:`angle_style table <angle_table>` - tabulated by angle
----------
Restrictions
""""""""""""
Angle styles can only be set for atom_styles that allow angles to be
defined.
Most angle styles are part of the MOLECULE package. They are only
enabled if LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
The doc pages for individual bond potentials tell if it is part of a
package.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
Default
"""""""
.. parsed-literal::
angle_style none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

175
doc/_sources/angle_table.txt Normal file
View File

@ -0,0 +1,175 @@
.. index:: angle_style table
angle_style table command
=========================
angle_style table/omp command
=============================
Syntax
""""""
.. parsed-literal::
angle_style table style N
* style = *linear* or *spline* = method of interpolation
* N = use N values in table
Examples
""""""""
.. parsed-literal::
angle_style table linear 1000
angle_coeff 3 file.table ENTRY1
Description
"""""""""""
Style *table* creates interpolation tables of length *N* from angle
potential and derivative values listed in a file(s) as a function of
angle The files are read by the :doc:`angle_coeff <angle_coeff>`
command.
The interpolation tables are created by fitting cubic splines to the
file values and interpolating energy and derivative values at each of
*N* angles. During a simulation, these tables are used to interpolate
energy and force values on individual atoms as needed. The
interpolation is done in one of 2 styles: *linear* or *spline*.
For the *linear* style, the angle is used to find 2 surrounding table
values from which an energy or its derivative is computed by linear
interpolation.
For the *spline* style, a cubic spline coefficients are computed and
stored at each of the *N* values in the table. The angle is used to
find the appropriate set of coefficients which are used to evaluate a
cubic polynomial which computes the energy or derivative.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above.
* filename
* keyword
The filename specifies a file containing tabulated energy and
derivative values. The keyword specifies a section of the file. The
format of this file is described below.
----------
The format of a tabulated file is as follows (without the
parenthesized comments):
.. parsed-literal::
# Angle potential for harmonic (one or more comment or blank lines)
.. parsed-literal::
HAM (keyword is the first text on line)
N 181 FP 0 0 EQ 90.0 (N, FP, EQ parameters)
(blank line)
N 181 FP 0 0 (N, FP parameters)
1 0.0 200.5 2.5 (index, angle, energy, derivative)
2 1.0 198.0 2.5
...
181 180.0 0.0 0.0
A section begins with a non-blank line whose 1st character is not a
"#"; blank lines or lines starting with "#" can be used as comments
between sections. The first line begins with a keyword which
identifies the section. The line can contain additional text, but the
initial text must match the argument specified in the
:doc:`angle_coeff <angle_coeff>` command. The next line lists (in any
order) one or more parameters for the table. Each parameter is a
keyword followed by one or more numeric values.
The parameter "N" is required and its value is the number of table
entries that follow. Note that this may be different than the *N*
specified in the :doc:`angle_style table <angle_style>` command. Let
Ntable = *N* in the angle_style command, and Nfile = "N" in the
tabulated file. What LAMMPS does is a preliminary interpolation by
creating splines using the Nfile tabulated values as nodal points. It
uses these to interpolate as needed to generate energy and derivative
values at Ntable different points. The resulting tables of length
Ntable are then used as described above, when computing energy and
force for individual angles and their atoms. This means that if you
want the interpolation tables of length Ntable to match exactly what
is in the tabulated file (with effectively no preliminary
interpolation), you should set Ntable = Nfile.
The "FP" parameter is optional. If used, it is followed by two values
fplo and fphi, which are the 2nd derivatives at the innermost and
outermost angle settings. These values are needed by the spline
construction routines. If not specified by the "FP" parameter, they
are estimated (less accurately) by the first two and last two
derivative values in the table.
The "EQ" parameter is also optional. If used, it is followed by a the
equilibrium angle value, which is used, for example, by the :doc:`fix shake <fix_shake>` command. If not used, the equilibrium angle is
set to 180.0.
Following a blank line, the next N lines list the tabulated values.
On each line, the 1st value is the index from 1 to N, the 2nd value is
the angle value (in degrees), the 3rd value is the energy (in energy
units), and the 4th is -dE/d(theta) (also in energy units). The 3rd
term is the energy of the 3-atom configuration for the specified
angle. The last term is the derivative of the energy with respect to
the angle (in degrees, not radians). Thus the units of the last term
are still energy, not force. The angle values must increase from one
line to the next. The angle values must also begin with 0.0 and end
with 180.0, i.e. span the full range of possible angles.
Note that one file can contain many sections, each with a tabulated
potential. LAMMPS reads the file section by section until it finds
one that matches the specified keyword.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

186
doc/_sources/atom_modify.txt Normal file
View File

@ -0,0 +1,186 @@
.. index:: atom_modify
atom_modify command
===================
Syntax
""""""
.. parsed-literal::
atom_modify keyword values ...
* one or more keyword/value pairs may be appended
* keyword = *id* or *map* or *first* or *sort*
.. parsed-literal::
*id* value = *yes* or *no*
*map* value = *array* or *hash*
*first* value = group-ID = group whose atoms will appear first in internal atom lists
*sort* values = Nfreq binsize
Nfreq = sort atoms spatially every this many time steps
binsize = bin size for spatial sorting (distance units)
Examples
""""""""
.. parsed-literal::
atom_modify map hash
atom_modify map array sort 10000 2.0
atom_modify first colloid
Description
"""""""""""
Modify certain attributes of atoms defined and stored within LAMMPS,
in addition to what is specified by the :doc:`atom_style <atom_style>`
command. The *id* and *map* keywords must be specified before a
simulation box is defined; other keywords can be specified any time.
The *id* keyword determines whether non-zero atom IDs can be assigned
to each atom. If the value is *yes*, which is the default, IDs are
assigned, whether you use the :doc:`create atoms <create_atoms>` or
:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
commands to initialize atoms. If the value is *no* the IDs for all
atoms are assumed to be 0.
If atom IDs are used, they must all be positive integers. They should
also be unique, though LAMMPS does not check for this. Typically they
should also be consecutively numbered (from 1 to Natoms), though this
is not required. Molecular :doc:`atom styles <atom_style>` are those
that store bond topology information (styles bond, angle, molecular,
full). These styles require atom IDs since the IDs are used to encode
the topology. Some other LAMMPS commands also require the use of atom
IDs. E.g. some many-body pair styles use them to avoid double
computation of the I-J interaction between two atoms.
The only reason not to use atom IDs is if you are running an atomic
simulation so large that IDs cannot be uniquely assigned. For a
default LAMMPS build this limit is 2^31 or about 2 billion atoms.
However, even in this case, you can use 64-bit atom IDs, allowing 2^63
or about 9e18 atoms, if you build LAMMPS with the - DLAMMPS_BIGBIG
switch. This is described in :ref:`Section 2.2 <start_2>`
of the manual. If atom IDs are not used, they must be specified as 0
for all atoms, e.g. in a data or restart file.
The *map* keyword determines how atom ID lookup is done for molecular
atom styles. Lookups are performed by bond (angle, etc) routines in
LAMMPS to find the local atom index associated with a global atom ID.
When the *array* value is used, each processor stores a lookup table
of length N, where N is the largest atom ID in the system. This is a
fast, simple method for many simulations, but requires too much memory
for large simulations. The *hash* value uses a hash table to perform
the lookups. This can be slightly slower than the *array* method, but
its memory cost is proportional to the number of atoms owned by a
processor, i.e. N/P when N is the total number of atoms in the system
and P is the number of processors.
When this setting is not specified in your input script, LAMMPS
creates a map, if one is needed, as an array or hash. See the
discussion of default values below for how LAMMPS chooses which kind
of map to build. Note that atomic systems do not normally need to
create a map. However, even in this case some LAMMPS commands will
create a map to find atoms (and then destroy it), or require a
permanent map. An example of the former is the :doc:`velocity loop all <velocity>` command, which uses a map when looping over all
atoms and insuring the same velocity values are assigned to an atom
ID, no matter which processor owns it.
The *first* keyword allows a :doc:`group <group>` to be specified whose
atoms will be maintained as the first atoms in each processor's list
of owned atoms. This in only useful when the specified group is a
small fraction of all the atoms, and there are other operations LAMMPS
is performing that will be sped-up significantly by being able to loop
over the smaller set of atoms. Otherwise the reordering required by
this option will be a net slow-down. The :doc:`neigh_modify include <neigh_modify>` and :doc:`comm_modify group <comm_modify>`
commands are two examples of commands that require this setting to
work efficiently. Several :doc:`fixes <fix>`, most notably time
integration fixes like :doc:`fix nve <fix_nve>`, also take advantage of
this setting if the group they operate on is the group specified by
this command. Note that specifying "all" as the group-ID effectively
turns off the *first* option.
It is OK to use the *first* keyword with a group that has not yet been
defined, e.g. to use the atom_modify first command at the beginning of
your input script. LAMMPS does not use the group until a simullation
is run.
The *sort* keyword turns on a spatial sorting or reordering of atoms
within each processor's sub-domain every *Nfreq* timesteps. If
*Nfreq* is set to 0, then sorting is turned off. Sorting can improve
cache performance and thus speed-up a LAMMPS simulation, as discussed
in a paper by :ref:`(Meloni) <Meloni>`. Its efficacy depends on the problem
size (atoms/processor), how quickly the system becomes disordered, and
various other factors. As a general rule, sorting is typically more
effective at speeding up simulations of liquids as opposed to solids.
In tests we have done, the speed-up can range from zero to 3-4x.
Reordering is peformed every *Nfreq* timesteps during a dynamics run
or iterations during a minimization. More precisely, reordering
occurs at the first reneighboring that occurs after the target
timestep. The reordering is performed locally by each processor,
using bins of the specified *binsize*. If *binsize* is set to 0.0,
then a binsize equal to half the :doc:`neighbor <neighbor>` cutoff
distance (force cutoff plus skin distance) is used, which is a
reasonable value. After the atoms have been binned, they are
reordered so that atoms in the same bin are adjacent to each other in
the processor's 1d list of atoms.
The goal of this procedure is for atoms to put atoms close to each
other in the processor's one-dimensional list of atoms that are also
near to each other spatially. This can improve cache performance when
pairwise intereractions and neighbor lists are computed. Note that if
bins are too small, there will be few atoms/bin. Likewise if bins are
too large, there will be many atoms/bin. In both cases, the goal of
cache locality will be undermined.
.. note::
Running a simulation with sorting on versus off should not
change the simulation results in a statistical sense. However, a
different ordering will induce round-off differences, which will lead
to diverging trajectories over time when comparing two simluations.
Various commands, particularly those which use random numbers
(e.g. :doc:`velocity create <velocity>`, and :doc:`fix langevin <fix_langevin>`), may generate (statistically identical)
results which depend on the order in which atoms are processed. The
order of atoms in a :doc:`dump <dump>` file will also typically change
if sorting is enabled.
Restrictions
""""""""""""
The *first* and *sort* options cannot be used together. Since sorting
is on by default, it will be turned off if the *first* keyword is
used with a group-ID that is not "all".
**Related commands:** none
Default
"""""""
By default, *id* is yes. By default, atomic systems (no bond topology
info) do not use a map. For molecular systems (with bond topology
info), a map is used. The default map style is array if no atom ID is
larger than 1 million, otherwise the default is hash. By default, a
"first" group is not defined. By default, sorting is enabled with a
frequency of 1000 and a binsize of 0.0, which means the neighbor
cutoff will be used to set the bin size.
----------
.. _Meloni:
**(Meloni)** Meloni, Rosati and Colombo, J Chem Phys, 126, 121102 (2007).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

310
doc/_sources/atom_style.txt Normal file
View File

@ -0,0 +1,310 @@
.. index:: atom_style
atom_style command
==================
Syntax
""""""
.. parsed-literal::
atom_style style args
* style = *angle* or *atomic* or *body* or *bond* or *charge* or *dipole* or *electron* or *ellipsoid* or *full* or *line* or *meso* or *molecular* or *peri* or *smd* or *sphere* or *tri* or *template* or *hybrid*
.. parsed-literal::
args = none for any style except *body* and *hybrid*
*body* args = bstyle bstyle-args
bstyle = style of body particles
bstyle-args = additional arguments specific to the bstyle
see the :doc:`body <body>` doc page for details
*template* args = template-ID
template-ID = ID of molecule template specified in a separate :doc:`molecule <molecule>` command
*hybrid* args = list of one or more sub-styles, each with their args
* accelerated styles (with same args) = *angle/cuda* or *angle/kk* or *atomic/cuda* or *atomic/kk* or *bond/kk* or *charge/cuda* or *charge/kk* or *full/cuda* or *full/kk* or *molecular/kk*
Examples
""""""""
.. parsed-literal::
atom_style atomic
atom_style bond
atom_style full
atom_style full/cuda
atom_style body nparticle 2 10
atom_style hybrid charge bond
atom_style hybrid charge body nparticle 2 5
atom_style template myMols
Description
"""""""""""
Define what style of atoms to use in a simulation. This determines
what attributes are associated with the atoms. This command must be
used before a simulation is setup via a :doc:`read_data <read_data>`,
:doc:`read_restart <read_restart>`, or :doc:`create_box <create_box>`
command.
Once a style is assigned, it cannot be changed, so use a style general
enough to encompass all attributes. E.g. with style *bond*, angular
terms cannot be used or added later to the model. It is OK to use a
style more general than needed, though it may be slightly inefficient.
The choice of style affects what quantities are stored by each atom,
what quantities are communicated between processors to enable forces
to be computed, and what quantities are listed in the data file read
by the :doc:`read_data <read_data>` command.
These are the additional attributes of each style and the typical
kinds of physical systems they are used to model. All styles store
coordinates, velocities, atom IDs and types. See the
:doc:`read_data <read_data>`, :doc:`create_atoms <create_atoms>`, and
:doc:`set <set>` commands for info on how to set these various
quantities.
+--------------+-----------------------------------------------------+--------------------------------------+
| *angle* | bonds and angles | bead-spring polymers with stiffness |
+--------------+-----------------------------------------------------+--------------------------------------+
| *atomic* | only the default values | coarse-grain liquids, solids, metals |
+--------------+-----------------------------------------------------+--------------------------------------+
| *body* | mass, inertia moments, quaternion, angular momentum | arbitrary bodies |
+--------------+-----------------------------------------------------+--------------------------------------+
| *bond* | bonds | bead-spring polymers |
+--------------+-----------------------------------------------------+--------------------------------------+
| *charge* | charge | atomic system with charges |
+--------------+-----------------------------------------------------+--------------------------------------+
| *dipole* | charge and dipole moment | system with dipolar particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *electron* | charge and spin and eradius | electronic force field |
+--------------+-----------------------------------------------------+--------------------------------------+
| *ellipsoid* | shape, quaternion, angular momentum | aspherical particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *full* | molecular + charge | bio-molecules |
+--------------+-----------------------------------------------------+--------------------------------------+
| *line* | end points, angular velocity | rigid bodies |
+--------------+-----------------------------------------------------+--------------------------------------+
| *meso* | rho, e, cv | SPH particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *molecular* | bonds, angles, dihedrals, impropers | uncharged molecules |
+--------------+-----------------------------------------------------+--------------------------------------+
| *peri* | mass, volume | mesocopic Peridynamic models |
+--------------+-----------------------------------------------------+--------------------------------------+
| *smd* | volume, kernel diameter, contact radius, mass | solid and fluid SPH particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *sphere* | diameter, mass, angular velocity | granular models |
+--------------+-----------------------------------------------------+--------------------------------------+
| *template* | template index, template atom | small molecules with fixed topology |
+--------------+-----------------------------------------------------+--------------------------------------+
| *tri* | corner points, angular momentum | rigid bodies |
+--------------+-----------------------------------------------------+--------------------------------------+
| *wavepacket* | charge, spin, eradius, etag, cs_re, cs_im | AWPMD |
+--------------+-----------------------------------------------------+--------------------------------------+
.. 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.
All of the above styles define point particles, except the *sphere*,
*ellipsoid*, *electron*, *peri*, *wavepacket*, *line*, *tri*, and
*body* styles, which define finite-size particles. See :ref:`Section_howto 14 <howto_14>` for an overview of using finite-size
particle models with LAMMPS.
All of the point-particle styles assign mass to particles on a
per-type basis, using the :doc:`mass <mass>` command, The finite-size
particle styles assign mass to individual particles on a per-particle
basis.
For the *sphere* style, the particles are spheres and each stores a
per-particle diameter and mass. If the diameter > 0.0, the particle
is a finite-size sphere. If the diameter = 0.0, it is a point
particle.
For the *ellipsoid* style, the particles are ellipsoids and each
stores a flag which indicates whether it is a finite-size ellipsoid or
a point particle. If it is an ellipsoid, it also stores a shape
vector with the 3 diamters of the ellipsoid and a quaternion 4-vector
with its orientation.
For the *dipole* style, a point dipole is defined for each point
particle. Note that if you wish the particles to be finite-size
spheres as in a Stockmayer potential for a dipolar fluid, so that the
particles can rotate due to dipole-dipole interactions, then you need
to use atom_style hybrid sphere dipole, which will assign both a
diameter and dipole moment to each particle.
For the *electron* style, the particles representing electrons are 3d
Gaussians with a specified position and bandwidth or uncertainty in
position, which is represented by the eradius = electron size.
For the *peri* style, the particles are spherical and each stores a
per-particle mass and volume.
The *meso* style is for smoothed particle hydrodynamics (SPH)
particles which store a density (rho), energy (e), and heat capacity
(cv).
The *smd* style is for a general formulation of Smooth Particle
Hydrodynamics. Both fluids and solids can be modeled. Particles
store the mass and volume of an integration point, a kernel diameter
used for calculating the field variables (e.g. stress and deformation)
and a contact radius for calculating repulsive forces which prevent
individual physical bodies from penetretating each other.
The *wavepacket* style is similar to *electron*, but the electrons may
consist of several Gaussian wave packets, summed up with coefficients
cs= (cs_re,cs_im). Each of the wave packets is treated as a separate
particle in LAMMPS, wave packets belonging to the same electron must
have identical *etag* values.
For the *line* style, the particles are idealized line segments and
each stores a per-particle mass and length and orientation (i.e. the
end points of the line segment).
For the *tri* style, the particles are planar triangles and each
stores a per-particle mass and size and orientation (i.e. the corner
points of the triangle).
The *template* style allows molecular topolgy (bonds,angles,etc) to be
defined via a molecule template using the `molecule <molecule.txt>`_
command. The template stores one or more molecules with a single copy
of the topology info (bonds,angles,etc) of each. Individual atoms
only store a template index and template atom to identify which
molecule and which atom-within-the-molecule they represent. Using the
*template* style instead of the *bond*, *angle*, *molecular* styles
can save memory for systems comprised of a large number of small
molecules, all of a single type (or small number of types). See the
paper by Grime and Voth, in :ref:`(Grime) <Grime>`, for examples of how this
can be advantageous for large-scale coarse-grained systems.
.. note::
When using the *template* style with a :doc:`molecule template <molecule>` that contains multiple molecules, you should
insure the atom types, bond types, angle_types, etc in all the
molecules are consistent. E.g. if one molecule represents H2O and
another CO2, then you probably do not want each molecule file to
define 2 atom types and a single bond type, because they will conflict
with each other when a mixture system of H2O and CO2 molecules is
defined, e.g. by the :doc:`read_data <read_data>` command. Rather the
H2O molecule should define atom types 1 and 2, and bond type 1. And
the CO2 molecule should define atom types 3 and 4 (or atom types 3 and
2 if a single oxygen type is desired), and bond type 2.
For the *body* style, the particles are arbitrary bodies with internal
attributes defined by the "style" of the bodies, which is specified by
the *bstyle* argument. Body particles can represent complex entities,
such as surface meshes of discrete points, collections of
sub-particles, deformable objects, etc.
The :doc:`body <body>` doc page descibes the body styles LAMMPS
currently supports, and provides more details as to the kind of body
particles they represent. For all styles, each body particle stores
moments of inertia and a quaternion 4-vector, so that its orientation
and position can be time integrated due to forces and torques.
Note that there may be additional arguments required along with the
*bstyle* specification, in the atom_style body command. These
arguments are described in the :doc:`body <body>` doc page.
----------
Typically, simulations require only a single (non-hybrid) atom style.
If some atoms in the simulation do not have all the properties defined
by a particular style, use the simplest style that defines all the
needed properties by any atom. For example, if some atoms in a
simulation are charged, but others are not, use the *charge* style.
If some atoms have bonds, but others do not, use the *bond* style.
The only scenario where the *hybrid* style is needed is if there is no
single style which defines all needed properties of all atoms. For
example, as mentioned above, if you want dipolar particles which will
rotate due to torque, you need to use "atom_style hybrid sphere
dipole". When a hybrid style is used, atoms store and communicate the
union of all quantities implied by the individual styles.
When using the *hybrid* style, you cannot combine the *template* style
with another molecular style that stores bond,angle,etc info on a
per-atom basis.
LAMMPS can be extended with new atom styles as well as new body
styles; see :doc:`this section <Section_modify>`.
----------
Styles with a *cuda* or *kk* suffix are functionally the same as the
corresponding style without the suffix. They have been optimized to
run faster, depending on your available hardware, as discussed in
:doc:`Section_accelerate <Section_accelerate>` of the manual. The
accelerated styles take the same arguments and should produce the same
results, except for round-off and precision issues.
Note that other acceleration packages in LAMMPS, specifically the GPU,
USER-INTEL, USER-OMP, and OPT packages do not use accelerated atom
styles.
The accelerated styles are part of the USER-CUDA and KOKKOS packages
respectively. They are only enabled if LAMMPS was built with those
packages. See the :ref:`Making LAMMPS <start_3>` section
for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
Restrictions
""""""""""""
This command cannot be used after the simulation box is defined by a
:doc:`read_data <read_data>` or :doc:`create_box <create_box>` command.
The *angle*, *bond*, *full*, *molecular*, and *template* styles are
part of the MOLECULE package. The *line* and *tri* styles are part
of the ASPHERE pacakge. The *body* style is part of the BODY package.
The *dipole* style is part of the DIPOLE package. The *peri* style is
part of the PERI package for Peridynamics. The *electron* style is
part of the USER-EFF package for :doc:`electronic force fields <pair_eff>`. The *meso* style is part of the USER-SPH
package for smoothed particle hydrodyanmics (SPH). See `this PDF guide <USER/sph/SPH_LAMMPS_userguide.pdf>`_ to using SPH in LAMMPS. The
*wavepacket* style is part of the USER-AWPMD package for the
:doc:`antisymmetrized wave packet MD method <pair_awpmd>`. They are
only enabled if LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
Related commands
""""""""""""""""
:doc:`read_data <read_data>`, :doc:`pair_style <pair_style>`
Default
"""""""
atom_style atomic
----------
.. _Grime:
**(Grime)** Grime and Voth, to appear in J Chem Theory & Computation
(2014).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

386
doc/_sources/balance.txt Normal file
View File

@ -0,0 +1,386 @@
.. index:: balance
balance command
===============
Syntax
""""""
.. parsed-literal::
balance thresh style args ... keyword value ...
* thresh = imbalance threshhold that must be exceeded to perform a re-balance
* one style/arg pair can be used (or multiple for *x*,*y*,*z*)
* style = *x* or *y* or *z* or *shift* or *rcb*
.. parsed-literal::
*x* args = *uniform* or Px-1 numbers between 0 and 1
*uniform* = evenly spaced cuts between processors in x dimension
numbers = Px-1 ascending values between 0 and 1, Px - # of processors in x dimension
*x* can be specified together with *y* or *z*
*y* args = *uniform* or Py-1 numbers between 0 and 1
*uniform* = evenly spaced cuts between processors in y dimension
numbers = Py-1 ascending values between 0 and 1, Py - # of processors in y dimension
*y* can be specified together with *x* or *z*
*z* args = *uniform* or Pz-1 numbers between 0 and 1
*uniform* = evenly spaced cuts between processors in z dimension
numbers = Pz-1 ascending values between 0 and 1, Pz - # of processors in z dimension
*z* can be specified together with *x* or *y*
*shift* args = dimstr Niter stopthresh
dimstr = sequence of letters containing "x" or "y" or "z", each not more than once
Niter = # of times to iterate within each dimension of dimstr sequence
stopthresh = stop balancing when this imbalance threshhold is reached
*rcb* args = none
* zero or more keyword/value pairs may be appended
* keyword = *out*
.. parsed-literal::
*out* value = filename
filename = write each processor's sub-domain to a file
Examples
""""""""
.. parsed-literal::
balance 0.9 x uniform y 0.4 0.5 0.6
balance 1.2 shift xz 5 1.1
balance 1.0 shift xz 5 1.1
balance 1.1 rcb
balance 1.0 shift x 20 1.0 out tmp.balance
Description
"""""""""""
This command adjusts the size and shape of processor sub-domains
within the simulation box, to attempt to balance the number of
particles and thus the computational cost (load) evenly across
processors. The load balancing is "static" in the sense that this
command performs the balancing once, before or between simulations.
The processor sub-domains will then remain static during the
subsequent run. To perform "dynamic" balancing, see the :doc:`fix balance <fix_balance>` command, which can adjust processor
sub-domain sizes and shapes on-the-fly during a :doc:`run <run>`.
Load-balancing is typically only useful if the particles in the
simulation box have a spatially-varying density distribution. E.g. a
model of a vapor/liquid interface, or a solid with an irregular-shaped
geometry containing void regions. In this case, the LAMMPS default of
dividing the simulation box volume into a regular-spaced grid of 3d
bricks, with one equal-volume sub-domain per procesor, may assign very
different numbers of particles per processor. This can lead to poor
performance when the simulation is run in parallel.
Note that the :doc:`processors <processors>` command allows some control
over how the box volume is split across processors. Specifically, for
a Px by Py by Pz grid of processors, it allows choice of Px, Py, and
Pz, subject to the constraint that Px * Py * Pz = P, the total number
of processors. This is sufficient to achieve good load-balance for
some problems on some processor counts. However, all the processor
sub-domains will still have the same shape and same volume.
The requested load-balancing operation is only performed if the
current "imbalance factor" in particles owned by each processor
exceeds the specified *thresh* parameter. The imbalance factor is
defined as the maximum number of particles owned by any processor,
divided by the average number of particles per processor. Thus an
imbalance factor of 1.0 is perfect balance.
As an example, for 10000 particles running on 10 processors, if the
most heavily loaded processor has 1200 particles, then the factor is
1.2, meaning there is a 20% imbalance. Note that a re-balance can be
forced even if the current balance is perfect (1.0) be specifying a
*thresh* < 1.0.
.. note::
Balancing is performed even if the imbalance factor does not
exceed the *thresh* parameter if a "grid" style is specified when the
current partitioning is "tiled". The meaning of "grid" vs "tiled" is
explained below. This is to allow forcing of the partitioning to
"grid" so that the :doc:`comm_style brick <comm_style>` command can then
be used to replace a current :doc:`comm_style tiled <comm_style>`
setting.
When the balance command completes, it prints statistics about the
result, including the change in the imbalance factor and the change in
the maximum number of particles on any processor. For "grid" methods
(defined below) that create a logical 3d grid of processors, the
positions of all cutting planes in each of the 3 dimensions (as
fractions of the box length) are also printed.
.. note::
This command attempts to minimize the imbalance factor, as
defined above. But depending on the method a perfect balance (1.0)
may not be achieved. For example, "grid" methods (defined below) that
create a logical 3d grid cannot achieve perfect balance for many
irregular distributions of particles. Likewise, if a portion of the
system is a perfect lattice, e.g. the intiial system is generated by
the :doc:`create_atoms <create_atoms>` command, then "grid" methods may
be unable to achieve exact balance. This is because entire lattice
planes will be owned or not owned by a single processor.
.. note::
The imbalance factor is also an estimate of the maximum speed-up
you can hope to achieve by running a perfectly balanced simulation
versus an imbalanced one. In the example above, the 10000 particle
simulation could run up to 20% faster if it were perfectly balanced,
versus when imbalanced. However, computational cost is not strictly
proportional to particle count, and changing the relative size and
shape of processor sub-domains may lead to additional computational
and communication overheads, e.g. in the PPPM solver used via the
:doc:`kspace_style <kspace_style>` command. Thus you should benchmark
the run times of a simulation before and after balancing.
----------
The method used to perform a load balance is specified by one of the
listed styles (or more in the case of *x*,*y*,*z*), which are
described in detail below. There are 2 kinds of styles.
The *x*, *y*, *z*, and *shift* styles are "grid" methods which produce
a logical 3d grid of processors. They operate by changing the cutting
planes (or lines) between processors in 3d (or 2d), to adjust the
volume (area in 2d) assigned to each processor, as in the following 2d
diagram where processor sub-domains are shown and atoms are colored by
the processor that owns them. The leftmost diagram is the default
partitioning of the simulation box across processors (one sub-box for
each of 16 processors); the middle diagram is after a "grid" method
has been applied.
.. thumbnail:: JPG/balance_uniform.jpg
:align: center
.. thumbnail:: JPG/balance_nonuniform.jpg
:align: center
.. thumbnail:: JPG/balance_rcb.jpg
:align: center
The *rcb* style is a "tiling" method which does not produce a logical
3d grid of processors. Rather it tiles the simulation domain with
rectangular sub-boxes of varying size and shape in an irregular
fashion so as to have equal numbers of particles in each sub-box, as
in the rightmost diagram above.
The "grid" methods can be used with either of the
:doc:`comm_style <comm_style>` command options, *brick* or *tiled*. The
"tiling" methods can only be used with :doc:`comm_style tiled <comm_style>`. Note that it can be useful to use a "grid"
method with :doc:`comm_style tiled <comm_style>` to return the domain
partitioning to a logical 3d grid of processors so that "comm_style
brick" can afterwords be specified for subsequent :doc:`run <run>`
commands.
When a "grid" method is specified, the current domain partitioning can
be either a logical 3d grid or a tiled partitioning. In the former
case, the current logical 3d grid is used as a starting point and
changes are made to improve the imbalance factor. In the latter case,
the tiled partitioning is discarded and a logical 3d grid is created
with uniform spacing in all dimensions. This becomes the starting
point for the balancing operation.
When a "tiling" method is specified, the current domain partitioning
("grid" or "tiled") is ignored, and a new partitioning is computed
from scratch.
----------
The *x*, *y*, and *z* styles invoke a "grid" method for balancing, as
described above. Note that any or all of these 3 styles can be
specified together, one after the other, but they cannot be used with
any other style. This style adjusts the position of cutting planes
between processor sub-domains in specific dimensions. Only the
specified dimensions are altered.
The *uniform* argument spaces the planes evenly, as in the left
diagrams above. The *numeric* argument requires listing Ps-1 numbers
that specify the position of the cutting planes. This requires
knowing Ps = Px or Py or Pz = the number of processors assigned by
LAMMPS to the relevant dimension. This assignment is made (and the
Px, Py, Pz values printed out) when the simulation box is created by
the "create_box" or "read_data" or "read_restart" command and is
influenced by the settings of the :doc:`processors <processors>`
command.
Each of the numeric values must be between 0 and 1, and they must be
listed in ascending order. They represent the fractional position of
the cutting place. The left (or lower) edge of the box is 0.0, and
the right (or upper) edge is 1.0. Neither of these values is
specified. Only the interior Ps-1 positions are specified. Thus is
there are 2 procesors in the x dimension, you specify a single value
such as 0.75, which would make the left processor's sub-domain 3x
larger than the right processor's sub-domain.
----------
The *shift* style invokes a "grid" method for balancing, as
described above. It changes the positions of cutting planes between
processors in an iterative fashion, seeking to reduce the imbalance
factor, similar to how the :doc:`fix balance shift <fix_balance>`
command operates.
The *dimstr* argument is a string of characters, each of which must be
an "x" or "y" or "z". Eacn character can appear zero or one time,
since there is no advantage to balancing on a dimension more than
once. You should normally only list dimensions where you expect there
to be a density variation in the particles.
Balancing proceeds by adjusting the cutting planes in each of the
dimensions listed in *dimstr*, one dimension at a time. For a single
dimension, the balancing operation (described below) is iterated on up
to *Niter* times. After each dimension finishes, the imbalance factor
is re-computed, and the balancing operation halts if the *stopthresh*
criterion is met.
A rebalance operation in a single dimension is performed using a
recursive multisectioning algorithm, where the position of each
cutting plane (line in 2d) in the dimension is adjusted independently.
This is similar to a recursive bisectioning for a single value, except
that the bounds used for each bisectioning take advantage of
information from neighboring cuts if possible. At each iteration, the
count of particles on either side of each plane is tallied. If the
counts do not match the target value for the plane, the position of
the cut is adjusted to be halfway between a low and high bound. The
low and high bounds are adjusted on each iteration, using new count
information, so that they become closer together over time. Thus as
the recustion progresses, the count of particles on either side of the
plane gets closer to the target value.
Once the rebalancing is complete and final processor sub-domains
assigned, particles are migrated to their new owning processor, and
the balance procedure ends.
.. note::
At each rebalance operation, the bisectioning for each cutting
plane (line in 2d) typcially starts with low and high bounds separated
by the extent of a processor's sub-domain in one dimension. The size
of this bracketing region shrinks by 1/2 every iteration. Thus if
*Niter* is specified as 10, the cutting plane will typically be
positioned to 1 part in 1000 accuracy (relative to the perfect target
position). For *Niter* = 20, it will be accurate to 1 part in a
million. Thus there is no need ot set *Niter* to a large value.
LAMMPS will check if the threshold accuracy is reached (in a
dimension) is less iterations than *Niter* and exit early. However,
*Niter* should also not be set too small, since it will take roughly
the same number of iterations to converge even if the cutting plane is
initially close to the target value.
----------
The *rcb* style invokes a "tiled" method for balancing, as described
above. It performs a recursive coordinate bisectioning (RCB) of the
simulation domain. The basic idea is as follows.
The simulation domain is cut into 2 boxes by an axis-aligned cut in
the longest dimension, leaving one new box on either side of the cut.
All the processors are also partitioned into 2 groups, half assigned
to the box on the lower side of the cut, and half to the box on the
upper side. (If the processor count is odd, one side gets an extra
processor.) The cut is positioned so that the number of atoms in the
lower box is exactly the number that the processors assigned to that
box should own for load balance to be perfect. This also makes load
balance for the upper box perfect. The positioning is done
iteratively, by a bisectioning method. Note that counting atoms on
either side of the cut requires communication between all processors
at each iteration.
That is the procedure for the first cut. Subsequent cuts are made
recursively, in exactly the same manner. The subset of processors
assigned to each box make a new cut in the longest dimension of that
box, splitting the box, the subset of processsors, and the atoms in
the box in two. The recursion continues until every processor is
assigned a sub-box of the entire simulation domain, and owns the atoms
in that sub-box.
----------
The *out* keyword writes a text file to the specified *filename* with
the results of the balancing operation. The file contains the bounds
of the sub-domain for each processor after the balancing operation
completes. The format of the file is compatible with the
`Pizza.py <pizza>`_ *mdump* tool which has support for manipulating and
visualizing mesh files. An example is shown here for a balancing by 4
processors for a 2d problem:
.. parsed-literal::
ITEM: TIMESTEP
0
ITEM: NUMBER OF NODES
16
ITEM: BOX BOUNDS
0 10
0 10
0 10
ITEM: NODES
1 1 0 0 0
2 1 5 0 0
3 1 5 5 0
4 1 0 5 0
5 1 5 0 0
6 1 10 0 0
7 1 10 5 0
8 1 5 5 0
9 1 0 5 0
10 1 5 5 0
11 1 5 10 0
12 1 10 5 0
13 1 5 5 0
14 1 10 5 0
15 1 10 10 0
16 1 5 10 0
ITEM: TIMESTEP
0
ITEM: NUMBER OF SQUARES
4
ITEM: SQUARES
1 1 1 2 3 4
2 1 5 6 7 8
3 1 9 10 11 12
4 1 13 14 15 16
The coordinates of all the vertices are listed in the NODES section, 5
per processor. Note that the 4 sub-domains share vertices, so there
will be duplicate nodes in the list.
The "SQUARES" section lists the node IDs of the 4 vertices in a
rectangle for each processor (1 to 4).
For a 3d problem, the syntax is similar with 8 vertices listed for
each processor, instead of 4, and "SQUARES" replaced by "CUBES".
----------
Restrictions
""""""""""""
For 2d simulations, the *z* style cannot be used. Nor can a "z"
appear in *dimstr* for the *shift* style.
Related commands
""""""""""""""""
:doc:`processors <processors>`, :doc:`fix balance <fix_balance>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

301
doc/_sources/body.txt Normal file
View File

@ -0,0 +1,301 @@
Body particles
==============
**Overview:**
This doc page is not about a LAMMPS input script command, but about
body particles, which 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 :ref:`Section_howto 14 <howto_14>` 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 convex polygon with N vertices |
+-------------------+-----------------------------------+
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.
.. note::
The rounded/polygon style listed in the table above and
described below has not yet been relesed in LAMMPS. It will be soon.
We hope to add more styles in the future. See :ref:`Section_modify 12 <mod_12>` 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, outputting 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, if particles have 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
then the interaction between pairs of particles is likely to be more
complex than the summation of simple sub-particle interactions. An
example is contact or frictional forces between particles with planar
sufaces that inter-penetrate.
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
vanillia, 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
N is the number of sub-particles in the body particle. M = 6 + 3*N.
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 prinicpal 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 <pair_body>` 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 convex
polygon with a variable number N > 2 of vertices, which can only be
used for 2d models. One example use of this body style is for 2d
discrete element models, as described in :ref:`Fraige <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 ...
radius
N is the number of vertices in the body particle. M = 6 + 3*N + 2*N +
1. 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, followed by 2N vertex indices
corresponding to the end points of the N edges, followed by a single
radius value = the smallest circle encompassing the polygon. That
last value is used to facilitate the body/body contact detection.
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 prinicpal 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
particles whose edge length is sqrt(2):
.. 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
The :doc:`pair_style body/rounded/polygon <pair_body_rounded_polygon>` command
can be used with this body style to compute body/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 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 convex
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 `pair_style rounded/polygon <pair_body_rounded_polygon.cpp>`_ 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.
----------
.. _Fraige:
**(Fraige)** F. Y. Fraige, P. A. Langston, A. J. Matchett, J. Dodds,
Particuology, 6, 455 (2008).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

101
doc/_sources/bond_class2.txt Normal file
View File

@ -0,0 +1,101 @@
.. index:: bond_style class2
bond_style class2 command
=========================
bond_style class2/omp command
=============================
Syntax
""""""
.. parsed-literal::
bond_style class2
Examples
""""""""
.. parsed-literal::
bond_style class2
bond_coeff 1 1.0 100.0 80.0 80.0
Description
"""""""""""
The *class2* bond style uses the potential
.. image:: Eqs/bond_class2.jpg
:align: center
where r0 is the equilibrium bond distance.
See :ref:`(Sun) <Sun>` for a description of the COMPASS class2 force field.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* R0 (distance)
* K2 (energy/distance^2)
* K3 (energy/distance^3)
* K4 (energy/distance^4)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the CLASS2
package. See the :ref:`Making LAMMPS <start_3>` section
for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
----------
.. _Sun:
**(Sun)** Sun, J Phys Chem B 102, 7338-7364 (1998).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

112
doc/_sources/bond_coeff.txt Normal file
View File

@ -0,0 +1,112 @@
.. index:: bond_coeff
bond_coeff command
==================
Syntax
""""""
.. parsed-literal::
bond_coeff N args
* N = bond type (see asterisk form below)
* args = coefficients for one or more bond types
Examples
""""""""
.. parsed-literal::
bond_coeff 5 80.0 1.2
bond_coeff * 30.0 1.5 1.0 1.0
bond_coeff 1*4 30.0 1.5 1.0 1.0
bond_coeff 1 harmonic 200.0 1.0
Description
"""""""""""
Specify the bond force field coefficients for one or more bond types.
The number and meaning of the coefficients depends on the bond style.
Bond coefficients can also be set in the data file read by the
:doc:`read_data <read_data>` command or in a restart file.
N can be specified in one of two ways. An explicit numeric value can
be used, as in the 1st example above. Or a wild-card asterisk can be
used to set the coefficients for multiple bond types. This takes the
form "*" or "*n" or "n*" or "m*n". If N = the number of bond types,
then an asterisk with no numeric values means all types from 1 to N. A
leading asterisk means all types from 1 to n (inclusive). A trailing
asterisk means all types from n to N (inclusive). A middle asterisk
means all types from m to n (inclusive).
Note that using a bond_coeff command can override a previous setting
for the same bond type. For example, these commands set the coeffs
for all bond types, then overwrite the coeffs for just bond type 2:
.. parsed-literal::
bond_coeff * 100.0 1.2
bond_coeff 2 200.0 1.2
A line in a data file that specifies bond coefficients uses the exact
same format as the arguments of the bond_coeff command in an input
script, except that wild-card asterisks should not be used since
coefficients for all N types must be listed in the file. For example,
under the "Bond Coeffs" section of a data file, the line that
corresponds to the 1st example above would be listed as
.. parsed-literal::
5 80.0 1.2
----------
Here is an alphabetic list of bond styles defined in LAMMPS. Click on
the style to display the formula it computes and coefficients
specified by the associated :doc:`bond_coeff <bond_coeff>` command.
Note that here are also additional bond styles submitted by users
which are included in the LAMMPS distribution. The list of these with
links to the individual styles are given in the bond section of :ref:`this page <cmd_5>`.
* :doc:`bond_style none <bond_none>` - turn off bonded interactions
* :doc:`bond_style hybrid <bond_hybrid>` - define multiple styles of bond interactions
* :doc:`bond_style class2 <bond_class2>` - COMPASS (class 2) bond
* :doc:`bond_style fene <bond_fene>` - FENE (finite-extensible non-linear elastic) bond
* :doc:`bond_style fene/expand <bond_fene_expand>` - FENE bonds with variable size particles
* :doc:`bond_style harmonic <bond_harmonic>` - harmonic bond
* :doc:`bond_style morse <bond_morse>` - Morse bond
* :doc:`bond_style nonlinear <bond_nonlinear>` - nonlinear bond
* :doc:`bond_style quartic <bond_quartic>` - breakable quartic bond
* :doc:`bond_style table <bond_table>` - tabulated by bond length
----------
Restrictions
""""""""""""
This command must come after the simulation box is defined by a
:doc:`read_data <read_data>`, :doc:`read_restart <read_restart>`, or
:doc:`create_box <create_box>` command.
A bond style must be defined before any bond coefficients are set,
either in the input script or in a data file.
Related commands
""""""""""""""""
:doc:`bond_style <bond_style>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

109
doc/_sources/bond_fene.txt Normal file
View File

@ -0,0 +1,109 @@
.. index:: bond_style fene
bond_style fene command
=======================
bond_style fene/kk command
==========================
bond_style fene/omp command
===========================
Syntax
""""""
.. parsed-literal::
bond_style fene
Examples
""""""""
.. parsed-literal::
bond_style fene
bond_coeff 1 30.0 1.5 1.0 1.0
Description
"""""""""""
The *fene* bond style uses the potential
.. image:: Eqs/bond_fene.jpg
:align: center
to define a finite extensible nonlinear elastic (FENE) potential
:ref:`(Kremer) <Kremer>`, used for bead-spring polymer models. The first
term is attractive, the 2nd Lennard-Jones term is repulsive. The
first term extends to R0, the maximum extent of the bond. The 2nd
term is cutoff at 2^(1/6) sigma, the minimum of the LJ potential.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy/distance^2)
* R0 (distance)
* epsilon (energy)
* sigma (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
You typically should specify `special_bonds fene <special_bonds.html">`_
or :doc:`special_bonds lj/coul 0 1 1 <special_bonds>` to use this bond
style. LAMMPS will issue a warning it that's not the case.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
----------
.. _Kremer:
**(Kremer)** Kremer, Grest, J Chem Phys, 92, 5057 (1990).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

111
doc/_sources/bond_fene_expand.txt Normal file
View File

@ -0,0 +1,111 @@
.. index:: bond_style fene/expand
bond_style fene/expand command
==============================
bond_style fene/expand/omp command
==================================
Syntax
""""""
.. parsed-literal::
bond_style fene/expand
Examples
""""""""
.. parsed-literal::
bond_style fene/expand
bond_coeff 1 30.0 1.5 1.0 1.0 0.5
Description
"""""""""""
The *fene/expand* bond style uses the potential
.. image:: Eqs/bond_fene_expand.jpg
:align: center
to define a finite extensible nonlinear elastic (FENE) potential
:ref:`(Kremer) <Kremer>`, used for bead-spring polymer models. The first
term is attractive, the 2nd Lennard-Jones term is repulsive.
The *fene/expand* bond style is similar to *fene* except that an extra
shift factor of delta (positive or negative) is added to *r* to
effectively change the bead size of the bonded atoms. The first term
now extends to R0 + delta and the 2nd term is cutoff at 2^(1/6) sigma
+ delta.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy/distance^2)
* R0 (distance)
* epsilon (energy)
* sigma (distance)
* delta (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
You typically should specify `special_bonds fene <special_bonds.html">`_
or :doc:`special_bonds lj/coul 0 1 1 <special_bonds>` to use this bond
style. LAMMPS will issue a warning it that's not the case.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
----------
.. _Kremer:
**(Kremer)** Kremer, Grest, J Chem Phys, 92, 5057 (1990).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

93
doc/_sources/bond_harmonic.txt Normal file
View File

@ -0,0 +1,93 @@
.. index:: bond_style harmonic
bond_style harmonic command
===========================
bond_style harmonic/intel command
=================================
bond_style harmonic/kk command
==============================
bond_style harmonic/omp command
===============================
Syntax
""""""
.. parsed-literal::
bond_style harmonic
Examples
""""""""
.. parsed-literal::
bond_style harmonic
bond_coeff 5 80.0 1.2
Description
"""""""""""
The *harmonic* bond style uses the potential
.. image:: Eqs/bond_harmonic.jpg
:align: center
where r0 is the equilibrium bond distance. Note that the usual 1/2
factor is included in K.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy/distance^2)
* r0 (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

94
doc/_sources/bond_harmonic_shift.txt Normal file
View File

@ -0,0 +1,94 @@
.. index:: bond_style harmonic/shift
bond_style harmonic/shift command
=================================
bond_style harmonic/shift/omp command
=====================================
Syntax
""""""
.. parsed-literal::
bond_style harmonic/shift
Examples
""""""""
.. parsed-literal::
bond_style harmonic/shift
bond_coeff 5 10.0 0.5 1.0
Description
"""""""""""
The *harmonic/shift* bond style is a shifted harmonic bond that uses
the potential
.. image:: Eqs/bond_harmonic_shift.jpg
:align: center
where r0 is the equilibrium bond distance, and rc the critical distance.
The potential is -Umin at r0 and zero at rc. The spring constant is
k = Umin / [ 2 (r0-rc)^2].
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* Umin (energy)
* r0 (distance)
* rc (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
USER-MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`,
:doc:`bond_harmonic <bond_harmonic>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

93
doc/_sources/bond_harmonic_shift_cut.txt Normal file
View File

@ -0,0 +1,93 @@
.. index:: bond_style harmonic/shift/cut
bond_style harmonic/shift/cut command
=====================================
bond_style harmonic/shift/cut/omp command
=========================================
Syntax
""""""
.. parsed-literal::
bond_style harmonic/shift/cut
Examples
""""""""
.. parsed-literal::
bond_style harmonic/shift/cut
bond_coeff 5 10.0 0.5 1.0
Description
"""""""""""
The *harmonic/shift/cut* bond style is a shifted harmonic bond that
uses the potential
.. image:: Eqs/bond_harmonic_shift_cut.jpg
:align: center
where r0 is the equilibrium bond distance, and rc the critical distance.
The bond potential is zero for distances r > rc. The potential is -Umin
at r0 and zero at rc. The spring constant is k = Umin / [ 2 (r0-rc)^2].
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* Umin (energy)
* r0 (distance)
* rc (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
USER-MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`,
:doc:`bond_harmonic <bond_harmonic>`,
:doc:`bond_harmonicshift <bond_harmonicshift>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

88
doc/_sources/bond_hybrid.txt Normal file
View File

@ -0,0 +1,88 @@
.. index:: bond_style hybrid
bond_style hybrid command
=========================
Syntax
""""""
.. parsed-literal::
bond_style hybrid style1 style2 ...
* style1,style2 = list of one or more bond styles
Examples
""""""""
.. parsed-literal::
bond_style hybrid harmonic fene
bond_coeff 1 harmonic 80.0 1.2
bond_coeff 2* fene 30.0 1.5 1.0 1.0
Description
"""""""""""
The *hybrid* style enables the use of multiple bond styles in one
simulation. A bond style is assigned to each bond type. For example,
bonds in a polymer flow (of bond type 1) could be computed with a
*fene* potential and bonds in the wall boundary (of bond type 2) could
be computed with a *harmonic* potential. The assignment of bond type
to style is made via the :doc:`bond_coeff <bond_coeff>` command or in
the data file.
In the bond_coeff commands, the name of a bond style must be added
after the bond type, with the remaining coefficients being those
appropriate to that style. In the example above, the 2 bond_coeff
commands set bonds of bond type 1 to be computed with a *harmonic*
potential with coefficients 80.0, 1.2 for K, r0. All other bond types
(2-N) are computed with a *fene* potential with coefficients 30.0,
1.5, 1.0, 1.0 for K, R0, epsilon, sigma.
If bond coefficients are specified in the data file read via the
:doc:`read_data <read_data>` command, then the same rule applies.
E.g. "harmonic" or "fene" must be added after the bond type, for each
line in the "Bond Coeffs" section, e.g.
.. parsed-literal::
Bond Coeffs
.. parsed-literal::
1 harmonic 80.0 1.2
2 fene 30.0 1.5 1.0 1.0
...
A bond style of *none* with no additional coefficients can be used in
place of a bond style, either in a input script bond_coeff command or
in the data file, if you desire to turn off interactions for specific
bond types.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Unlike other bond styles, the hybrid bond style does not store bond
coefficient info for individual sub-styles in a :doc:`binary restart files <restart>`. Thus when retarting a simulation from a restart
file, you need to re-specify bond_coeff commands.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

88
doc/_sources/bond_morse.txt Normal file
View File

@ -0,0 +1,88 @@
.. index:: bond_style morse
bond_style morse command
========================
bond_style morse/omp command
============================
Syntax
""""""
.. parsed-literal::
bond_style morse
Examples
""""""""
.. parsed-literal::
bond_style morse
bond_coeff 5 1.0 2.0 1.2
Description
"""""""""""
The *morse* bond style uses the potential
.. image:: Eqs/bond_morse.jpg
:align: center
where r0 is the equilibrium bond distance, alpha is a stiffness
parameter, and D determines the depth of the potential well.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* D (energy)
* alpha (inverse distance)
* r0 (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

38
doc/_sources/bond_none.txt Normal file
View File

@ -0,0 +1,38 @@
.. index:: bond_style none
bond_style none command
=======================
Syntax
""""""
.. parsed-literal::
bond_style none
Examples
""""""""
.. parsed-literal::
bond_style none
Description
"""""""""""
Using a bond style of none means bond forces are not computed, even if
pairs of bonded atoms were listed in the data file read by the
:doc:`read_data <read_data>` command.
Restrictions
""""""""""""
none
**Related commands:** none
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

98
doc/_sources/bond_nonlinear.txt Normal file
View File

@ -0,0 +1,98 @@
.. index:: bond_style nonlinear
bond_style nonlinear command
============================
bond_style nonlinear/omp command
================================
Syntax
""""""
.. parsed-literal::
bond_style nonlinear
Examples
""""""""
.. parsed-literal::
bond_style nonlinear
bond_coeff 2 100.0 1.1 1.4
Description
"""""""""""
The *nonlinear* bond style uses the potential
.. image:: Eqs/bond_nonlinear.jpg
:align: center
to define an anharmonic spring :ref:`(Rector) <Rector>` of equilibrium
length r0 and maximum extension lamda.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* epsilon (energy)
* r0 (distance)
* lamda (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
----------
.. _Rector:
**(Rector)** Rector, Van Swol, Henderson, Molecular Physics, 82, 1009 (1994).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

128
doc/_sources/bond_quartic.txt Normal file
View File

@ -0,0 +1,128 @@
.. index:: bond_style quartic
bond_style quartic command
==========================
bond_style quartic/omp command
==============================
Syntax
""""""
.. parsed-literal::
bond_style quartic
Examples
""""""""
.. parsed-literal::
bond_style quartic
bond_coeff 2 1200 -0.55 0.25 1.3 34.6878
Description
"""""""""""
The *quartic* bond style uses the potential
.. image:: Eqs/bond_quartic.jpg
:align: center
to define a bond that can be broken as the simulation proceeds (e.g.
due to a polymer being stretched). The sigma and epsilon used in the
LJ portion of the formula are both set equal to 1.0 by LAMMPS.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy/distance^4)
* B1 (distance)
* B2 (distance)
* Rc (distance)
* U0 (energy)
This potential was constructed to mimic the FENE bond potential for
coarse-grained polymer chains. When monomers with sigma = epsilon =
1.0 are used, the following choice of parameters gives a quartic
potential that looks nearly like the FENE potential: K = 1200, B1 =
-0.55, B2 = 0.25, Rc = 1.3, and U0 = 34.6878. Different parameters
can be specified using the :doc:`bond_coeff <bond_coeff>` command, but
you will need to choose them carefully so they form a suitable bond
potential.
Rc is the cutoff length at which the bond potential goes smoothly to a
local maximum. If a bond length ever becomes > Rc, LAMMPS "breaks"
the bond, which means two things. First, the bond potential is turned
off by setting its type to 0, and is no longer computed. Second, a
pairwise interaction between the two atoms is turned on, since they
are no longer bonded.
LAMMPS does the second task via a computational sleight-of-hand. It
subtracts the pairwise interaction as part of the bond computation.
When the bond breaks, the subtraction stops. For this to work, the
pairwise interaction must always be computed by the
:doc:`pair_style <pair_style>` command, whether the bond is broken or
not. This means that :doc:`special_bonds <special_bonds>` must be set
to 1,1,1, as indicated as a restriction below.
Note that when bonds are dumped to a file via the :doc:`dump local <dump>` command, bonds with type 0 are not included. The
:doc:`delete_bonds <delete_bonds>` command can also be used to query the
status of broken bonds or permanently delete them, e.g.:
.. parsed-literal::
delete_bonds all stats
delete_bonds all bond 0 remove
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
The *quartic* style requires that :doc:`special_bonds <special_bonds>`
parameters be set to 1,1,1. Three- and four-body interactions (angle,
dihedral, etc) cannot be used with *quartic* bonds.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

121
doc/_sources/bond_style.txt Normal file
View File

@ -0,0 +1,121 @@
.. index:: bond_style
bond_style command
==================
Syntax
""""""
.. parsed-literal::
bond_style style args
* style = *none* or *hybrid* or *class2* or *fene* or *fene/expand* or *harmonic* or *morse* or *nonlinear* or *quartic*
.. parsed-literal::
args = none for any style except *hybrid*
*hybrid* args = list of one or more styles
Examples
""""""""
.. parsed-literal::
bond_style harmonic
bond_style fene
bond_style hybrid harmonic fene
Description
"""""""""""
Set the formula(s) LAMMPS uses to compute bond interactions between
pairs of atoms. In LAMMPS, a bond differs from a pairwise
interaction, which are set via the :doc:`pair_style <pair_style>`
command. Bonds are defined between specified pairs of atoms and
remain in force for the duration of the simulation (unless the bond
breaks which is possible in some bond potentials). The list of bonded
atoms is read in by a :doc:`read_data <read_data>` or
:doc:`read_restart <read_restart>` command from a data or restart file.
By contrast, pair potentials are typically defined between all pairs
of atoms within a cutoff distance and the set of active interactions
changes over time.
Hybrid models where bonds are computed using different bond potentials
can be setup using the *hybrid* bond style.
The coefficients associated with a bond style can be specified in a
data or restart file or via the :doc:`bond_coeff <bond_coeff>` command.
All bond potentials store their coefficient data in binary restart
files which means bond_style and :doc:`bond_coeff <bond_coeff>` commands
do not need to be re-specified in an input script that restarts a
simulation. See the :doc:`read_restart <read_restart>` command for
details on how to do this. The one exception is that bond_style
*hybrid* only stores the list of sub-styles in the restart file; bond
coefficients need to be re-specified.
.. note::
When both a bond and pair style is defined, the
:doc:`special_bonds <special_bonds>` command often needs to be used to
turn off (or weight) the pairwise interaction that would otherwise
exist between 2 bonded atoms.
In the formulas listed for each bond style, *r* is the distance
between the 2 atoms in the bond.
----------
Here is an alphabetic list of bond styles defined in LAMMPS. Click on
the style to display the formula it computes and coefficients
specified by the associated :doc:`bond_coeff <bond_coeff>` command.
Note that there are also additional bond styles submitted by users
which are included in the LAMMPS distribution. The list of these with
links to the individual styles are given in the bond section of :ref:`this page <cmd_5>`.
* :doc:`bond_style none <bond_none>` - turn off bonded interactions
* :doc:`bond_style hybrid <bond_hybrid>` - define multiple styles of bond interactions
* :doc:`bond_style class2 <bond_class2>` - COMPASS (class 2) bond
* :doc:`bond_style fene <bond_fene>` - FENE (finite-extensible non-linear elastic) bond
* :doc:`bond_style fene/expand <bond_fene_expand>` - FENE bonds with variable size particles
* :doc:`bond_style harmonic <bond_harmonic>` - harmonic bond
* :doc:`bond_style morse <bond_morse>` - Morse bond
* :doc:`bond_style nonlinear <bond_nonlinear>` - nonlinear bond
* :doc:`bond_style quartic <bond_quartic>` - breakable quartic bond
* :doc:`bond_style table <bond_table>` - tabulated by bond length
----------
Restrictions
""""""""""""
Bond styles can only be set for atom styles that allow bonds to be
defined.
Most bond styles are part of the MOLECULE package. They are only
enabled if LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
The doc pages for individual bond potentials tell if it is part of a
package.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
Default
"""""""
bond_style none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

172
doc/_sources/bond_table.txt Normal file
View File

@ -0,0 +1,172 @@
.. index:: bond_style table
bond_style table command
========================
bond_style table/omp command
============================
Syntax
""""""
.. parsed-literal::
bond_style table style N
* style = *linear* or *spline* = method of interpolation
* N = use N values in table
Examples
""""""""
.. parsed-literal::
bond_style table linear 1000
bond_coeff 1 file.table ENTRY1
Description
"""""""""""
Style *table* creates interpolation tables of length *N* from bond
potential and force values listed in a file(s) as a function of bond
length. The files are read by the :doc:`bond_coeff <bond_coeff>`
command.
The interpolation tables are created by fitting cubic splines to the
file values and interpolating energy and force values at each of *N*
distances. During a simulation, these tables are used to interpolate
energy and force values as needed. The interpolation is done in one
of 2 styles: *linear* or *spline*.
For the *linear* style, the bond length is used to find 2 surrounding
table values from which an energy or force is computed by linear
interpolation.
For the *spline* style, a cubic spline coefficients are computed and
stored at each of the *N* values in the table. The bond length is
used to find the appropriate set of coefficients which are used to
evaluate a cubic polynomial which computes the energy or force.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above.
* filename
* keyword
The filename specifies a file containing tabulated energy and force
values. The keyword specifies a section of the file. The format of
this file is described below.
----------
The format of a tabulated file is as follows (without the
parenthesized comments):
.. parsed-literal::
# Bond potential for harmonic (one or more comment or blank lines)
.. parsed-literal::
HAM (keyword is the first text on line)
N 101 FP 0 0 EQ 0.5 (N, FP, EQ parameters)
(blank line)
1 0.00 338.0000 1352.0000 (index, bond-length, energy, force)
2 0.01 324.6152 1324.9600
...
101 1.00 338.0000 -1352.0000
A section begins with a non-blank line whose 1st character is not a
"#"; blank lines or lines starting with "#" can be used as comments
between sections. The first line begins with a keyword which
identifies the section. The line can contain additional text, but the
initial text must match the argument specified in the
:doc:`bond_coeff <bond_coeff>` command. The next line lists (in any
order) one or more parameters for the table. Each parameter is a
keyword followed by one or more numeric values.
The parameter "N" is required and its value is the number of table
entries that follow. Note that this may be different than the *N*
specified in the :doc:`bond_style table <bond_style>` command. Let
Ntable = *N* in the bond_style command, and Nfile = "N" in the
tabulated file. What LAMMPS does is a preliminary interpolation by
creating splines using the Nfile tabulated values as nodal points. It
uses these to interpolate as needed to generate energy and force
values at Ntable different points. The resulting tables of length
Ntable are then used as described above, when computing energy and
force for individual bond lengths. This means that if you want the
interpolation tables of length Ntable to match exactly what is in the
tabulated file (with effectively no preliminary interpolation), you
should set Ntable = Nfile.
The "FP" parameter is optional. If used, it is followed by two values
fplo and fphi, which are the derivatives of the force at the innermost
and outermost bond lengths. These values are needed by the spline
construction routines. If not specified by the "FP" parameter, they
are estimated (less accurately) by the first two and last two force
values in the table.
The "EQ" parameter is also optional. If used, it is followed by a the
equilibrium bond length, which is used, for example, by the :doc:`fix shake <fix_shake>` command. If not used, the equilibrium bond
length is set to 0.0.
Following a blank line, the next N lines list the tabulated values.
On each line, the 1st value is the index from 1 to N, the 2nd value is
the bond length r (in distance units), the 3rd value is the energy (in
energy units), and the 4th is the force (in force units). The bond
lengths must range from a LO value to a HI value, and increase from
one line to the next. If the actual bond length is ever smaller than
the LO value or larger than the HI value, then the bond energy and
force is evaluated as if the bond were the LO or HI length.
Note that one file can contain many sections, each with a tabulated
potential. LAMMPS reads the file section by section until it finds
one that matches the specified keyword.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

114
doc/_sources/boundary.txt Normal file
View File

@ -0,0 +1,114 @@
.. index:: boundary
boundary command
================
Syntax
""""""
.. parsed-literal::
boundary x y z
* x,y,z = *p* or *s* or *f* or *m*, one or two letters
.. parsed-literal::
*p* is periodic
*f* is non-periodic and fixed
*s* is non-periodic and shrink-wrapped
*m* is non-periodic and shrink-wrapped with a minimum value
Examples
""""""""
.. parsed-literal::
boundary p p f
boundary p fs p
boundary s f fm
Description
"""""""""""
Set the style of boundaries for the global simulation box in each
dimension. A single letter assigns the same style to both the lower
and upper face of the box. Two letters assigns the first style to the
lower face and the second style to the upper face. The initial size
of the simulation box is set by the :doc:`read_data <read_data>`,
:doc:`read_restart <read_restart>`, or :doc:`create_box <create_box>`
commands.
The style *p* means the box is periodic, so that particles interact
across the boundary, and they can exit one end of the box and re-enter
the other end. A periodic dimension can change in size due to
constant pressure boundary conditions or box deformation (see the :doc:`fix npt <fix_nh>` and :doc:`fix deform <fix_deform>` commands). The *p*
style must be applied to both faces of a dimension.
The styles *f*, *s*, and *m* mean the box is non-periodic, so that
particles do not interact across the boundary and do not move from one
side of the box to the other.
For style *f*, the position of the face is fixed. If an atom moves
outside the face it will be deleted on the next timestep that
reneighboring occurs. This will typically generate an error unless
you have set the :doc:`thermo_modify lost <thermo_modify>` option to
allow for lost atoms.
For style *s*, the position of the face is set so as to encompass the
atoms in that dimension (shrink-wrapping), no matter how far they
move.
For style *m*, shrink-wrapping occurs, but is bounded by the value
specified in the data or restart file or set by the
:doc:`create_box <create_box>` command. For example, if the upper z
face has a value of 50.0 in the data file, the face will always be
positioned at 50.0 or above, even if the maximum z-extent of all the
atoms becomes less than 50.0. This can be useful if you start a
simulation with an empty box or if you wish to leave room on one side
of the box, e.g. for atoms to evaporate from a surface.
For triclinic (non-orthogonal) simulation boxes, if the 2nd dimension
of a tilt factor (e.g. y for xy) is periodic, then the periodicity is
enforced with the tilt factor offset. If the 1st dimension is
shrink-wrapped, then the shrink wrapping is applied to the tilted box
face, to encompass the atoms. E.g. for a positive xy tilt, the xlo
and xhi faces of the box are planes tilting in the +y direction as y
increases. These tilted planes are shrink-wrapped around the atoms to
determine the x extent of the box.
See :ref:`Section_howto 12 <howto_12>` of the doc pages
for a geometric description of triclinic boxes, as defined by LAMMPS,
and how to transform these parameters to and from other commonly used
triclinic representations.
Restrictions
""""""""""""
This command cannot be used after the simulation box is defined by a
:doc:`read_data <read_data>` or :doc:`create_box <create_box>` command or
:doc:`read_restart <read_restart>` command. See the
:doc:`change_box <change_box>` command for how to change the simulation
box boundaries after it has been defined.
For 2d simulations, the z dimension must be periodic.
Related commands
""""""""""""""""
See the :doc:`thermo_modify <thermo_modify>` command for a discussion
of lost atoms.
Default
"""""""
.. parsed-literal::
boundary p p p
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

73
doc/_sources/box.txt Normal file
View File

@ -0,0 +1,73 @@
.. index:: box
box command
===========
Syntax
""""""
.. parsed-literal::
box keyword value ...
* one or more keyword/value pairs may be appended
* keyword = *tilt*
.. parsed-literal::
*tilt* value = *small* or *large*
Examples
""""""""
.. parsed-literal::
box tilt large
box tilt small
Description
"""""""""""
Set attributes of the simulation box.
For triclinic (non-orthogonal) simulation boxes, the *tilt* keyword
allows simulation domains to be created with arbitrary tilt factors,
e.g. via the :doc:`create_box <create_box>` or
:doc:`read_data <read_data>` commands. Tilt factors determine how
skewed the triclinic box is; see :ref:`this section <howto_12>` of the manual for a discussion of
triclinic boxes in LAMMPS.
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). If *tilt* is set to
*small*, which is the default, then an error will be
generated if a box is created which exceeds this limit. If *tilt*
is set to *large*, then no limit is enforced. You can create
a box with any tilt factors you wish.
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.
Restrictions
""""""""""""
This command cannot be used after the simulation box is defined by a
:doc:`read_data <read_data>` or :doc:`create_box <create_box>` command or
:doc:`read_restart <read_restart>` command.
**Related commands:** none
Default
"""""""
The default value is tilt = small.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

381
doc/_sources/change_box.txt Normal file
View File

@ -0,0 +1,381 @@
.. index:: change_box
change_box command
==================
Syntax
""""""
.. parsed-literal::
change_box group-ID parameter args ... keyword args ...
* group-ID = ID of group of atoms to (optionally) displace
* one or more parameter/arg pairs may be appended
.. parsed-literal::
parameter = *x* or *y* or *z* or *xy* or *xz* or *yz* or *boundary* or *ortho* or *triclinic* or *set* or *remap*
*x*, *y*, *z* args = style value(s)
style = *final* or *delta* or *scale* or *volume*
*final* values = lo hi
lo hi = box boundaries after displacement (distance units)
*delta* values = dlo dhi
dlo dhi = change in box boundaries after displacement (distance units)
*scale* values = factor
factor = multiplicative factor for change in box length after displacement
*volume* value = none = adjust this dim to preserve volume of system
*xy*, *xz*, *yz* args = style value
style = *final* or *delta*
*final* value = tilt
tilt = tilt factor after displacement (distance units)
*delta* value = dtilt
dtilt = change in tilt factor after displacement (distance units)
*boundary* args = x y z
x,y,z = *p* or *s* or *f* or *m*, one or two letters
*p* is periodic
*f* is non-periodic and fixed
*s* is non-periodic and shrink-wrapped
*m* is non-periodic and shrink-wrapped with a minimum value
*ortho* args = none = change box to orthogonal
*triclinic* args = none = change box to triclinic
*set* args = none = store state of current box
*remap* args = none = remap atom coords from last saved state to current box
* zero or more keyword/value pairs may be appended
* keyword = *units*
.. parsed-literal::
*units* value = *lattice* or *box*
lattice = distances are defined in lattice units
box = distances are defined in simulation box units
Examples
""""""""
.. parsed-literal::
change_box all xy final -2.0 z final 0.0 5.0 boundary p p f remap units box
change_box all x scale 1.1 y volume z volume remap
Description
"""""""""""
Change the volume and/or shape and/or boundary conditions for the
simulation box. Orthogonal simulation boxes have 3 adjustable size
parameters (x,y,z). Triclinic (non-orthogonal) simulation boxes have
6 adjustable size/shape parameters (x,y,z,xy,xz,yz). Any or all of
them can be adjusted independently by this command. Thus it can be
used to expand or contract a box, or to apply a shear strain to a
non-orthogonal box. It can also be used to change the boundary
conditions for the simulation box, similar to the
:doc:`boundary <boundary>` command.
The size and shape of the initial simulation box are specified by the
:doc:`create_box <create_box>` or :doc:`read_data <read_data>` or
:doc:`read_restart <read_restart>` command used to setup the simulation.
The size and shape may be altered by subsequent runs, e.g. by use of
the :doc:`fix npt <fix_nh>` or :doc:`fix deform <fix_deform>` commands.
The :doc:`create_box <create_box>`, :doc:`read data <read_data>`, and
:doc:`read_restart <read_restart>` commands also determine whether the
simulation box is orthogonal or triclinic and their doc pages explain
the meaning of the xy,xz,yz tilt factors.
See :ref:`Section_howto 12 <howto_12>` of the doc pages
for a geometric description of triclinic boxes, as defined by LAMMPS,
and how to transform these parameters to and from other commonly used
triclinic representations.
The keywords used in this command are applied sequentially to the
simulation box and the atoms in it, in the order specified.
Before the sequence of keywords are invoked, the current box
size/shape is stored, in case a *remap* keyword is used to map the
atom coordinates from a previously stored box size/shape to the
current one.
After all the keywords have been processed, any shrink-wrap boundary
conditions are invoked (see the :doc:`boundary <boundary>` command)
which may change simulation box boundaries, and atoms are migrated to
new owning processors.
.. note::
This means that you cannot use the change_box command to enlarge
a shrink-wrapped box, e.g. to make room to insert more atoms via the
:doc:`create_atoms <create_atoms>` command, because the simulation box
will be re-shrink-wrapped before the change_box command completes.
Instead you could do something like this, assuming the simulation box
is non-periodic and atoms extend from 0 to 20 in all dimensions:
.. parsed-literal::
change_box all x final -10 20
create_atoms 1 single -5 5 5 # this will fail to insert an atom
.. parsed-literal::
change_box all x final -10 20 boundary f s s
create_atoms 1 single -5 5 5
change_box boundary s s s # this will work
.. note::
Unlike the earlier "displace_box" version of this command, atom
remapping is NOT performed by default. This command allows remapping
to be done in a more general way, exactly when you specify it (zero or
more times) in the sequence of transformations. Thus if you do not
use the *remap* keyword, atom coordinates will not be changed even if
the box size/shape changes. If a uniformly strained state is desired,
the *remap* keyword should be specified.
.. note::
It is possible to lose atoms with this command. E.g. by
changing the box without remapping the atoms, and having atoms end up
outside of non-periodic boundaries. It is also possible to alter
bonds between atoms straddling a boundary in bad ways. E.g. by
converting a boundary from periodic to non-periodic. It is also
possible when remapping atoms to put them (nearly) on top of each
other. E.g. by converting a boundary from non-periodic to periodic.
All of these will typically lead to bad dynamics and/or generate error
messages.
.. note::
The simulation box size/shape can be changed by arbitrarily
large amounts by this command. This is not a problem, except that the
mapping of processors to the simulation box is not changed from its
initial 3d configuration; see the :doc:`processors <processors>`
command. Thus, if the box size/shape changes dramatically, the
mapping of processors to the simulation box may not end up as optimal
as the initial mapping attempted to be.
.. note::
Because the keywords used in this command are applied one at a
time to the simulation box and the atoms in it, care must be taken
with triclinic cells to avoid exceeding the limits on skew after each
transformation in the sequence. If skew is exceeded before the final
transformation this can be avoided by changing the order of the
sequence, or breaking the transformation into two or more smaller
transformations. For more information on the allowed limits for box
skew see the discussion on triclinic boxes on :ref:`this page <howto_12>`.
----------
For the *x*, *y*, and *z* parameters, this is the meaning of their
styles and values.
For style *final*, the final lo and hi box boundaries of a dimension
are specified. The values can be in lattice or box distance units.
See the discussion of the units keyword below.
For style *delta*, plus or minus changes in the lo/hi box boundaries
of a dimension are specified. The values can be in lattice or box
distance units. See the discussion of the units keyword below.
For style *scale*, a multiplicative factor to apply to the box length
of a dimension is specified. For example, if the initial box length
is 10, and the factor is 1.1, then the final box length will be 11. A
factor less than 1.0 means compression.
The *volume* style changes the specified dimension in such a way that
the overall box volume remains constant with respect to the operation
performed by the preceding keyword. The *volume* style can only be
used following a keyword that changed the volume, which is any of the
*x*, *y*, *z* keywords. If the preceding keyword "key" had a *volume*
style, then both it and the current keyword apply to the keyword
preceding "key". I.e. this sequence of keywords is allowed:
.. parsed-literal::
change_box all x scale 1.1 y volume z volume
The *volume* style changes the associated dimension so that the
overall box volume is unchanged relative to its value before the
preceding keyword was invoked.
If the following command is used, then the z box length will shrink by
the same 1.1 factor the x box length was increased by:
.. parsed-literal::
change_box all x scale 1.1 z volume
If the following command is used, then the y,z box lengths will each
shrink by sqrt(1.1) to keep the volume constant. In this case, the
y,z box lengths shrink so as to keep their relative aspect ratio
constant:
.. parsed-literal::
change_box all"x scale 1.1 y volume z volume
If the following command is used, then the final box will be a factor
of 10% larger in x and y, and a factor of 21% smaller in z, so as to
keep the volume constant:
.. parsed-literal::
change_box all x scale 1.1 z volume y scale 1.1 z volume
.. note::
For solids or liquids, when one dimension of the box is
expanded, it may be physically undesirable to hold the other 2 box
lengths constant since that implies a density change. For solids,
adjusting the other dimensions via the *volume* style may make
physical sense (just as for a liquid), but may not be correct for
materials and potentials whose Poisson ratio is not 0.5.
For the *scale* and *volume* styles, the box length is expanded or
compressed around its mid point.
----------
For the *xy*, *xz*, and *yz* parameters, this is the meaning of their
styles and values. Note that changing the tilt factors of a triclinic
box does not change its volume.
For style *final*, the final tilt factor is specified. The value
can be in lattice or box distance units. See the discussion of the
units keyword below.
For style *delta*, a plus or minus change in the tilt factor is
specified. The value can be in lattice or box distance units. See
the discussion of the units keyword below.
All of these styles change the xy, xz, yz tilt factors. In LAMMPS,
tilt factors (xy,xz,yz) for triclinic boxes are required to be no more
than half the distance of the parallel box length. 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 all equivalent. Any tilt factor specified by this command
must be within these limits.
----------
The *boundary* keyword takes arguments that have exactly the same
meaning as they do for the :doc:`boundary <boundary>` command. In each
dimension, a single letter assigns the same style to both the lower
and upper face of the box. Two letters assigns the first style to the
lower face and the second style to the upper face.
The style *p* means the box is periodic; the other styles mean
non-periodic. For style *f*, the position of the face is fixed. For
style *s*, the position of the face is set so as to encompass the
atoms in that dimension (shrink-wrapping), no matter how far they
move. For style *m*, shrink-wrapping occurs, but is bounded by the
current box edge in that dimension, so that the box will become no
smaller. See the :doc:`boundary <boundary>` command for more
explanation of these style options.
Note that the "boundary" command itself can only be used before the
simulation box is defined via a :doc:`read_data <read_data>` or
:doc:`create_box <create_box>` or :doc:`read_restart <read_restart>`
command. This command allows the boundary conditions to be changed
later in your input script. Also note that the
:doc:`read_restart <read_restart>` will change boundary conditions to
match what is stored in the restart file. So if you wish to change
them, you should use the change_box command after the read_restart
command.
----------
The *ortho* and *triclinic* keywords convert the simulation box to be
orthogonal or triclinic (non-orthongonal). See :ref:`this section <howto_13>` for a discussion of how non-orthongal
boxes are represented in LAMMPS.
The simulation box is defined as either orthogonal or triclinic when
it is created via the :doc:`create_box <create_box>`,
:doc:`read_data <read_data>`, or :doc:`read_restart <read_restart>`
commands.
These keywords allow you to toggle the existing simulation box from
orthogonal to triclinic and vice versa. For example, an initial
equilibration simulation can be run in an orthogonal box, the box can
be toggled to triclinic, and then a :ref:`non-equilibrium MD (NEMD) simulation <howto_13>` can be run with deformation
via the :doc:`fix deform <fix_deform>` command.
If the simulation box is currently triclinic and has non-zero tilt in
xy, yz, or xz, then it cannot be converted to an orthogonal box.
----------
The *set* keyword saves the current box size/shape. This can be
useful if you wish to use the *remap* keyword more than once or if you
wish it to be applied to an intermediate box size/shape in a sequence
of keyword operations. Note that the box size/shape is saved before
any of the keywords are processed, i.e. the box size/shape at the time
the create_box command is encountered in the input script.
The *remap* keyword remaps atom coordinates from the last saved box
size/shape to the current box state. For example, if you stretch the
box in the x dimension or tilt it in the xy plane via the *x* and *xy*
keywords, then the *remap* commmand will dilate or tilt the atoms to
conform to the new box size/shape, as if the atoms moved with the box
as it deformed.
Note that this operation is performed without regard to periodic
boundaries. Also, any shrink-wrapping of non-periodic boundaries (see
the :doc:`boundary <boundary>` command) occurs after all keywords,
including this one, have been processed.
Only atoms in the specified group are remapped.
----------
The *units* keyword determines the meaning of the distance units used
to define various arguments. A *box* value selects standard distance
units as defined by the :doc:`units <units>` command, e.g. Angstroms for
units = real or metal. A *lattice* value means the distance units are
in lattice spacings. The :doc:`lattice <lattice>` command must have
been previously used to define the lattice spacing.
----------
Restrictions
""""""""""""
If you use the *ortho* or *triclinic* keywords, then at the point in
the input script when this command is issued, no :doc:`dumps <dump>` can
be active, nor can a :doc:`fix ave/spatial <fix_ave_spatial>` or :doc:`fix deform <fix_deform>` be active. This is because these commands
test whether the simulation box is orthogonal when they are first
issued. Note that these commands can be used in your script before a
change_box command is issued, so long as an :doc:`undump <undump>` or
:doc:`unfix <unfix>` command is also used to turn them off.
Related commands
""""""""""""""""
:doc:`fix deform <fix_deform>`, :doc:`boundary <boundary>`
Default
"""""""
The option default is units = lattice.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

47
doc/_sources/clear.txt Normal file
View File

@ -0,0 +1,47 @@
.. index:: clear
clear command
=============
Syntax
""""""
.. parsed-literal::
clear
Examples
""""""""
.. parsed-literal::
(commands for 1st simulation)
clear
(commands for 2nd simulation)
Description
"""""""""""
This command deletes all atoms, restores all settings to their default
values, and frees all memory allocated by LAMMPS. Once a clear
command has been executed, it is almost as if LAMMPS were starting
over, with only the exceptions noted below. This command enables
multiple jobs to be run sequentially from one input script.
These settings are not affected by a clear command: the working
directory (:doc:`shell <shell>` command), log file status
(:doc:`log <log>` command), echo status (:doc:`echo <echo>` command), and
input script variables (:doc:`variable <variable>` command).
Restrictions
""""""""""""
none
**Related commands:** none
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

177
doc/_sources/comm_modify.txt Normal file
View File

@ -0,0 +1,177 @@
.. index:: comm_modify
comm_modify command
===================
Syntax
""""""
.. parsed-literal::
comm_modify keyword value ...
* zero or more keyword/value pairs may be appended
* keyword = *mode* or *cutoff* or *cutoff/multi* or *group* or *vel*
.. parsed-literal::
*mode* value = *single* or *multi* = communicate atoms within a single or multiple distances
*cutoff* value = Rcut (distance units) = communicate atoms from this far away
*cutoff/multi* type value
type = atom type or type range (supports asterisk notation)
value = Rcut (distance units) = communicate atoms for selected types from this far away
*group* value = group-ID = only communicate atoms in the group
*vel* value = *yes* or *no* = do or do not communicate velocity info with ghost atoms
Examples
""""""""
.. parsed-literal::
comm_modify mode multi
comm_modify mode multi group solvent
comm_modift mode multi cutoff/multi 1 10.0 cutoff/multi 2*4 15.0
comm_modify vel yes
comm_modify mode single cutoff 5.0 vel yes
comm_modify cutoff/multi * 0.0
Description
"""""""""""
This command sets parameters that affect the inter-processor
communication of atom information that occurs each timestep as
coordinates and other properties are exchanged between neighboring
processors and stored as properties of ghost atoms.
.. note::
These options apply to the currently defined comm style. When
you specify a :doc:`comm_style <comm_style>` command, all communication
settings are restored to their default values, including those
previously reset by a comm_modify command. Thus if your input script
specifies a comm_style command, you should use the comm_modify command
after it.
The *mode* keyword determines whether a single or multiple cutoff
distances are used to determine which atoms to communicate.
The default mode is *single* which means each processor acquires
information for ghost atoms that are within a single distance from its
sub-domain. The distance is by default the maximum of the neighbor
cutoff across all atom type pairs.
For many systems this is an efficient algorithm, but for systems with
widely varying cutoffs for different type pairs, the *multi* mode can
be faster. In this case, each atom type is assigned its own distance
cutoff for communication purposes, and fewer atoms will be
communicated. See the :doc:`neighbor multi <neighbor>` command for a
neighbor list construction option that may also be beneficial for
simulations of this kind.
The *cutoff* keyword allows you to extend the ghost cutoff distance
for communication mode *single*, which is the distance from the borders
of a processor's sub-domain at which ghost atoms are acquired from other
processors. By default the ghost cutoff = neighbor cutoff = pairwise
force cutoff + neighbor skin. See the :doc:`neighbor <neighbor>` command
for more information about the skin distance. If the specified Rcut is
greater than the neighbor cutoff, then extra ghost atoms will be acquired.
If the provided cutoff is smaller, the provided value will be ignored
and the ghost cutoff is set to the neighbor cutoff. Specifying a
cutoff value of 0.0 will reset any previous value to the default.
The *cutoff/multi* option is equivalent to *cutoff*, but applies to
communication mode *multi* instead. Since in this case the communication
cutoffs are determined per atom type, a type specifier is needed and
cutoff for one or multiple types can be extended. Also ranges of types
using the usual asterisk notation can be given.
These are simulation scenarios in which it may be useful or even
necessary to set a ghost cutoff > neighbor cutoff:
* a single polymer chain with bond interactions, but no pairwise interactions
* bonded interactions (e.g. dihedrals) extend further than the pairwise cutoff
* ghost atoms beyond the pairwise cutoff are needed for some computation
In the first scenario, a pairwise potential is not defined. Thus the
pairwise neighbor cutoff will be 0.0. But ghost atoms are still
needed for computing bond, angle, etc interactions between atoms on
different processors, or when the interaction straddles a periodic
boundary.
The appropriate ghost cutoff depends on the :doc:`newton bond <newton>`
setting. For newton bond *off*, the distance needs to be the furthest
distance between any two atoms in the bond, angle, etc. E.g. the
distance between 1-4 atoms in a dihedral. For newton bond *on*, the
distance between the central atom in the bond, angle, etc and any
other atom is sufficient. E.g. the distance between 2-4 atoms in a
dihedral.
In the second scenario, a pairwise potential is defined, but its
neighbor cutoff is not sufficiently long enough to enable bond, angle,
etc terms to be computed. As in the previous scenario, an appropriate
ghost cutoff should be set.
In the last scenario, a :doc:`fix <fix>` or :doc:`compute <compute>` or
:doc:`pairwise potential <pair_style>` needs to calculate with ghost
atoms beyond the normal pairwise cutoff for some computation it
performs (e.g. locate neighbors of ghost atoms in a multibody pair
potential). Setting the ghost cutoff appropriately can insure it will
find the needed atoms.
.. note::
In these scenarios, if you do not set the ghost cutoff long
enough, and if there is only one processor in a periodic dimension
(e.g. you are running in serial), then LAMMPS may "find" the atom it
is looking for (e.g. the partner atom in a bond), that is on the far
side of the simulation box, across a periodic boundary. This will
typically lead to bad dynamics (i.e. the bond length is now the
simulation box length). To detect if this is happening, see the
:doc:`neigh_modify cluster <neigh_modify>` command.
The *group* keyword will limit communication to atoms in the specified
group. This can be useful for models where no ghost atoms are needed
for some kinds of particles. All atoms (not just those in the
specified group) will still migrate to new processors as they move.
The group specified with this option must also be specified via the
:doc:`atom_modify first <atom_modify>` command.
The *vel* keyword enables velocity information to be communicated with
ghost particles. Depending on the :doc:`atom_style <atom_style>`,
velocity info includes the translational velocity, angular velocity,
and angular momentum of a particle. If the *vel* option is set to
*yes*, then ghost atoms store these quantities; if *no* then they do
not. The *yes* setting is needed by some pair styles which require
the velocity state of both the I and J particles to compute a pairwise
I,J interaction.
Note that if the :doc:`fix deform <fix_deform>` command is being used
with its "remap v" option enabled, then the velocities for ghost atoms
(in the fix deform group) mirrored across a periodic boundary will
also include components due to any velocity shift that occurs across
that boundary (e.g. due to dilation or shear).
Restrictions
""""""""""""
Communication mode *multi* is currently only available for
:doc:`comm_style <comm_style>` *brick*.
Related commands
""""""""""""""""
:doc:`comm_style <comm_style>`, :doc:`neighbor <neighbor>`
Default
"""""""
The option defauls are mode = single, group = all, cutoff = 0.0, vel =
no. The cutoff default of 0.0 means that ghost cutoff = neighbor
cutoff = pairwise force cutoff + neighbor skin.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

73
doc/_sources/comm_style.txt Normal file
View File

@ -0,0 +1,73 @@
.. index:: comm_style
comm_style command
==================
Syntax
""""""
.. parsed-literal::
comm_style style
* style = *brick* or *tiled*
Examples
""""""""
.. parsed-literal::
comm_style brick
comm_style tiled
Description
"""""""""""
This command sets the style of inter-processor communication of atom
information that occurs each timestep as coordinates and other
properties are exchanged between neighboring processors and stored as
properties of ghost atoms.
For the default *brick* style, the domain decomposition used by LAMMPS
to partition the simulation box must be a regular 3d grid of bricks,
one per processor. Each processor communicates with its 6 Cartesian
neighbors in the grid to acquire information for nearby atoms.
For the *tiled* style, a more general domain decomposition can be
used, as triggered by the :doc:`balance <balance>` or :doc:`fix balance <fix_balance>` commands. The simulation box can be
partitioned into non-overlapping rectangular-shaped "tiles" or varying
sizes and shapes. Again there is one tile per processor. To acquire
information for nearby atoms, communication must now be done with a
more complex pattern of neighboring processors.
Note that this command does not actually define a partitoining of the
simulation box (a domain decomposition), rather it determines what
kinds of decompositions are allowed and the pattern of communication
used to enable the decomposition. A decomposition is created when the
simulation box is first created, via the :doc:`create_box <create_box>`
or :doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
commands. For both the *brick* and *tiled* styles, the initial
decomposition will be the same, as described by
:doc:`create_box <create_box>` and :doc:`processors <processors>`
commands. The decomposition can be changed via the
:doc:`balance <balance>` or :doc:`fix_balance <fix_balance>` commands.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`comm_modify <comm_modify>`, :doc:`processors <processors>`,
:doc:`balance <balance>`, :doc:`fix balance <fix_balance>`
Default
"""""""
The default style is brick.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

270
doc/_sources/compute.txt Normal file
View File

@ -0,0 +1,270 @@
.. index:: compute
compute command
===============
Syntax
""""""
.. parsed-literal::
compute ID group-ID style args
* ID = user-assigned name for the computation
* group-ID = ID of the group of atoms to perform the computation on
* style = one of a list of possible style names (see below)
* args = arguments used by a particular style
Examples
""""""""
.. parsed-literal::
compute 1 all temp
compute newtemp flow temp/partial 1 1 0
compute 3 all ke/atom
Description
"""""""""""
Define a computation that will be performed on a group of atoms.
Quantities calculated by a compute are instantaneous values, meaning
they are calculated from information about atoms on the current
timestep or iteration, though a compute may internally store some
information about a previous state of the system. Defining a compute
does not perform a computation. Instead computes are invoked by other
LAMMPS commands as needed, e.g. to calculate a temperature needed for
a thermostat fix or to generate thermodynamic or dump file output.
See this :ref:`howto section <howto_15>` for a summary of
various LAMMPS output options, many of which involve computes.
The ID of a compute can only contain alphanumeric characters and
underscores.
----------
Computes calculate one of three styles of quantities: global,
per-atom, or local. A global quantity is one or more system-wide
values, e.g. the temperature of the system. A per-atom quantity is
one or more values per atom, e.g. the kinetic energy of each atom.
Per-atom values are set to 0.0 for atoms not in the specified compute
group. Local quantities 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. Computes that produce per-atom quantities have the
word "atom" in their style, e.g. *ke/atom*. Computes that produce
local quantities have the word "local" in their style,
e.g. *bond/local*. Styles with neither "atom" or "local" in their
style produce global quantities.
Note that a single compute produces either global or per-atom or local
quantities, but never more than one of these (with only a few
exceptions, as documented by individual compute commands).
Global, per-atom, and local quantities each come in three kinds: a
single scalar value, a vector of values, or a 2d array of values. The
doc page for each compute describes the style and kind of values it
produces, e.g. a per-atom vector. Some computes produce more than one
kind of a single style, e.g. a global scalar and a global vector.
When a compute quantity is accessed, as in many of the output commands
discussed below, it can be referenced via the following bracket
notation, where ID is the ID of the compute:
+------------+--------------------------------------------+
| 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
quantity once (vector -> scalar, array -> vector). Using two brackets
reduces the dimension twice (array -> scalar). Thus a command that
uses scalar compute values as input can also process elements of a
vector or array.
Note that commands and :doc:`variables <variable>` which use compute
quantities typically do not allow for all kinds, e.g. a command may
require a vector of values, not a scalar. This means there is no
ambiguity about referring to a compute quantity as c_ID even if it
produces, for example, both a scalar and vector. The doc pages for
various commands explain the details.
----------
In LAMMPS, the values generated by a compute can be used in several
ways:
* The results of computes that calculate a global temperature or
pressure can be used by fixes that do thermostatting or barostatting
or when atom velocities are created.
* Global values can be output via the :doc:`thermo_style custom <thermo_style>` or :doc:`fix ave/time <fix_ave_time>` command.
Or the values can be referenced in a :doc:`variable equal <variable>` or
:doc:`variable atom <variable>` command.
* Per-atom values can be output via the :doc:`dump custom <dump>` command
or the :doc:`fix ave/spatial <fix_ave_spatial>` command. Or they can be
time-averaged via the :doc:`fix ave/atom <fix_ave_atom>` command or
reduced by the :doc:`compute reduce <compute_reduce>` command. Or the
per-atom values can be referenced in an :doc:`atom-style variable <variable>`.
* Local values can be reduced by the :doc:`compute reduce <compute_reduce>` command, or histogrammed by the :doc:`fix ave/histo <fix_ave_histo>` command, or output by the :doc:`dump local <dump>` command.
The results of computes that calculate global quantities can be either
"intensive" or "extensive" values. Intensive means the value is
independent of the number of atoms in the simulation,
e.g. temperature. Extensive means the value scales with the number of
atoms in the simulation, e.g. total rotational kinetic energy.
:doc:`Thermodynamic output <thermo_style>` will normalize extensive
values by the number of atoms in the system, depending on the
"thermo_modify norm" setting. It will not normalize intensive values.
If a compute value is accessed in another way, e.g. by a
:doc:`variable <variable>`, you may want to know whether it is an
intensive or extensive value. See the doc page for individual
computes for further info.
----------
LAMMPS creates its own computes internally for thermodynamic output.
Three computes are always created, named "thermo_temp",
"thermo_press", and "thermo_pe", as if these commands had been invoked
in the input script:
.. parsed-literal::
compute thermo_temp all temp
compute thermo_press all pressure thermo_temp
compute thermo_pe all pe
Additional computes for other quantities are created if the thermo
style requires it. See the documentation for the
:doc:`thermo_style <thermo_style>` command.
Fixes that calculate temperature or pressure, i.e. for thermostatting
or barostatting, may also create computes. These are discussed in the
documentation for specific :doc:`fix <fix>` commands.
In all these cases, the default computes LAMMPS creates can be
replaced by computes defined by the user in the input script, as
described by the :doc:`thermo_modify <thermo_modify>` and :doc:`fix modify <fix_modify>` commands.
Properties of either a default or user-defined compute can be modified
via the :doc:`compute_modify <compute_modify>` command.
Computes can be deleted with the :doc:`uncompute <uncompute>` command.
Code for new computes can be added to LAMMPS (see :doc:`this section <Section_modify>` of the manual) and the results of their
calculations accessed in the various ways described above.
----------
Each compute style has its own doc page which describes its arguments
and what it does. Here is an alphabetic list of compute styles
available in LAMMPS. They are also given in more compact form in the
Compute section of :ref:`this page <cmd_5>`.
There are also additional compute styles (not listed here) submitted
by users which are included in the LAMMPS distribution. The list of
these with links to the individual styles are given in the compute
section of :ref:`this page <cmd_5>`.
* :doc:`angle/local <compute_bond_local>` - theta and energy of each angle
* :doc:`angmom/chunk <compute_angmom_chunk>` - angular momentum for each chunk
* :doc:`body/local <compute_body_local>` - attributes of body sub-particles
* :doc:`bond/local <compute_bond_local>` - distance and energy of each bond
* :doc:`centro/atom <compute_centro_atom>` - centro-symmetry parameter for each atom
* :doc:`chunk/atom <compute_chunk_atom>` - assign chunk IDs to each atom
* :doc:`cluster/atom <compute_cluster_atom>` - cluster ID for each atom
* :doc:`cna/atom <compute_cna_atom>` - common neighbor analysis (CNA) for each atom
* :doc:`com <compute_com>` - center-of-mass of group of atoms
* :doc:`com/chunk <compute_com_chunk>` - center-of-mass for each chunk
* :doc:`contact/atom <compute_contact_atom>` - contact count for each spherical particle
* :doc:`coord/atom <compute_coord_atom>` - coordination number for each atom
* :doc:`damage/atom <compute_damage_atom>` - Peridynamic damage for each atom
* :doc:`dihedral/local <compute_dihedral_local>` - angle of each dihedral
* :doc:`dilatation/atom <compute_dilatation_atom>` - Peridynamic dilatation for each atom
* :doc:`displace/atom <compute_displace_atom>` - displacement of each atom
* :doc:`erotate/asphere <compute_erotate_asphere>` - rotational energy of aspherical particles
* :doc:`erotate/rigid <compute_erotate_rigid>` - rotational energy of rigid bodies
* :doc:`erotate/sphere <compute_erotate_sphere>` - rotational energy of spherical particles
* :doc:`erotate/sphere/atom <compute_erotate_sphere>` - rotational energy for each spherical particle
* :doc:`event/displace <compute_event_displace>` - detect event on atom displacement
* :doc:`group/group <compute_group_group>` - energy/force between two groups of atoms
* :doc:`gyration <compute_gyration>` - radius of gyration of group of atoms
* :doc:`gyration/chunk <compute_gyration_chunk>` - radius of gyration for each chunk
* :doc:`heat/flux <compute_heat_flux>` - heat flux through a group of atoms
* :doc:`hexorder/atom <compute_hexorder_atom>` - bond orientational order parameter q6
* :doc:`improper/local <compute_improper_local>` - angle of each improper
* :doc:`inertia/chunk <compute_inertia_chunk>` - inertia tensor for each chunk
* :doc:`ke <compute_ke>` - translational kinetic energy
* :doc:`ke/atom <compute_ke_atom>` - kinetic energy for each atom
* :doc:`ke/rigid <compute_ke_rigid>` - translational kinetic energy of rigid bodies
* :doc:`msd <compute_msd>` - mean-squared displacement of group of atoms
* :doc:`msd/chunk <compute_msd_chunk>` - mean-squared displacement for each chunk
* :doc:`msd/nongauss <compute_msd_nongauss>` - MSD and non-Gaussian parameter of group of atoms
* :doc:`omega/chunk <compute_omega_chunk>` - angular velocity for each chunk
* :doc:`orientorder/atom <compute_orientorder_atom>` - Steinhardt bond orientational order parameters Ql
* :doc:`pair <compute_pair>` - values computed by a pair style
* :doc:`pair/local <compute_pair_local>` - distance/energy/force of each pairwise interaction
* :doc:`pe <compute_pe>` - potential energy
* :doc:`pe/atom <compute_pe_atom>` - potential energy for each atom
* :doc:`plasticity/atom <compute_plasticity_atom>` - Peridynamic plasticity for each atom
* :doc:`pressure <compute_pressure>` - total pressure and pressure tensor
* :doc:`property/atom <compute_property_atom>` - convert atom attributes to per-atom vectors/arrays
* :doc:`property/local <compute_property_local>` - convert local attributes to localvectors/arrays
* :doc:`property/chunk <compute_property_chunk>` - extract various per-chunk attributes
* :doc:`rdf <compute_rdf>` - radial distribution function g(r) histogram of group of atoms
* :doc:`reduce <compute_reduce>` - combine per-atom quantities into a single global value
* :doc:`reduce/region <compute_reduce>` - same as compute reduce, within a region
* :doc:`slice <compute_slice>` - extract values from global vector or array
* :doc:`sna/atom <compute_sna_atom>` - calculate bispectrum coefficients for each atom
* :doc:`snad/atom <compute_sna_atom>` - derivative of bispectrum coefficients for each atom
* :doc:`snav/atom <compute_sna_atom>` - virial contribution from bispectrum coefficients for each atom
* :doc:`stress/atom <compute_stress_atom>` - stress tensor for each atom
* :doc:`temp <compute_temp>` - temperature of group of atoms
* :doc:`temp/asphere <compute_temp_asphere>` - temperature of aspherical particles
* :doc:`temp/chunk <compute_temp_chunk>` - temperature of each chunk
* :doc:`temp/com <compute_temp_com>` - temperature after subtracting center-of-mass velocity
* :doc:`temp/deform <compute_temp_deform>` - temperature excluding box deformation velocity
* :doc:`temp/partial <compute_temp_partial>` - temperature excluding one or more dimensions of velocity
* :doc:`temp/profile <compute_temp_profile>` - temperature excluding a binned velocity profile
* :doc:`temp/ramp <compute_temp_ramp>` - temperature excluding ramped velocity component
* :doc:`temp/region <compute_temp_region>` - temperature of a region of atoms
* :doc:`temp/sphere <compute_temp_sphere>` - temperature of spherical particles
* :doc:`ti <compute_ti>` - thermodyanmic integration free energy values
* :doc:`torque/chunk <compute_torque_chunk>` - torque applied on each chunk
* :doc:`vacf <compute_vacf>` - velocity-autocorrelation function of group of atoms
* :doc:`vcm/chunk <compute_vcm_chunk>` - velocity of center-of-mass for each chunk
* :doc:`voronoi/atom <compute_voronoi_atom>` - Voronoi volume and neighbors for each atom
There are also additional compute styles submitted by users which are
included in the LAMMPS distribution. The list of these with links to
the individual styles are given in the compute section of :ref:`this page <cmd_5>`.
There are also additional accelerated compute styles included in the
LAMMPS distribution for faster performance on CPUs and GPUs. The list
of these with links to the individual styles are given in the pair
section of :ref:`this page <cmd_5>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`uncompute <uncompute>`, :doc:`compute_modify <compute_modify>`, :doc:`fix ave/atom <fix_ave_atom>`, :doc:`fix ave/spatial <fix_ave_spatial>`,
:doc:`fix ave/time <fix_ave_time>`, :doc:`fix ave/histo <fix_ave_histo>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

87
doc/_sources/compute_ackland_atom.txt Normal file
View File

@ -0,0 +1,87 @@
.. index:: compute ackland/atom
compute ackland/atom command
============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID ackland/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* ackland/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all ackland/atom
Description
"""""""""""
Defines a computation that calculates the local lattice structure
according to the formulation given in :ref:`(Ackland) <Ackland>`.
In contrast to the :doc:`centro-symmetry parameter <compute_centro_atom>` this method is stable against
temperature boost, because it is based not on the distance between
particles but the angles. Therefore statistical fluctuations are
averaged out a little more. A comparison with the Common Neighbor
Analysis metric is made in the paper.
The result is a number which is mapped to the following different
lattice structures:
* 0 = UNKNOWN
* 1 = BCC
* 2 = FCC
* 3 = HCP
* 4 = ICO
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently or to have multiple compute/dump commands, each of
which computes this quantity.-
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
Restrictions
""""""""""""
This compute is part of the USER-MISC package. It is only enabled if
LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
The per-atom vector values will be unitless since they are the
integers defined above.
Related commands
""""""""""""""""
:doc:`compute centro/atom <compute_centro_atom>`
**Default:** none
----------
.. _Ackland:
**(Ackland)** Ackland, Jones, Phys Rev B, 73, 054104 (2006).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

86
doc/_sources/compute_angle_local.txt Normal file
View File

@ -0,0 +1,86 @@
.. index:: compute angle/local
compute angle/local command
===========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID angle/local input1 input2 ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* angle/local = style name of this compute command
* one or more keywords may be appended
* keyword = *theta* or *eng*
.. parsed-literal::
*theta* = tabulate angles
*eng* = tabulate angle energies
Examples
""""""""
.. parsed-literal::
compute 1 all angle/local theta
compute 1 all angle/local eng theta
Description
"""""""""""
Define a computation that calculates properties of individual angle
interactions. The number of datums generated, aggregated across all
processors, equals the number of angles in the system, modified by the
group parameter as explained below.
The local data stored by this command is generated by looping over all
the atoms owned on a processor and their angles. An angle will only
be included if all 3 atoms in the angle are in the specified compute
group. Any angles that have been broken (see the
:doc:`angle_style <angle_style>` command) by setting their angle type to
0 are not included. Angles that have been turned off (see the :doc:`fix shake <fix_shake>` or :doc:`delete_bonds <delete_bonds>` commands) by
setting their angle type negative are written into the file, but their
energy will be 0.0.
Note that as atoms migrate from processor to processor, there will be
no consistent ordering of the entries within the local vector or array
from one timestep to the next. The only consistency that is
guaranteed is that the ordering on a particular timestep will be the
same for local vectors or arrays generated by other compute commands.
For example, angle output from the :doc:`compute property/local <compute_property_local>` command can be combined
with data from this command and output by the :doc:`dump local <dump>`
command in a consistent way.
**Output info:**
This compute calculates a local vector or local array depending on the
number of keywords. The length of the vector or number of rows in the
array is the number of angles. If a single keyword is specified, a
local vector is produced. If two or more keywords are specified, a
local array is produced where the number of columns = the number of
keywords. The vector or array can be accessed by any command that
uses local values from a compute as input. See :ref:`this section <howto_15>` for an overview of LAMMPS output
options.
The output for *theta* will be in degrees. The output for *eng* will
be in energy :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`dump local <dump>`, :doc:`compute property/local <compute_property_local>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

97
doc/_sources/compute_angmom_chunk.txt Normal file
View File

@ -0,0 +1,97 @@
.. index:: compute angmom/chunk
compute angmom/chunk command
============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID angmom/chunk chunkID
* ID, group-ID are documented in :doc:`compute <compute>` command
* angmom/chunk = style name of this compute command
* chunkID = ID of :doc:`compute chunk/atom <compute_chunk_atom>` command
Examples
""""""""
.. parsed-literal::
compute 1 fluid angmom/chunk molchunk
Description
"""""""""""
Define a computation that calculates the angular momemtum of multiple
chunks of atoms.
In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom <compute_chunk_atom>` command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom <compute_chunk_atom>` doc page and ":ref:`Section_howto 23 <howto_23>` for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.
This compute calculates the 3 components of the angular momentum
vector for each chunk, due to the velocity/momentum of the individual
atoms in the chunk around the center-of-mass of the chunk. The
calculation includes all effects due to atoms passing thru periodic
boundaries.
Note that only atoms in the specified group contribute to the
calculation. The :doc:`compute chunk/atom <compute_chunk_atom>` command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
"all" group for this command if you simply want to include atoms with
non-zero chunk IDs.
.. note::
The coordinates of an atom contribute to the chunk's angular
momentum in "unwrapped" form, by using the image flags associated with
each atom. See the :doc:`dump custom <dump>` command for a discussion
of "unwrapped" coordinates. See the Atoms section of the
:doc:`read_data <read_data>` command for a discussion of image flags and
how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the :doc:`set image <set>` command.
The simplest way to output the results of the compute angmom/chunk
calculation to a file is to use the :doc:`fix ave/time <fix_ave_time>`
command, for example:
.. parsed-literal::
compute cc1 all chunk/atom molecule
compute myChunk all angmom/chunk cc1
fix 1 all ave/time 100 1 100 c_myChunk file tmp.out mode vector
**Output info:**
This compute calculates a global array where the number of rows = the
number of chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom <compute_chunk_atom>` command. The number of columns =
3 for the 3 xyz components of the angular momentum for each chunk.
These values can be accessed by any command that uses global array
values from a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
The array values are "intensive". The array values will be in
mass-velocity-distance :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`variable angmom() function <variable>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

88
doc/_sources/compute_basal_atom.txt Normal file
View File

@ -0,0 +1,88 @@
.. index:: compute basal/atom
compute basal/atom command
==========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID basal/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* basal/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all basal/atom
Description
"""""""""""
Defines a computation that calculates the hexagonal close-packed "c"
lattice vector for each atom in the group. It does this by
calculating the normal unit vector to the basal plane for each atom.
The results enable efficient identification and characterization of
twins and grains in hexagonal close-packed structures.
The output of the compute is thus the 3 components of a unit vector
associdate with each atom. The components are set to 0.0 for
atoms not in the group.
Details of the calculation are given in :ref:`(Barrett) <Barrett>`.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently or to have multiple compute/dump commands, each of
which computes this quantity.
An example input script that uses this compute is provided
in examples/USER/misc/basal.
**Output info:**
This compute calculates a per-atom array with 3 columns, which can be
accessed by indices 1-3 by any command that uses per-atom values from
a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
The per-atom vector values are unitless since the 3 columns represent
components of a unit vector.
Restrictions
""""""""""""
This compute is part of the USER-MISC package. It is only enabled if
LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
The output of this compute will be meaningless unless the atoms are on
(or near) hcp lattice sites, since the calculation assumes a
well-defined basal plane.
Related commands
""""""""""""""""
:doc:`compute centro/atom <compute_centro_atom>`, :doc:`compute ackland/atom <compute_ackland_atom>`
**Default:** none
----------
.. _Barrett:
**(Barrett)** Barrett, Tschopp, El Kadiri, Scripta Mat. 66, p.666 (2012).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

106
doc/_sources/compute_body_local.txt Normal file
View File

@ -0,0 +1,106 @@
.. index:: compute body/local
compute body/local command
==========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID body/local input1 input2 ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* body/local = style name of this compute command
* one or more keywords may be appended
* keyword = *id* or *type* or *integer*
.. parsed-literal::
*id* = atom ID of the body particle
*type* = atom type of the body particle
*integer* = 1,2,3,etc = index of fields defined by body style
Examples
""""""""
.. parsed-literal::
compute 1 all body/local type 1 2 3
compute 1 all body/local 3 6
Description
"""""""""""
Define a computation that calculates properties of individual body
sub-particles. The number of datums generated, aggregated across all
processors, equals the number of body sub-particles plus the number of
non-body particles in the system, modified by the group parameter as
explained below. See :ref:`Section_howto 14 <howto_14>`
of the manual and the :doc:`body <body>` doc page for more details on
using body particles.
The local data stored by this command is generated by looping over all
the atoms. An atom will only be included if it is in the group. If
the atom is a body particle, then its N sub-particles will be looped
over, and it will contribute N datums to the count of datums. If it
is not a body particle, it will contribute 1 datum.
For both body particles and non-body particles, the *id* keyword
will store the ID of the particle.
For both body particles and non-body particles, the *type* keyword
will store the type of the particle.
The *integer* keywords mean different things for body and non-body
particles. If the atom is not a body particle, only its *x*, *y*, *z*
coordinates can be referenced, using the *integer* keywords 1,2,3.
Note that this means that if you want to access more fields than this
for body particles, then you cannot include non-body particles in the
group.
For a body particle, the *integer* keywords refer to fields calculated
by the body style for each sub-particle. The body style, as specified
by the :doc:`atom_style body <atom_style>`, determines how many fields
exist and what they are. See the :doc:`body <body>` doc page for
details of the different styles.
Here is an example of how to output body information using the :doc:`dump local <dump>` command with this compute. If fields 1,2,3 for the
body sub-particles are x,y,z coordinates, then the dump file will be
formatted similar to the output of a :doc:`dump atom or custom <dump>`
command.
.. parsed-literal::
compute 1 all body/local type 1 2 3
dump 1 all local 1000 tmp.dump index c_1[1] c_1[2] c_1[3] c_1[4]
**Output info:**
This compute calculates a local vector or local array depending on the
number of keywords. The length of the vector or number of rows in the
array is the number of datums as described above. If a single keyword
is specified, a local vector is produced. If two or more keywords are
specified, a local array is produced where the number of columns = the
number of keywords. The vector or array can be accessed by any
command that uses local values from a compute as input. See :ref:`this section <howto_15>` for an overview of LAMMPS output
options.
The :doc:`units <units>` for output values depend on the body style.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`dump local <dump>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

96
doc/_sources/compute_bond_local.txt Normal file
View File

@ -0,0 +1,96 @@
.. index:: compute bond/local
compute bond/local command
==========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID bond/local input1 input2 ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* bond/local = style name of this compute command
* one or more keywords may be appended
* keyword = *dist* or *eng*
.. parsed-literal::
*dist* = bond distance
*eng* = bond energy
*force* = bond force
Examples
""""""""
.. parsed-literal::
compute 1 all bond/local eng
compute 1 all bond/local dist eng force
Description
"""""""""""
Define a computation that calculates properties of individual bond
interactions. The number of datums generated, aggregated across all
processors, equals the number of bonds in the system, modified
by the group parameter as explained below.
The local data stored by this command is generated by looping over all
the atoms owned on a processor and their bonds. A bond will only be
included if both atoms in the bond are in the specified compute group.
Any bonds that have been broken (see the :doc:`bond_style <bond_style>`
command) by setting their bond type to 0 are not included. Bonds that
have been turned off (see the :doc:`fix shake <fix_shake>` or
:doc:`delete_bonds <delete_bonds>` commands) by setting their bond type
negative are written into the file, but their energy will be 0.0.
Note that as atoms migrate from processor to processor, there will be
no consistent ordering of the entries within the local vector or array
from one timestep to the next. The only consistency that is
guaranteed is that the ordering on a particular timestep will be the
same for local vectors or arrays generated by other compute commands.
For example, bond output from the :doc:`compute property/local <compute_property_local>` command can be combined
with data from this command and output by the :doc:`dump local <dump>`
command in a consistent way.
Here is an example of how to do this:
.. parsed-literal::
compute 1 all property/local batom1 batom2 btype
compute 2 all bond/local dist eng
dump 1 all local 1000 tmp.dump index c_1[1] c_1[2] c_1[3] c_2[1] c_2[2]
**Output info:**
This compute calculates a local vector or local array depending on the
number of keywords. The length of the vector or number of rows in the
array is the number of bonds. If a single keyword is specified, a
local vector is produced. If two or more keywords are specified, a
local array is produced where the number of columns = the number of
keywords. The vector or array can be accessed by any command that
uses local values from a compute as input. See :ref:`this section <howto_15>` for an overview of LAMMPS output
options.
The output for *dist* will be in distance :doc:`units <units>`. The
output for *eng* will be in energy :doc:`units <units>`. The output for
*force* will be in force :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`dump local <dump>`, :doc:`compute property/local <compute_property_local>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

142
doc/_sources/compute_centro_atom.txt Normal file
View File

@ -0,0 +1,142 @@
.. index:: compute centro/atom
compute centro/atom command
===========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID centro/atom lattice
* ID, group-ID are documented in :doc:`compute <compute>` command
* centro/atom = style name of this compute command
* lattice = *fcc* or *bcc* or N = # of neighbors per atom to include
Examples
""""""""
.. parsed-literal::
compute 1 all centro/atom fcc
.. parsed-literal::
compute 1 all centro/atom 8
Description
"""""""""""
Define a computation that calculates the centro-symmetry parameter for
each atom in the group. In solid-state systems the centro-symmetry
parameter is a useful measure of the local lattice disorder around an
atom and can be used to characterize whether the atom is part of a
perfect lattice, a local defect (e.g. a dislocation or stacking
fault), or at a surface.
The value of the centro-symmetry parameter will be 0.0 for atoms not
in the specified compute group.
This parameter is computed using the following formula from
:ref:`(Kelchner) <Kelchner>`
.. image:: Eqs/centro_symmetry.jpg
:align: center
where the *N* nearest neighbors or each atom are identified and Ri and
Ri+N/2 are vectors from the central atom to a particular pair of
nearest neighbors. There are N*(N-1)/2 possible neighbor pairs that
can contribute to this formula. The quantity in the sum is computed
for each, and the N/2 smallest are used. This will typically be for
pairs of atoms in symmetrically opposite positions with respect to the
central atom; hence the i+N/2 notation.
*N* is an input parameter, which should be set to correspond to the
number of nearest neighbors in the underlying lattice of atoms. If
the keyword *fcc* or *bcc* is used, *N* is set to 12 and 8
respectively. More generally, *N* can be set to a positive, even
integer.
For an atom on a lattice site, surrounded by atoms on a perfect
lattice, the centro-symmetry parameter will be 0. It will be near 0
for small thermal perturbations of a perfect lattice. If a point
defect exists, the symmetry is broken, and the parameter will be a
larger positive value. An atom at a surface will have a large
positive parameter. If the atom does not have *N* neighbors (within
the potential cutoff), then its centro-symmetry parameter is set to
0.0.
Only atoms within the cutoff of the pairwise neighbor list are
considered as possible neighbors. Atoms not in the compute group are
included in the *N* neighbors used in this calculation.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (e.g. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently or to have multiple compute/dump commands, each with a
*centro/atom* style.
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The per-atom vector values are unitless values >= 0.0. Their
magnitude depends on the lattice style due to the number of
contibuting neighbor pairs in the summation in the formula above. And
it depends on the local defects surrounding the central atom, as
described above.
Here are typical centro-symmetry values, from a a nanoindentation
simulation into gold (FCC). These were provided by Jon Zimmerman
(Sandia):
.. parsed-literal::
Bulk lattice = 0
Dislocation core ~ 1.0 (0.5 to 1.25)
Stacking faults ~ 5.0 (4.0 to 6.0)
Free surface ~ 23.0
These values are *not* normalized by the square of the lattice
parameter. If they were, normalized values would be:
.. parsed-literal::
Bulk lattice = 0
Dislocation core ~ 0.06 (0.03 to 0.075)
Stacking faults ~ 0.3 (0.24 to 0.36)
Free surface ~ 1.38
For BCC materials, the values for dislocation cores and free surfaces
would be somewhat different, due to their being only 8 neighbors instead
of 12.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute cna/atom <compute_cna_atom>`
**Default:** none
----------
.. _Kelchner:
**(Kelchner)** Kelchner, Plimpton, Hamilton, Phys Rev B, 58, 11085 (1998).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

699
doc/_sources/compute_chunk_atom.txt Normal file
View File

@ -0,0 +1,699 @@
.. index:: compute chunk/atom
compute chunk/atom command
==========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID chunk/atom style args keyword values ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* chunk/atom = style name of this compute command
.. parsed-literal::
style = *bin/1d* or *bin/2d* or *bin/3d* or *bin/sphere* or *type* or *molecule* or *compute/fix/variable*
*bin/1d* args = dim origin delta
dim = *x* or *y* or *z*
origin = *lower* or *center* or *upper* or coordinate value (distance units)
delta = thickness of spatial bins in dim (distance units)
*bin/2d* args = dim origin delta dim origin delta
dim = *x* or *y* or *z*
origin = *lower* or *center* or *upper* or coordinate value (distance units)
delta = thickness of spatial bins in dim (distance units)
*bin/3d* args = dim origin delta dim origin delta dim origin delta
dim = *x* or *y* or *z*
origin = *lower* or *center* or *upper* or coordinate value (distance units)
delta = thickness of spatial bins in dim (distance units)
*bin/sphere* args = xorig yorig zorig rmin rmax nsbin
xorig,yorig,zorig = center point of sphere
srmin,srmax = bin from sphere radius rmin to rmax
nsbin = # of spherical shell bins between rmin and rmax
*bin/cylinder* args = dim origin delta c1 c2 rmin rmax ncbin
dim = *x* or *y* or *z* = axis of cylinder axis
origin = *lower* or *center* or *upper* or coordinate value (distance units)
delta = thickness of spatial bins in dim (distance units)
c1,c2 = coords of cylinder axis in other 2 dimensions (distance units)
crmin,crmax = bin from cylinder radius rmin to rmax (distance units)
ncbin = # of concentric circle bins between rmin and rmax
*type* args = none
*molecule* args = none
*compute/fix/variable* = c_ID, c_ID[I], f_ID, f_ID[I], v_name with no args
c_ID = per-atom vector calculated by a compute with ID
c_ID[I] = Ith column of per-atom array calculated by a compute with ID
f_ID = per-atom vector calculated by a fix with ID
f_ID[I] = Ith column of per-atom array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name
* zero or more keyword/values pairs may be appended
* keyword = *region* or *nchunk* or *static* or *compress* or *bound* or *discard* or *pbc* or *units*
.. parsed-literal::
*region* value = region-ID
region-ID = ID of region atoms must be in to be part of a chunk
*nchunk* value = *once* or *every*
once = only compute the number of chunks once
every = re-compute the number of chunks whenever invoked
*limit* values = 0 or Nc max or Nc exact
0 = no limit on the number of chunks
Nc max = limit number of chunks to be <= Nc
Nc exact = set number of chunks to exactly Nc
*ids* value = *once* or *nfreq* or *every*
once = assign chunk IDs to atoms only once, they persist thereafter
nfreq = assign chunk IDs to atoms only once every Nfreq steps (if invoked by :doc:`fix ave/chunk <fix_ave_chunk>` which sets Nfreq)
every = assign chunk IDs to atoms whenever invoked
*compress* value = *yes* or *no*
yes = compress chunk IDs to eliminate IDs with no atoms
no = do not compress chunk IDs even if some IDs have no atoms
*discard* value = *yes* or *no* or *mixed*
yes = discard atoms with out-of-range chunk IDs by assigning a chunk ID = 0
no = keep atoms with out-of-range chunk IDs by assigning a valid chunk ID
mixed = keep or discard such atoms according to spatial binning rule
*bound* values = x/y/z lo hi
x/y/z = *x* or *y* or *z* to bound sptial bins in this dimension
lo = *lower* or coordinate value (distance units)
hi = *upper* or coordinate value (distance units)
*pbc* value = *no* or *yes*
yes = use periodic distance for bin/sphere and bin/cylinder styles
*units* value = *box* or *lattice* or *reduced*
Examples
""""""""
.. parsed-literal::
compute 1 all chunk/atom type
compute 1 all chunk/atom bin/1d z lower 0.02 units reduced
compute 1 all chunk/atom bin/2d z lower 1.0 y 0.0 2.5
compute 1 all chunk/atom molecule region sphere nchunk once ids once compress yes
compute 1 all chunk/atom bin/sphere 5 5 5 2.0 5.0 5 discard yes
compute 1 all chunk/atom bin/cylinder z lower 2 10 10 2.0 5.0 3 discard yes
Description
"""""""""""
Define a computation that calculates an integer chunk ID from 1 to
Nchunk for each atom in the group. Values of chunk IDs are determined
by the *style* of chunk, which can be based on atom type or molecule
ID or spatial binning or a per-atom property or value calculated by
another :doc:`compute <compute>`, :doc:`fix <fix>`, or :doc:`atom-style variable <variable>`. Per-atom chunk IDs can be used by other
computes with "chunk" in their style name, such as :doc:`compute com/chunk <compute_com_chunk>` or :doc:`compute msd/chunk <compute_msd_chunk>`. Or they can be used by the :doc:`fix ave/chunk <fix_ave_chunk>` command to sum and time average a
variety of per-atom properties over the atoms in each chunk. Or they
can simply be accessed by any command that uses per-atom values from a
compute as input, as discussed in :ref:`Section_howto 15 <howto_15>`.
See :ref:`Section_howto 23 <howto_23>` for an overview of
how this compute can be used with a variety of other commands to
tabulate properties of a simulation. The howto section gives several
examples of input script commands that can be used to calculate
interesting properties.
Conceptually it is important to realize that this compute does two
simple things. First, it sets the value of *Nchunk* = the number of
chunks, which can be a constant value or change over time. Second, it
assigns each atom to a chunk via a chunk ID. Chunk IDs range from 1
to *Nchunk* inclusive; some chunks may have no atoms assigned to them.
Atoms that do not belong to any chunk are assigned a value of 0. Note
that the two operations are not always performed together. For
example, spatial bins can be setup once (which sets *Nchunk*), and
atoms assigned to those bins many times thereafter (setting their
chunk IDs).
All other commands in LAMMPS that use chunk IDs assume there are
*Nchunk* number of chunks, and that every atom is assigned to one of
those chunks, or not assigned to any chunk.
There are many options for specifying for how and when *Nchunk* is
calculated, and how and when chunk IDs are assigned to atoms. The
details depend on the chunk *style* and its *args*, as well as
optional keyword settings. They can also depend on whether a :doc:`fix ave/chunk <fix_ave_chunk>` command is using this compute, since
that command requires *Nchunk* to remain static across windows of
timesteps it specifies, while it accumulates per-chunk averages.
The details are described below.
The different chunk styles operate as follows. For each style, how it
calculates *Nchunk* and assigns chunk IDs to atoms is explained. Note
that using the optional keywords can change both of those actions, as
described further below where the keywords are discussed.
----------
The *binning* styles perform a spatial binning of atoms, and assign an
atom the chunk ID corresponding to the bin number it is in. *Nchunk*
is set to the number of bins, which can change if the simulation box
size changes.
The *bin/1d*, *bin/2d*, and *bin/3d* styles define bins as 1d layers
(slabs), 2d pencils, or 3d boxes. The *dim*, *origin*, and *delta*
settings are specified 1, 2, or 3 times. For 2d or 3d bins, there is
no restriction on specifying dim = x before dim = y or z, or dim = y
before dim = z. Bins in a particular *dim* have a bin size in that
dimension given by *delta*. In each dimension, bins are defined
relative to a specified *origin*, which may be the lower/upper edge of
the simulation box (in that dimension), or its center point, or a
specified coordinate value. Starting at the origin, sufficient bins
are created in both directions to completely span the simulation box
or the bounds specified by the optional *bounds* keyword.
For orthogonal simulation boxes, the bins are layers, pencils, or
boxes aligned with the xyz coordinate axes. For triclinic
(non-orthogonal) simulation boxes, the bin faces are parallel to the
tilted faces of the simulation box. See :ref:`this section <howto_12>` of the manual for a discussion of
the geometry of triclinic boxes in LAMMPS. As described there, a
tilted simulation box has edge vectors a,b,c. In that nomenclature,
bins in the x dimension have faces with normals in the "b" cross "c"
direction. Bins in y have faces normal to the "a" cross "c"
direction. And bins in z have faces normal to the "a" cross "b"
direction. Note that in order to define the size and position of
these bins in an unambiguous fashion, the *units* option must be set
to *reduced* when using a triclinic simulation box, as noted below.
The meaning of *origin* and *delta* for triclinic boxes is as follows.
Consider a triclinic box with bins that are 1d layers or slabs in the
x dimension. No matter how the box is tilted, an *origin* of 0.0
means start layers at the lower "b" cross "c" plane of the simulation
box and an *origin* of 1.0 means to start layers at the upper "b"
cross "c" face of the box. A *delta* value of 0.1 in *reduced* units
means there will be 10 layers from 0.0 to 1.0, regardless of the
current size or shape of the simulation box.
The *bin/sphere* style defines a set of spherical shell bins around
the origin (*xorig*,*yorig*,*zorig*), using *nsbin* bins with radii
equally spaced between *srmin* and *srmax*. This is effectively a 1d
vector of bins. For example, if *srmin* = 1.0 and *srmax* = 10.0 and
*nsbin* = 9, then the first bin spans 1.0 < r < 2.0, and the last bin
spans 9.0 < r 10.0. The geometry of the bins is the same whether the
simulation box is orthogonal or triclinic; i.e. the spherical shells
are not tilted or scaled differently in different dimensions to
transform them into ellipsoidal shells.
The *bin/cylinder* style defines bins for a cylinder oriented along
the axis *dim* with the axis coordinates in the other two radial
dimensions at (*c1*,*c2*). For dim = x, c1/c2 = y/z; for dim = y,
c1/c2 = x/z; for dim = z, c1/c2 = x/y. This is effectively a 2d array
of bins. The first dimension is along the cylinder axis, the second
dimension is radially outward from the cylinder axis. The bin size
and positions along the cylinder axis are specified by the *origin*
and *delta* values, the same as for the *bin/1d*, *bin/2d*, and
*bin/3d* styles. There are *ncbin* concentric circle bins in the
radial direction from the cylinder axis with radii equally spaced
between *crmin* and *crmax*. For example, if *crmin* = 1.0 and
*crmax* = 10.0 and *ncbin* = 9, then the first bin spans 1.0 < r <
2.0, and the last bin spans 9.0 < r 10.0. The geometry of the bins in
the radial dimensions is the same whether the simulation box is
orthogonal or triclinic; i.e. the concetric circles are not tilted or
scaled differently in the two different dimensions to transform them
into ellipses.
The created bins (and hence the chunk IDs) are numbered consecutively
from 1 to the number of bins = *Nchunk*. For *bin2d* and *bin3d*, the
numbering varies most rapidly in the first dimension (which could be
x, y, or z), next rapidly in the 2nd dimension, and most slowly in the
3rd dimension. For *bin/sphere*, the bin with smallest radii is chunk
1 and the bni with largest radii is chunk Nchunk = *ncbin*. For
*bin/cylinder*, the numbering varies most rapidly in the dimension
along the cylinder axis and most slowly in the radial direction.
Each time this compute is invoked, each atom is mapped to a bin based
on its current position. Note that between reneighboring timesteps,
atoms can move outside the current simulation box. If the box is
periodic (in that dimension) the atom is remapping into the periodic
box for purposes of binning. If the box in not periodic, the atom may
have moved outside the bounds of all bins. If an atom is not inside
any bin, the *discard* keyword is used to determine how a chunk ID is
assigned to the atom.
----------
The *type* style uses the atom type as the chunk ID. *Nchunk* is set
to the number of atom types defined for the simulation, e.g. via the
:doc:`create_box <create_box>` or :doc:`read_data <read_data>` commands.
----------
The *molecule* style uses the molecule ID of each atom as its chunk
ID. *Nchunk* is set to the largest chunk ID. Note that this excludes
molecule IDs for atoms which are not in the specified group or
optional region.
There is no requirement that all atoms in a particular molecule are
assigned the same chunk ID (zero or non-zero), though you probably
want that to be the case, if you wish to compute a per-molecule
property. LAMMPS will issue a warning if that is not the case, but
only the first time that *Nchunk* is calculated.
Note that atoms with a molecule ID = 0, which may be non-molecular
solvent atoms, have an out-of-range chunk ID. These atoms are
discarded (not assigned to any chunk) or assigned to *Nchunk*,
depending on the value of the *discard* keyword.
----------
The *compute/fix/variable* styles set the chunk ID of each atom based
on a quantity calculated and stored by a compute, fix, or variable.
In each case, it must be a per-atom quantity. In each case the
referenced floating point values are converted to an integer chunk ID
as follows. The floating point value is truncated (rounded down) to
an integer value. If the integer value is <= 0, then a chunk ID of 0
is assigned to the atom. If the integer value is > 0, it becomes the
chunk ID to the atom. *Nchunk* is set to the largest chunk ID. Note
that this excludes atoms which are not in the specified group or
optional region.
If the style begins with "c_", a compute ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the compute is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the compute is used. Users can also write code for
their own compute styles and :doc:`add them to LAMMPS <Section_modify>`.
If the style begins with "f_", a fix ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the fix is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the fix is used. Note that some fixes only produce
their values on certain timesteps, which must be compatible with the
timestep on which this compute accesses the fix, else an error
results. Users can also write code for their own fix styles and :doc:`add them to LAMMPS <Section_modify>`.
If a value begins with "v_", a variable name for an *atom* or
*atomfile* style :doc:`variable <variable>` must follow which has been
previously defined in the input script. Variables of style *atom* can
reference thermodynamic keywords and various per-atom attributes, or
invoke other computes, fixes, or variables when they are evaluated, so
this is a very general means of generating per-atom quantities to
treat as a chunk ID.
Normally, *Nchunk* = the number of chunks, is re-calculated every time
this fix is invoked, though the value may or may not change. As
explained below, the *nchunk* keyword can be set to *once* which means
*Nchunk* will never change.
If a :doc:`fix ave/chunk <fix_ave_chunk>` command uses this compute, it
can also turn off the re-calculation of *Nchunk* for one or more
windows of timesteps. The extent of the windows, during which Nchunk
is held constant, are determined by the *Nevery*, *Nrepeat*, *Nfreq*
values and the *ave* keyword setting that are used by the :doc:`fix ave/chunk <fix_ave_chunk>` command.
Specifically, if *ave* = *one*, then for each span of *Nfreq*
timesteps, *Nchunk* is held constant between the first timestep when
averaging is done (within the Nfreq-length window), and the last
timestep when averaging is done (multiple of Nfreq). If *ave* =
*running* or *window*, then *Nchunk* is held constant forever,
starting on the first timestep when the :doc:`fix ave/chunk <fix_ave_chunk>` command invokes this compute.
Note that multiple :doc:`fix ave/chunk <fix_ave_chunk>` commands can use
the same compute chunk/atom compute. However, the time windows they
induce for holding *Nchunk* constant must be identical, else an error
will be generated.
The various optional keywords operate as follows. Note that some of
them function differently or are ignored by different chunk styles.
Some of them also have different default values, depending on
the chunk style, as listed below.
The *region* keyword applies to all chunk styles. If used, an atom
must be in both the specified group and the specified geometric
:doc:`region <region>` to be assigned to a chunk.
----------
The *nchunk* keyword applies to all chunk styles. It specifies how
often *Nchunk* is recalculated, which in turn can affect the chunk IDs
assigned to individual atoms.
If *nchunk* is set to *once*, then *Nchunk* is only calculated once,
the first time this compute is invoked. If *nchunk* is set to
*every*, then *Nchunk* is re-calculated every time the compute is
invoked. Note that, as described above, the use of this compute
by the :doc:`fix ave/chunk <fix_ave_chunk>` command can override
the *every* setting.
The default values for *nchunk* are listed below and depend on the
chunk style and other system and keyword settings. They attempt to
represent typical use cases for the various chunk styles. The
*nchunk* value can always be set explicitly if desired.
----------
The *limit* keyword can be used to limit the calculated value of
*Nchunk* = the number of chunks. The limit is applied each time
*Nchunk* is calculated, which also limits the chunk IDs assigned to
any atom. The *limit* keyword is used by all chunk styles except the
*binning* styles, which ignore it. This is because the number of bins
can be tailored using the *bound* keyword (described below) which
effectively limits the size of *Nchunk*.
If *limit* is set to *Nc* = 0, then no limit is imposed on *Nchunk*,
though the *compress* keyword can still be used to reduce *Nchunk*, as
described below.
If *Nc* > 0, then the effect of the *limit* keyword depends on whether
the *compress* keyword is also used with a setting of *yes*, and
whether the *compress* keyword is specified before the *limit* keyword
or after.
In all cases, *Nchunk* is first calculated in the usual way for each
chunk style, as described above.
First, here is what occurs if *compress yes* is not set. If *limit*
is set to *Nc max*, then *Nchunk* is reset to the smaller of *Nchunk*
and *Nc*. If *limit* is set to *Nc exact*, then *Nchunk* is reset to
*Nc*, whether the original *Nchunk* was larger or smaller than *Nc*.
If *Nchunk* shrank due to the *limit* setting, then atom chunk IDs >
*Nchunk* will be reset to 0 or *Nchunk*, depending on the setting of
the *discard* keyword. If *Nchunk* grew, there will simply be some
chunks with no atoms assigned to them.
If *compress yes* is set, and the *compress* keyword comes before the
*limit* keyword, the compression operation is performed first, as
described below, which resets *Nchunk*. The *limit* keyword is then
applied to the new *Nchunk* value, exactly as described in the
preceeding paragraph. Note that in this case, all atoms will end up
with chunk IDs <= *Nc*, but their original values (e.g. molecule ID or
compute/fix/variable value) may have been > *Nc*, because of the
compression operation.
If *compress yes* is set, and the *compress* keyword comes after the
*limit* keyword, then the *limit* value of *Nc* is applied first to
the uncompressed value of *Nchunk*, but only if *Nc* < *Nchunk*
(whether *Nc max* or *Nc exact* is used). This effectively means all
atoms with chunk IDs > *Nc* have their chunk IDs reset to 0 or *Nc*,
depending on the setting of the *discard* keyword. The compression
operation is then performed, which may shrink *Nchunk* further. If
the new *Nchunk* < *Nc* and *limit* = *Nc exact* is specified, then
*Nchunk* is reset to *Nc*, which results in extra chunks with no atoms
assigned to them. Note that in this case, all atoms will end up with
chunk IDs <= *Nc*, and their original values (e.g. molecule ID or
compute/fix/variable value) will also have been <= *Nc*.
----------
The *ids* keyword applies to all chunk styles. If the setting is
*once* then the chunk IDs assigned to atoms the first time this
compute is invoked will be permanent, and never be re-computed.
If the setting is *nfreq* and if a :doc:`fix ave/chunk <fix_ave_chunk>`
command is using this compute, then in each of the *Nchunk* = constant
time windows (discussed above), the chunk ID's assigned to atoms on
the first step of the time window will persist until the end of the
time window.
If the setting is *every*, which is the default, then chunk IDs are
re-calculated on any timestep this compute is invoked.
.. note::
If you want the persistent chunk-IDs calculated by this compute
to be continuous when running from a :doc:`restart file <read_restart>`,
then you should use the same ID for this compute, as in the original
run. This is so that the fix this compute creates to store per-atom
quantities will also have the same ID, and thus be initialized
correctly with chunk IDs from the restart file.
----------
The *compress* keyword applies to all chunk styles and affects how
*Nchunk* is calculated, which in turn affects the chunk IDs assigned
to each atom. It is useful for converting a "sparse" set of chunk IDs
(with many IDs that have no atoms assigned to them), into a "dense"
set of IDs, where every chunk has one or more atoms assigned to it.
Two possible use cases are as follows. If a large simulation box is
mostly empty space, then the *binning* style may produce many bins
with no atoms. If *compress* is set to *yes*, only bins with atoms
will be contribute to *Nchunk*. Likewise, the *molecule* or
*compute/fix/variable* styles may produce large *Nchunk* values. For
example, the :doc:`compute cluster/atom <compute_cluster_atom>` command
assigns every atom an atom ID for one of the atoms it is clustered
with. For a million-atom system with 5 clusters, there would only be
5 unique chunk IDs, but the largest chunk ID might be 1 million,
resulting in *Nchunk* = 1 million. If *compress* is set to *yes*,
*Nchunk* will be reset to 5.
If *compress* is set to *no*, which is the default, no compression is
done. If it is set to *yes*, all chunk IDs with no atoms are removed
from the list of chunk IDs, and the list is sorted. The remaining
chunk IDs are renumbered from 1 to *Nchunk* where *Nchunk* is the new
length of the list. The chunk IDs assigned to each atom reflect
the new renumbering from 1 to *Nchunk*.
The original chunk IDs (before renumbering) can be accessed by the
:doc:`compute property/chunk <compute_property_chunk>` command and its
*id* keyword, or by the :doc:`fix ave/chunk <fix_ave_chunk>` command
which outputs the original IDs as one of the columns in its global
output array. For example, using the "compute cluster/atom" command
discussed above, the original 5 unique chunk IDs might be atom IDs
(27,4982,58374,857838,1000000). After compresion, these will be
renumbered to (1,2,3,4,5). The original values (27,...,1000000) can
be output to a file by the :doc:`fix ave/chunk <fix_ave_chunk>` command,
or by using the :doc:`fix ave/time <fix_ave_time>` command in
conjunction with the :doc:`compute property/chunk <compute_property_chunk>` command.
.. note::
The compression operation requires global communication across
all processors to share their chunk ID values. It can require large
memory on every processor to store them, even after they are
compressed, if there are are a large number of unique chunk IDs with
atoms assigned to them. It uses a STL map to find unique chunk IDs
and store them in sorted order. Each time an atom is assigned a
compressed chunk ID, it must access the STL map. All of this means
that compression can be expensive, both in memory and CPU time. The
use of the *limit* keyword in conjunction with the *compress* keyword
can affect these costs, depending on which keyword is used first. So
use this option with care.
----------
The *discard* keyword applies to all chunk styles. It affects what
chunk IDs are assigned to atoms that do not match one of the valid
chunk IDs from 1 to *Nchunk*. Note that it does not apply to atoms
that are not in the specified group or optionally specified region.
Those atoms are always assigned a chunk ID = 0.
If the calculated chunk ID for an atom is not within the range 1 to
*Nchunk* then it is a "discard" atom. Note that *Nchunk* may have
been shrunk by the *limit* keyword. Or the *compress* keyword may
have eliminated chunk IDs that were valid before the compression took
place, and are now not in the compressed list. Also note that for the
*molecule* chunk style, if new molecules are added to the system,
their chunk IDs may exceed a previously calculated *Nchunk*.
Likewise, evaluation of a compute/fix/variable on a later timestep may
return chunk IDs that are invalid for the previously calculated
*Nchunk*.
All the chunk styles except the *binning* styles, must use *discard*
set to either *yes* or *no*. If *discard* is set to *yes*, which is
the default, then every "discard" atom has its chunk ID set to 0. If
*discard* is set to *no*, every "discard" atom has its chunk ID set to
*Nchunk*. I.e. it becomes part of the last chunk.
The *binning* styles use the *discard* keyword to decide whether to
discard atoms outside the spatial domain covered by bins, or to assign
them to the bin they are nearest to.
For the *bin/1d*, *bin/2d*, *bin/3d* styles the details are as
follows. If *discard* is set to *yes*, an out-of-domain atom will
have its chunk ID set to 0. If *discard* is set to *no*, the atom
will have its chunk ID set to the first or last bin in that dimension.
If *discard* is set to *mixed*, which is the default, it will only
have its chunk ID set to the first or last bin if bins extend to the
simulation box boundary in that dimension. This is the case if the
*bound* keyword settings are *lower* and *upper*, which is the
default. If the *bound* keyword settings are numeric values, then the
atom will have its chunk ID set to 0 if it is outside the bounds of
any bin. Note that in this case, it is possible that the first or
last bin extends beyond the numeric *bounds* settings, depending on
the specified *origin*. If this is the case, the chunk ID of the atom
is only set to 0 if it is outside the first or last bin, not if it is
simply outside the numeric *bounds* setting.
For the *bin/sphere* style the details are as follows. If *discard*
is set to *yes*, an out-of-domain atom will have its chunk ID set to
0. If *discard* is set to *no* or *mixed*, the atom will have its
chunk ID set to the first or last bin, i.e. the innermost or outermost
spherical shell. If the distance of the atom from the origin is less
than *rmin*, it will be assigned to the first bin. If the distance of
the atom from the origin is greater than *rmax*, it will be assigned
to the last bin.
For the *bin/cylinder* style the details are as follows. If *discard*
is set to *yes*, an out-of-domain atom will have its chunk ID set to
0. If *discard* is set to *no*, the atom will have its chunk ID set
to the first or last bin in both the radial and axis dimensions. If
*discard* is set to *mixed*, which is the default, the the radial
dimension is treated the same as for *discard* = no. But for the axis
dimensinon, it will only have its chunk ID set to the first or last
bin if bins extend to the simulation box boundary in the axis
dimension. This is the case if the *bound* keyword settings are
*lower* and *upper*, which is the default. If the *bound* keyword
settings are numeric values, then the atom will have its chunk ID set
to 0 if it is outside the bounds of any bin. Note that in this case,
it is possible that the first or last bin extends beyond the numeric
*bounds* settings, depending on the specified *origin*. If this is
the case, the chunk ID of the atom is only set to 0 if it is outside
the first or last bin, not if it is simply outside the numeric
*bounds* setting.
If *discard* is set to *no* or *mixed*, the atom will have its
chunk ID set to the first or last bin, i.e. the innermost or outermost
spherical shell. If the distance of the atom from the origin is less
than *rmin*, it will be assigned to the first bin. If the distance of
the atom from the origin is greater than *rmax*, it will be assigned
to the last bin.
----------
The *bound* keyword only applies to the *bin/1d*, *bin/2d*, *bin/3d*
styles and to the axis dimension of the *bin/cylinder* style;
otherwise it is ignored. It can be used one or more times to limit
the extent of bin coverage in a specified dimension, i.e. to only bin
a portion of the box. If the *lo* setting is *lower* or the *hi*
setting is *upper*, the bin extent in that direction extends to the
box boundary. If a numeric value is used for *lo* and/or *hi*, then
the bin extent in the *lo* or *hi* direction extends only to that
value, which is assumed to be inside (or at least near) the simulation
box boundaries, though LAMMPS does not check for this. Note that
using the *bound* keyword typically reduces the total number of bins
and thus the number of chunks *Nchunk*.
The *pbc* keyword only applies to the *bin/sphere* and *bin/cylinder*
styles. If set to *yes*, the distance an atom is from the sphere
origin or cylinder axis is calculated in a minimum image sense with
respect to periodic dimensions, when determining which bin the atom is
in. I.e. if x is a periodic dimension and the distance between the
atom and the sphere center in the x dimension is greater than 0.5 *
simulation box length in x, then a box length is subtracted to give a
distance < 0.5 * simulation box length. This allosws the sphere or
cylinder center to be near a box edge, and atoms on the other side of
the periodic box will still be close to the center point/axis. Note
that with a setting of *yes*, the outer sphere or cylinder radius must
also be <= 0.5 * simulation box length in any periodic dimension
except for the cylinder axis dimension, or an error is generated.
The *units* keyword only applies to the *binning* styles; otherwise it
is ignored. For the *bin/1d*, *bin/2d*, *bin/3d* styles, it
determines the meaning of the distance units used for the bin sizes
*delta* and for *origin* and *bounds* values if they are coordinate
values. For the *bin/sphere* style it determines the meaning of the
distance units used for *xorig*,*yorig*,*zorig* and the radii *srmin*
and *srmax*. For the *bin/cylinder* style it determines the meaning
of the distance units used for *delta*,*c1*,*c2* and the radii *crmin*
and *crmax*.
For orthogonal simulation boxes, any of the 3 options may
be used. For non-orthogonal (triclinic) simulation boxes, only the
*reduced* option may be used.
A *box* value selects standard distance units as defined by the
:doc:`units <units>` command, e.g. Angstroms for units = real or metal.
A *lattice* value means the distance units are in lattice spacings.
The :doc:`lattice <lattice>` command must have been previously used to
define the lattice spacing. A *reduced* value means normalized
unitless values between 0 and 1, which represent the lower and upper
faces of the simulation box respectively. Thus an *origin* value of
0.5 means the center of the box in any dimension. A *delta* value of
0.1 means 10 bins span the box in that dimension.
Note that for the *bin/sphere* style, the radii *srmin* and *srmax* are
scaled by the lattice spacing or reduced value of the *x* dimension.
Note that for the *bin/cylinder* style, the radii *crmin* and *crmax*
are scaled by the lattice spacing or reduced value of the 1st
dimension perpendicular to the cylinder axis. E.g. y for an x-axis
cylinder, x for a y-axis cylinder, and x for a z-axis cylinder.
----------
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The per-atom vector values are unitless chunk IDs, ranging from 1 to
*Nchunk* (inclusive) for atoms assigned to chunks, and 0 for atoms not
belonging to a chunk.
Restrictions
""""""""""""
Even if the *nchunk* keyword is set to *once*, the chunk IDs assigned
to each atom are not stored in a restart files. This means you cannot
expect those assignments to persist in a restarted simulation.
Instead you must re-specify this command and assign atoms to chunks when
the restarted simulation begins.
Related commands
""""""""""""""""
:doc:`fix ave/chunk <fix_ave_chunk>`
Default
"""""""
The option defaults are as follows:
* region = none
* nchunk = every, if compress is yes, overriding other defaults listed here
* nchunk = once, for type style
* nchunk = once, for mol style if region is none
* nchunk = every, for mol style if region is set
* nchunk = once, for binning style if the simulation box size is static or units = reduced
* nchunk = every, for binning style if the simulation box size is dynamic and units is lattice or box
* nchunk = every, for compute/fix/variable style
* limit = 0
* ids = every
* compress = no
* discard = yes, for all styles except binning
* discard = mixed, for binning styles
* bound = lower and upper in all dimensions
* pbc = no
* units = lattice
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

85
doc/_sources/compute_cluster_atom.txt Normal file
View File

@ -0,0 +1,85 @@
.. index:: compute cluster/atom
compute cluster/atom command
============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID cluster/atom cutoff
* ID, group-ID are documented in :doc:`compute <compute>` command
* cluster/atom = style name of this compute command
* cutoff = distance within which to label atoms as part of same cluster (distance units)
Examples
""""""""
.. parsed-literal::
compute 1 all cluster/atom 1.0
Description
"""""""""""
Define a computation that assigns each atom a cluster ID.
A cluster is defined as a set of atoms, each of which is within the
cutoff distance from one or more other atoms in the cluster. If an
atom has no neighbors within the cutoff distance, then it is a 1-atom
cluster. The ID of every atom in the cluster will be the smallest
atom ID of any atom in the cluster.
Only atoms in the compute group are clustered and assigned cluster
IDs. Atoms not in the compute group are assigned a cluster ID = 0.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently or to have multiple compute/dump commands, each of a
*clsuter/atom* style.
.. note::
If you have a bonded system, then the settings of
:doc:`special_bonds <special_bonds>` command can remove pairwise
interactions between atoms in the same bond, angle, or dihedral. This
is the default setting for the :doc:`special_bonds <special_bonds>`
command, and means those pairwise interactions do not appear in the
neighbor list. Because this fix uses the neighbor list, it also means
those pairs will not be included when computing the clusters. This
does not apply when using long-range coulomb (*coul/long*, *coul/msm*,
*coul/wolf* or similar. One way to get around this would be to set
special_bond scaling factors to very tiny numbers that are not exactly
zero (e.g. 1.0e-50). Another workaround is to write a dump file, and
use the :doc:`rerun <rerun>` command to compute the clusters for
snapshots in the dump file. The rerun script can use a
:doc:`special_bonds <special_bonds>` command that includes all pairs in
the neighbor list.
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The per-atom vector values will be an ID > 0, as explained above.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute coord/atom <compute_coord_atom>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

117
doc/_sources/compute_cna_atom.txt Normal file
View File

@ -0,0 +1,117 @@
.. index:: compute cna/atom
compute cna/atom command
========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID cna/atom cutoff
* ID, group-ID are documented in :doc:`compute <compute>` command
* cna/atom = style name of this compute command
* cutoff = cutoff distance for nearest neighbors (distance units)
Examples
""""""""
.. parsed-literal::
compute 1 all cna/atom 3.08
Description
"""""""""""
Define a computation that calculates the CNA (Common Neighbor
Analysis) pattern for each atom in the group. In solid-state systems
the CNA pattern is a useful measure of the local crystal structure
around an atom. The CNA methodology is described in :ref:`(Faken) <Faken>`
and :ref:`(Tsuzuki) <Tsuzuki>`.
Currently, there are five kinds of CNA patterns LAMMPS recognizes:
* fcc = 1
* hcp = 2
* bcc = 3
* icosohedral = 4
* unknown = 5
The value of the CNA pattern will be 0 for atoms not in the specified
compute group. Note that normally a CNA calculation should only be
performed on mono-component systems.
The CNA calculation can be sensitive to the specified cutoff value.
You should insure the appropriate nearest neighbors of an atom are
found within the cutoff distance for the presumed crystal strucure.
E.g. 12 nearest neighbor for perfect FCC and HCP crystals, 14 nearest
neighbors for perfect BCC crystals. These formulas can be used to
obtain a good cutoff distance:
.. image:: Eqs/cna_cutoff1.jpg
:align: center
where a is the lattice constant for the crystal structure concerned
and in the HCP case, x = (c/a) / 1.633, where 1.633 is the ideal c/a
for HCP crystals.
Also note that since the CNA calculation in LAMMPS uses the neighbors
of an owned atom to find the nearest neighbors of a ghost atom, the
following relation should also be satisfied:
.. image:: Eqs/cna_cutoff2.jpg
:align: center
where Rc is the cutoff distance of the potential, Rs is the skin
distance as specified by the :doc:`neighbor <neighbor>` command, and
cutoff is the argument used with the compute cna/atom command. LAMMPS
will issue a warning if this is not the case.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (e.g. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently or to have multiple compute/dump commands, each with a
*cna/atom* style.
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The per-atom vector values will be a number from 0 to 5, as explained
above.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute centro/atom <compute_centro_atom>`
**Default:** none
----------
.. _Faken:
**(Faken)** Faken, Jonsson, Comput Mater Sci, 2, 279 (1994).
.. _Tsuzuki:
**(Tsuzuki)** Tsuzuki, Branicio, Rino, Comput Phys Comm, 177, 518 (2007).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

67
doc/_sources/compute_com.txt Normal file
View File

@ -0,0 +1,67 @@
.. index:: compute com
compute com command
===================
Syntax
""""""
.. parsed-literal::
compute ID group-ID com
* ID, group-ID are documented in :doc:`compute <compute>` command
* com = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all com
Description
"""""""""""
Define a computation that calculates the center-of-mass of the group
of atoms, including all effects due to atoms passing thru periodic
boundaries.
A vector of three quantites is calculated by this compute, which
are the x,y,z coordinates of the center of mass.
.. note::
The coordinates of an atom contribute to the center-of-mass in
"unwrapped" form, by using the image flags associated with each atom.
See the :doc:`dump custom <dump>` command for a discussion of
"unwrapped" coordinates. See the Atoms section of the
:doc:`read_data <read_data>` command for a discussion of image flags and
how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the :doc:`set image <set>` command.
**Output info:**
This compute calculates a global vector of length 3, which can be
accessed by indices 1-3 by any command that uses global vector values
from a compute as input. See :ref:`this section <howto_15>` for an overview of LAMMPS output
options.
The vector values are "intensive". The vector values will be in
distance :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute com/chunk <compute_com_chunk>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

95
doc/_sources/compute_com_chunk.txt Normal file
View File

@ -0,0 +1,95 @@
.. index:: compute com/chunk
compute com/chunk command
=========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID com/chunk chunkID
* ID, group-ID are documented in :doc:`compute <compute>` command
* com/chunk = style name of this compute command
* chunkID = ID of :doc:`compute chunk/atom <compute_chunk_atom>` command
Examples
""""""""
.. parsed-literal::
compute 1 fluid com/chunk molchunk
Description
"""""""""""
Define a computation that calculates the center-of-mass for multiple
chunks of atoms.
In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom <compute_chunk_atom>` command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom <compute_chunk_atom>` doc page and ":ref:`Section_howto 23 <howto_23>` for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.
This compute calculates the x,y,z coordinates of the center-of-mass
for each chunk, which includes all effects due to atoms passing thru
periodic boundaries.
Note that only atoms in the specified group contribute to the
calculation. The :doc:`compute chunk/atom <compute_chunk_atom>` command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
"all" group for this command if you simply want to include atoms with
non-zero chunk IDs.
.. note::
The coordinates of an atom contribute to the chunk's
center-of-mass in "unwrapped" form, by using the image flags
associated with each atom. See the :doc:`dump custom <dump>` command
for a discussion of "unwrapped" coordinates. See the Atoms section of
the :doc:`read_data <read_data>` command for a discussion of image flags
and how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the :doc:`set image <set>` command.
The simplest way to output the results of the compute com/chunk
calculation to a file is to use the :doc:`fix ave/time <fix_ave_time>`
command, for example:
.. 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
**Output info:**
This compute calculates a global array where the number of rows = the
number of chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom <compute_chunk_atom>` command. The number of columns =
3 for the x,y,z center-of-mass coordinates of each chunk. These
values can be accessed by any command that uses global array values
from a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
The array values are "intensive". The array values will be in
distance :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute com <compute_com>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

64
doc/_sources/compute_contact_atom.txt Normal file
View File

@ -0,0 +1,64 @@
.. index:: compute contact/atom
compute contact/atom command
============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID contact/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* contact/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all contact/atom
Description
"""""""""""
Define a computation that calculates the number of contacts
for each atom in a group.
The contact number is defined for finite-size spherical particles as
the number of neighbor atoms which overlap the central particle,
meaning that their distance of separation is less than or equal to the
sum of the radii of the two particles.
The value of the contact number will be 0.0 for atoms not in the
specified compute group.
**Output info:**
This compute calculates a per-atom vector, whose values can be
accessed by any command that uses per-atom values from a compute as
input. See :ref:`Section_howto 15 <howto_15>` for an
overview of LAMMPS output options.
The per-atom vector values will be a number >= 0.0, as explained
above.
Restrictions
""""""""""""
This compute requires that atoms store a radius as defined by the
:doc:`atom_style sphere <atom_style>` command.
Related commands
""""""""""""""""
:doc:`compute coord/atom <compute_coord_atom>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

103
doc/_sources/compute_coord_atom.txt Normal file
View File

@ -0,0 +1,103 @@
.. index:: compute coord/atom
compute coord/atom command
==========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID coord/atom cutoff type1 type2 ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* coord/atom = style name of this compute command
* cutoff = distance within which to count coordination neighbors (distance units)
* typeN = atom type for Nth coordination count (see asterisk form below)
Examples
""""""""
.. parsed-literal::
compute 1 all coord/atom 2.0
compute 1 all coord/atom 6.0 1 2
compute 1 all coord/atom 6.0 2*4 5*8 *
Description
"""""""""""
Define a computation that calculates one or more coordination numbers
for each atom in a group.
A coordination number is defined as the number of neighbor atoms with
specified atom type(s) that are within the specified cutoff distance
from the central atom. Atoms not in the group are included in a
coordination number of atoms in the group.
The *typeN* keywords allow you to specify which atom types contribute
to each coordination number. One coordination number is computed for
each of the *typeN* keywords listed. If no *typeN* keywords are
listed, a single coordination number is calculated, which includes
atoms of all types (same as the "*" format, see below).
The *typeN* keywords can be specified in one of two ways. An explicit
numeric value can be used, as in the 2nd example above. Or a
wild-card asterisk can be used to specify a range of atom types. This
takes the form "*" or "*n" or "n*" or "m*n". If N = the number of
atom types, then an asterisk with no numeric values means all types
from 1 to N. A leading asterisk means all types from 1 to n
(inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive).
The value of all coordination numbers will be 0.0 for atoms not in the
specified compute group.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently.
.. note::
If you have a bonded system, then the settings of
:doc:`special_bonds <special_bonds>` command can remove pairwise
interactions between atoms in the same bond, angle, or dihedral. This
is the default setting for the :doc:`special_bonds <special_bonds>`
command, and means those pairwise interactions do not appear in the
neighbor list. Because this fix uses the neighbor list, it also means
those pairs will not be included in the coordination count. One way
to get around this, is to write a dump file, and use the
:doc:`rerun <rerun>` command to compute the coordination for snapshots
in the dump file. The rerun script can use a
:doc:`special_bonds <special_bonds>` command that includes all pairs in
the neighbor list.
**Output info:**
If single *type1* keyword is specified (or if none are specified),
this compute calculates a per-atom vector. If multiple *typeN*
keywords are specified, this compute calculates a per-atom array, with
N columns. These values can be accessed by any command that uses
per-atom values from a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
The per-atom vector or array values will be a number >= 0.0, as
explained above.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute cluster/atom <compute_cluster_atom>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

69
doc/_sources/compute_damage_atom.txt Normal file
View File

@ -0,0 +1,69 @@
.. index:: compute damage/atom
compute damage/atom command
===========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID damage/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* damage/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all damage/atom
Description
"""""""""""
Define a computation that calculates the per-atom damage for each atom
in a group. This is a quantity relevant for :doc:`Peridynamics models <pair_peri>`. See `this document <PDF/PDLammps_overview.pdf>`_
for an overview of LAMMPS commands for Peridynamics modeling.
The "damage" of a Peridymaics particles is based on the bond breakage
between the particle and its neighbors. If all the bonds are broken
the particle is considered to be fully damaged.
See the `PDLAMMPS user guide <http://www.sandia.gov/~mlparks/papers/PDLAMMPS.pdf>`_ for a formal
definition of "damage" and more details about Peridynamics as it is
implemented in LAMMPS.
This command can be used with all the Peridynamic pair styles.
The damage value will be 0.0 for atoms not in the specified compute
group.
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The per-atom vector values are unitlesss numbers (damage) >= 0.0.
Restrictions
""""""""""""
This compute is part of the PERI package. It is only enabled if
LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
Related commands
""""""""""""""""
:doc:`compute dilatation <compute_dilatation>`, :doc:`compute plasticity <compute_plasticity>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

79
doc/_sources/compute_dihedral_local.txt Normal file
View File

@ -0,0 +1,79 @@
.. index:: compute dihedral/local
compute dihedral/local command
==============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID dihedral/local input1 input2 ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* dihedral/local = style name of this compute command
* one or more keywords may be appended
* keyword = *phi*
.. parsed-literal::
*phi* = tabulate dihedral angles
Examples
""""""""
.. parsed-literal::
compute 1 all dihedral/local phi
Description
"""""""""""
Define a computation that calculates properties of individual dihedral
interactions. The number of datums generated, aggregated across all
processors, equals the number of angles in the system, modified by the
group parameter as explained below.
The local data stored by this command is generated by looping over all
the atoms owned on a processor and their dihedrals. A dihedral will
only be included if all 4 atoms in the dihedral are in the specified
compute group.
Note that as atoms migrate from processor to processor, there will be
no consistent ordering of the entries within the local vector or array
from one timestep to the next. The only consistency that is
guaranteed is that the ordering on a particular timestep will be the
same for local vectors or arrays generated by other compute commands.
For example, dihedral output from the :doc:`compute property/local <compute_property_local>` command can be combined
with data from this command and output by the :doc:`dump local <dump>`
command in a consistent way.
**Output info:**
This compute calculates a local vector or local array depending on the
number of keywords. The length of the vector or number of rows in the
array is the number of dihedrals. If a single keyword is specified, a
local vector is produced. If two or more keywords are specified, a
local array is produced where the number of columns = the number of
keywords. The vector or array can be accessed by any command that
uses local values from a compute as input. See :ref:`this section <howto_15>` for an overview of LAMMPS output
options.
The output for *phi* will be in degrees.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`dump local <dump>`, :doc:`compute property/local <compute_property_local>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

71
doc/_sources/compute_dilatation_atom.txt Normal file
View File

@ -0,0 +1,71 @@
.. index:: compute dilatation/atom
compute dilatation/atom command
===============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID dilatation/atom
* ID, group-ID are documented in compute command
* dilation/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all dilatation/atom
Description
"""""""""""
Define a computation that calculates the per-atom dilatation for each
atom in a group. This is a quantity relevant for :doc:`Peridynamics models <pair_peri>`. See `this document <PDF/PDLammps_overview.pdf>`_
for an overview of LAMMPS commands for Peridynamics modeling.
For small deformation, dilatation of is the measure of the volumetric
strain.
The dilatation "theta" for each peridynamic particle I is calculated
as a sum over its neighbors with unbroken bonds, where the
contribution of the IJ pair is a function of the change in bond length
(versus the initial length in the reference state), the volume
fraction of the particles and an influence function. See the
`PDLAMMPS user guide <http://www.sandia.gov/~mlparks/papers/PDLAMMPS.pdf>`_ for a formal
definition of dilatation.
This command can only be used with a subset of the Peridynamic :doc:`pair styles <pair_peri>`: peri/lps, peri/ves and peri/eps.
The dilatation value will be 0.0 for atoms not in the specified
compute group.
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
Section_howto 15 for an overview of LAMMPS output options.
The per-atom vector values are unitlesss numbers (theta) >= 0.0.
Restrictions
""""""""""""
This compute is part of the PERI package. It is only enabled if
LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
Related commands
""""""""""""""""
:doc:`compute damage <compute_damage>`, :doc:`compute plasticity <compute_plasticity>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

80
doc/_sources/compute_displace_atom.txt Normal file
View File

@ -0,0 +1,80 @@
.. index:: compute displace/atom
compute displace/atom command
=============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID displace/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* displace/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all displace/atom
Description
"""""""""""
Define a computation that calculates the current displacement of each
atom in the group from its original coordinates, including all effects
due to atoms passing thru periodic boundaries.
A vector of four quantites per atom is calculated by this compute.
The first 3 elements of the vector are the dx,dy,dz displacements.
The 4th component is the total displacement, i.e. sqrt(dx*dx + dy*dy +
dz*dz).
The displacement of an atom is from its original position at the time
the compute command was issued. The value of the displacement will be
0.0 for atoms not in the specified compute group.
.. note::
Initial coordinates are stored in "unwrapped" form, by using the
image flags associated with each atom. See the :doc:`dump custom <dump>` command for a discussion of "unwrapped" coordinates.
See the Atoms section of the :doc:`read_data <read_data>` command for a
discussion of image flags and how they are set for each atom. You can
reset the image flags (e.g. to 0) before invoking this compute by
using the :doc:`set image <set>` command.
.. note::
If you want the quantities calculated by this compute to be
continuous when running from a :doc:`restart file <read_restart>`, then
you should use the same ID for this compute, as in the original run.
This is so that the fix this compute creates to store per-atom
quantities will also have the same ID, and thus be initialized
correctly with time=0 atom coordinates from the restart file.
**Output info:**
This compute calculates a per-atom array with 4 columns, which can be
accessed by indices 1-4 by any command that uses per-atom values from
a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
The per-atom array values will be in distance :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute msd <compute_msd>`, :doc:`dump custom <dump>`, :doc:`fix store/state <fix_store_state>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

80
doc/_sources/compute_erotate_asphere.txt Normal file
View File

@ -0,0 +1,80 @@
.. index:: compute erotate/asphere
compute erotate/asphere command
===============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID erotate/asphere
* ID, group-ID are documented in :doc:`compute <compute>` command
* erotate/asphere = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all erotate/asphere
Description
"""""""""""
Define a computation that calculates the rotational kinetic energy of
a group of aspherical particles. The aspherical particles can be
ellipsoids, or line segments, or triangles. See the
:doc:`atom_style <atom_style>` and :doc:`read_data <read_data>` commands
for descriptions of these options.
For all 3 types of particles, the rotational kinetic energy is
computed as 1/2 I w^2, where I is the inertia tensor for the
aspherical particle and w is its angular velocity, which is computed
from its angular momentum if needed.
.. note::
For :doc:`2d models <dimension>`, ellipsoidal particles are
treated as ellipsoids, not ellipses, meaning their moments of inertia
will be the same as in 3d.
**Output info:**
This compute calculates a global scalar (the KE). This value can be
used by any command that uses a global scalar value from a compute as
input. See :ref:`Section_howto 15 <howto_15>` for an
overview of LAMMPS output options.
The scalar value calculated by this compute is "extensive". The
scalar value will be in energy :doc:`units <units>`.
Restrictions
""""""""""""
This compute requires that ellipsoidal particles atoms store a shape
and quaternion orientation and angular momentum as defined by the
:doc:`atom_style ellipsoid <atom_style>` command.
This compute requires that line segment particles atoms store a length
and orientation and angular velocity as defined by the :doc:`atom_style line <atom_style>` command.
This compute requires that triangular particles atoms store a size and
shape and quaternion orientation and angular momentum as defined by
the :doc:`atom_style tri <atom_style>` command.
All particles in the group must be finite-size. They cannot be point
particles.
**Related commands:** none
:doc:`compute erotate/sphere <compute_erotate_sphere>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

69
doc/_sources/compute_erotate_rigid.txt Normal file
View File

@ -0,0 +1,69 @@
.. index:: compute erotate/rigid
compute erotate/rigid command
=============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID erotate/rigid fix-ID
* ID, group-ID are documented in :doc:`compute <compute>` command
* erotate/rigid = style name of this compute command
* fix-ID = ID of rigid body fix
Examples
""""""""
.. parsed-literal::
compute 1 all erotate/rigid myRigid
Description
"""""""""""
Define a computation that calculates the rotational kinetic energy of
a collection of rigid bodies, as defined by one of the :doc:`fix rigid <fix_rigid>` command variants.
The rotational energy of each rigid body is computed as 1/2 I Wbody^2,
where I is the inertia tensor for the rigid body, and Wbody is its
angular velocity vector. Both I and Wbody are in the frame of
reference of the rigid body, i.e. I is diagonalized.
The *fix-ID* should be the ID of one of the :doc:`fix rigid <fix_rigid>`
commands which defines the rigid bodies. The group specified in the
compute command is ignored. The rotational energy of all the rigid
bodies defined by the fix rigid command in included in the
calculation.
**Output info:**
This compute calculates a global scalar (the summed rotational energy
of all the rigid bodies). This value can be used by any command that
uses a global scalar value from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The scalar value calculated by this compute is "extensive". The
scalar value will be in energy :doc:`units <units>`.
Restrictions
""""""""""""
This compute is part of the RIGID package. It is only enabled if
LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
Related commands
""""""""""""""""
:doc:`compute ke/rigid <compute_erotate_ke_rigid>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

69
doc/_sources/compute_erotate_sphere.txt Normal file
View File

@ -0,0 +1,69 @@
.. index:: compute erotate/sphere
compute erotate/sphere command
==============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID erotate/sphere
* ID, group-ID are documented in :doc:`compute <compute>` command
* erotate/sphere = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all erotate/sphere
Description
"""""""""""
Define a computation that calculates the rotational kinetic energy of
a group of spherical particles.
The rotational energy is computed as 1/2 I w^2, where I is the moment
of inertia for a sphere and w is the particle's angular velocity.
.. note::
For :doc:`2d models <dimension>`, particles are treated as
spheres, not disks, meaning their moment of inertia will be the same
as in 3d.
**Output info:**
This compute calculates a global scalar (the KE). This value can be
used by any command that uses a global scalar value from a compute as
input. See :ref:`Section_howto 15 <howto_15>` for an
overview of LAMMPS output options.
The scalar value calculated by this compute is "extensive". The
scalar value will be in energy :doc:`units <units>`.
Restrictions
""""""""""""
This compute requires that atoms store a radius and angular velocity
(omega) as defined by the :doc:`atom_style sphere <atom_style>` command.
All particles in the group must be finite-size spheres or point
particles. They cannot be aspherical. Point particles will not
contribute to the rotational energy.
Related commands
""""""""""""""""
:doc:`compute erotate/asphere <compute_erotate_asphere>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

65
doc/_sources/compute_erotate_sphere_atom.txt Normal file
View File

@ -0,0 +1,65 @@
.. index:: compute erotate/sphere/atom
compute erotate/sphere/atom command
===================================
Syntax
""""""
.. parsed-literal::
compute ID group-ID erotate/sphere/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* erotate/sphere/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all erotate/sphere/atom
Description
"""""""""""
Define a computation that calculates the rotational kinetic energy for
each particle in a group.
The rotational energy is computed as 1/2 I w^2, where I is the moment
of inertia for a sphere and w is the particle's angular velocity.
.. note::
For :doc:`2d models <dimension>`, particles are treated as
spheres, not disks, meaning their moment of inertia will be the same
as in 3d.
The value of the rotational kinetic energy will be 0.0 for atoms not
in the specified compute group or for point particles with a radius =
0.0.
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The per-atom vector values will be in energy :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`dump custom <dump>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

74
doc/_sources/compute_event_displace.txt Normal file
View File

@ -0,0 +1,74 @@
.. index:: compute event/displace
compute event/displace command
==============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID event/displace threshold
* ID, group-ID are documented in :doc:`compute <compute>` command
* event/displace = style name of this compute command
* threshold = minimum distance anyparticle must move to trigger an event (distance units)
Examples
""""""""
.. parsed-literal::
compute 1 all event/displace 0.5
Description
"""""""""""
Define a computation that flags an "event" if any particle in the
group has moved a distance greater than the specified threshold
distance when compared to a previously stored reference state
(i.e. the previous event). This compute is typically used in
conjunction with the :doc:`prd <prd>` and :doc:`tad <tad>` commands,
to detect if a transition
to a new minimum energy basin has occurred.
This value calculated by the compute is equal to 0 if no particle has
moved far enough, and equal to 1 if one or more particles have moved
further than the threshold distance.
.. note::
If the system is undergoing significant center-of-mass motion,
due to thermal motion, an external force, or an initial net momentum,
then this compute will not be able to distinguish that motion from
local atom displacements and may generate "false postives."
**Output info:**
This compute calculates a global scalar (the flag). This value can be
used by any command that uses a global scalar value from a compute as
input. See :ref:`Section_howto 15 <howto_15>` for an
overview of LAMMPS output options.
The scalar value calculated by this compute is "intensive". The
scalar value will be a 0 or 1 as explained above.
Restrictions
""""""""""""
This command can only be used if LAMMPS was built with the REPLICA
package. See the :ref:`Making LAMMPS <start_3>` section
for more info on packages.
Related commands
""""""""""""""""
:doc:`prd <prd>`, :doc:`tad <tad>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

315
doc/_sources/compute_fep.txt Normal file
View File

@ -0,0 +1,315 @@
.. index:: compute fep
compute fep command
===================
Syntax
""""""
.. parsed-literal::
compute ID group-ID fep temp attribute args ... keyword value ...
* ID, group-ID are documented in the :doc:`compute <compute>` command
* fep = name of this compute command
* temp = external temperature (as specified for constant-temperature run)
* one or more attributes with args may be appended
* attribute = *pair* or *atom*
.. parsed-literal::
*pair* args = pstyle pparam I J v_delta
pstyle = pair style name, e.g. lj/cut
pparam = parameter to perturb
I,J = type pair(s) to set parameter for
v_delta = variable with perturbation to apply (in the units of the parameter)
*atom* args = aparam I v_delta
aparam = parameter to perturb
I = type to set parameter for
v_delta = variable with perturbation to apply (in the units of the parameter)
* zero or more keyword/value pairs may be appended
* keyword = *tail* or *volume*
.. parsed-literal::
*tail* value = *no* or *yes*
*no* = ignore tail correction to pair energies (usually small in fep)
*yes* = include tail correction to pair energies
*volume* value = *no* or *yes*
*no* = ignore volume changes (e.g. in *NVE* or *NVT* trajectories)
*yes* = include volume changes (e.g. in *NpT* trajectories)
Examples
""""""""
.. parsed-literal::
compute 1 all fep 298 pair lj/cut epsilon 1 * v_delta pair lj/cut sigma 1 * v_delta volume yes
compute 1 all fep 300 atom charge 2 v_delta
Description
"""""""""""
Apply a perturbation to parameters of the interaction potential and
recalculate the pair potential energy without changing the atomic
coordinates from those of the reference, unperturbed system. This
compute can be used to calculate free energy differences using several
methods, such as free-energy perturbation (FEP), finite-difference
thermodynamic integration (FDTI) or Bennet's acceptance ratio method
(BAR).
The potential energy of the system is decomposed in three terms: a
background term corresponding to interaction sites whose parameters
remain constant, a reference term *U*<sub>0</sub> corresponding to the
initial interactions of the atoms that will undergo perturbation, and
a term *U*<sub>1</sub> corresponding to the final interactions of
these atoms:
.. image:: Eqs/compute_fep_u.jpg
:align: center
A coupling parameter &lambda; varying from 0 to 1 connects the
reference and perturbed systems:
.. image:: Eqs/compute_fep_lambda.jpg
:align: center
It is possible but not necessary that the coupling parameter (or a
function thereof) appears as a multiplication factor of the potential
energy. Therefore, this compute can apply perturbations to interaction
parameters that are not directly proportional to the potential energy
(e.g. &sigma; in Lennard-Jones potentials).
This command can be combined with :doc:`fix adapt <fix_adapt>` to
perform multistage free-energy perturbation calculations along
stepwise alchemical transformations during a simulation run:
.. image:: Eqs/compute_fep_fep.jpg
:align: center
This compute is suitable for the finite-difference thermodynamic
integration (FDTI) method :ref:`(Mezei) <Mezei>`, which is based on an
evaluation of the numerical derivative of the free energy by a
perturbation method using a very small &delta;:
.. image:: Eqs/compute_fep_fdti.jpg
:align: center
where *w*<sub>i</sub> are weights of a numerical quadrature. The :doc:`fix adapt <fix_adapt>` command can be used to define the stages of
&lambda; at which the derivative is calculated and averaged.
The compute fep calculates the exponential Boltzmann term and also the
potential energy difference *U*<sub>1</sub>-*U*<sub>0</sub>. By
choosing a very small perturbation &delta; the thermodynamic
integration method can be implemented using a numerical evaluation of
the derivative of the potential energy with respect to &lambda;:
.. image:: Eqs/compute_fep_ti.jpg
:align: center
Another technique to calculate free energy differences is the
acceptance ratio method :ref:`(Bennet) <Bennet>`, which can be implemented
by calculating the potential energy differences with &delta; = 1.0 on
both the forward and reverse routes:
.. image:: Eqs/compute_fep_bar.jpg
:align: center
The value of the free energy difference is determined by numerical
root finding to establish the equality.
Concerning the choice of how the atomic parameters are perturbed in
order to setup an alchemical transformation route, several strategies
are available, such as single-topology or double-topology strategies
:ref:`(Pearlman) <Pearlman>`. The latter does not require modification of
bond lengths, angles or other internal coordinates.
NOTES: This compute command does not take kinetic energy into account,
therefore the masses of the particles should not be modified between
the reference and perturbed states, or along the alchemical
transformation route. This compute command does not change bond
lengths or other internal coordinates :ref:`(Boresch, Karplus) <BoreschKarplus>`.
----------
The *pair* attribute enables various parameters of potentials defined
by the :doc:`pair_style <pair_style>` and :doc:`pair_coeff <pair_coeff>`
commands to be changed, if the pair style supports it.
The *pstyle* argument is the name of the pair style. For example,
*pstyle* could be specified as "lj/cut". The *pparam* argument is the
name of the parameter to change. This is a (non-exclusive) list of
pair styles and parameters that can be used with this compute. See
the doc pages for individual pair styles and their energy formulas for
the meaning of these parameters:
+------------------------------------------------+----------------------+------------+
| :doc:`lj/cut <pair_lj>` | epsilon,sigma | type pairs |
+------------------------------------------------+----------------------+------------+
| :doc:`lj/cut/coul/cut <pair_lj>` | epsilon,sigma | type pairs |
+------------------------------------------------+----------------------+------------+
| :doc:`lj/cut/coul/long <pair_lj>` | epsilon,sigma | type pairs |
+------------------------------------------------+----------------------+------------+
| :doc:`lj/cut/soft <pair_lj_soft>` | epsilon,sigma,lambda | type pairs |
+------------------------------------------------+----------------------+------------+
| :doc:`coul/cut/soft <pair_lj_soft>` | lambda | type pairs |
+------------------------------------------------+----------------------+------------+
| :doc:`coul/long/soft <pair_lj_soft>` | lambda | type pairs |
+------------------------------------------------+----------------------+------------+
| :doc:`lj/cut/coul/cut/soft <pair_lj_soft>` | epsilon,sigma,lambda | type pairs |
+------------------------------------------------+----------------------+------------+
| :doc:`lj/cut/coul/long/soft <pair_lj_soft>` | epsilon,sigma,lambda | type pairs |
+------------------------------------------------+----------------------+------------+
| :doc:`lj/cut/tip4p/long/soft <pair_lj_soft>` | epsilon,sigma,lambda | type pairs |
+------------------------------------------------+----------------------+------------+
| :doc:`tip4p/long/soft <pair_lj_soft>` | lambda | type pairs |
+------------------------------------------------+----------------------+------------+
| :doc:`lj/charmm/coul/long/soft <pair_lj_soft>` | epsilon,sigma,lambda | type pairs |
+------------------------------------------------+----------------------+------------+
| :doc:`born <pair_born>` | a,b,c | type pairs |
+------------------------------------------------+----------------------+------------+
| :doc:`buck <pair_buck>` | a,c | type pairs |
+------------------------------------------------+----------------------+------------+
Note that it is easy to add new potentials and their parameters to
this list. All it typically takes is adding an extract() method to
the pair_*.cpp file associated with the potential.
Similar to the :doc:`pair_coeff <pair_coeff>` command, I and J can be
specified in one of two ways. Explicit numeric values can be used for
each, as in the 1st example above. I <= J is required. LAMMPS sets
the coefficients for the symmetric J,I interaction to the same
values. A wild-card asterisk can be used in place of or in conjunction
with the I,J arguments to set the coefficients for multiple pairs of
atom types. This takes the form "*" or "*n" or "n*" or "m*n". If N =
the number of atom types, then an asterisk with no numeric values
means all types from 1 to N. A leading asterisk means all types from
1 to n (inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive). Note that only type pairs with I <= J are considered; if
asterisks imply type pairs where J < I, they are ignored.
If :doc:`pair_style hybrid or hybrid/overlay <pair_hybrid>` is being
used, then the *pstyle* will be a sub-style name. You must specify
I,J arguments that correspond to type pair values defined (via the
:doc:`pair_coeff <pair_coeff>` command) for that sub-style.
The *v_name* argument for keyword *pair* is the name of an
:doc:`equal-style variable <variable>` which will be evaluated each time
this compute is invoked. It should be specified as v_name, where name
is the variable name.
----------
The *atom* attribute enables atom properties to be changed. The
*aparam* argument is the name of the parameter to change. This is the
current list of atom parameters that can be used with this compute:
* charge = charge on particle
The *v_name* argument for keyword *pair* is the name of an
:doc:`equal-style variable <variable>` which will be evaluated each time
this compute is invoked. It should be specified as v_name, where name
is the variable name.
----------
The *tail* keyword controls the calculation of the tail correction to
"van der Waals" pair energies beyond the cutoff, if this has been
activated via the :doc:`pair_modify <pair_modify>` command. If the
perturbation is small, the tail contribution to the energy difference
between the reference and perturbed systems should be negligible.
If the keyword *volume* = *yes*, then the Boltzmann term is multiplied
by the volume so that correct ensemble averaging can be performed over
trajectories during which the volume fluctuates or changes :ref:`(Allen and Tildesley) <AllenTildesley>`:
.. image:: Eqs/compute_fep_vol.jpg
:align: center
----------
**Output info:**
This compute calculates a global vector of length 3 which contains the
energy difference (*U*<sub>1</sub>-*U*<sub>0</sub>) as c_ID[1], the
Boltzmann factor exp(-(*U*<sub>1</sub>-*U*<sub>0</sub>)/*kT*), or
*V*exp(-(*U*<sub>1</sub>-*U*<sub>0</sub>)/*kT*), as c_ID[2] and the
volume of the simulation box *V* as c_ID[3]. *U*<sub>1</sub> is the
pair potential energy obtained with the perturbed parameters and
*U*<sub>0</sub> is the pair potential energy obtained with the
unperturbed parameters. The energies include kspace terms if these
are used in the simulation.
These output results can be used by any command that uses a global
scalar or vector from a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options. For example, the computed values can be averaged using :doc:`fix ave/time <fix_ave_time>`.
The values calculated by this compute are "extensive".
Restrictions
""""""""""""
This compute is distributed as the USER-FEP package. It is only
enabled if LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
Related commands
""""""""""""""""
:doc:`fix adapt/fep <fix_adapt_fep>`, :doc:`fix ave/time <fix_ave_time>`,
`pair_lj_soft_coul_soft <pair_lj_soft_coul_soft.txt>`_
Default
"""""""
The option defaults are *tail* = *no*, *volume* = *no*.
----------
.. _Pearlman:
**(Pearlman)** Pearlman, J Chem Phys, 98, 1487 (1994)
.. _Mezei:
**(Mezei)** Mezei, J Chem Phys, 86, 7084 (1987)
.. _Bennet:
**(Bennet)** Bennet, J Comput Phys, 22, 245 (1976)
.. _BoreschKarplus:
**(BoreschKarplus)** Boresch and Karplus, J Phys Chem A, 103, 103 (1999)
.. _AllenTildesley:
**(AllenTildesley)** Allen and Tildesley, Computer Simulation of
Liquids, Oxford University Press (1987)
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

144
doc/_sources/compute_group_group.txt Normal file
View File

@ -0,0 +1,144 @@
.. index:: compute group/group
compute group/group command
===========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID group/group group2-ID keyword value ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* group/group = style name of this compute command
* group2-ID = group ID of second (or same) group
* zero or more keyword/value pairs may be appended
* keyword = *pair* or *kspace* or *boundary*
.. parsed-literal::
*pair* value = *yes* or *no*
*kspace* value = *yes* or *no*
*boundary* value = *yes* or *no*
Examples
""""""""
.. parsed-literal::
compute 1 lower group/group upper
compute 1 lower group/group upper kspace yes
compute mine fluid group/group wall
Description
"""""""""""
Define a computation that calculates the total energy and force
interaction between two groups of atoms: the compute group and the
specified group2. The two groups can be the same.
If the *pair* keyword is set to *yes*, which is the default, then the
the interaction energy will include a pair component which is defined
as the pairwise energy between all pairs of atoms where one atom in
the pair is in the first group and the other is in the second group.
Likewise, the interaction force calculated by this compute will
include the force on the compute group atoms due to pairwise
interactions with atoms in the specified group2.
If the *kspace* keyword is set to *yes*, which is not the default, and
if a :doc:`kspace_style <kspace_style>` is defined, then the interaction
energy will include a Kspace component which is the long-range
Coulombic energy between all the atoms in the first group and all the
atoms in the 2nd group. Likewise, the interaction force calculated by
this compute will include the force on the compute group atoms due to
long-range Coulombic interactions with atoms in the specified group2.
Normally the long-range Coulombic energy converges only when the net
charge of the unit cell is zero. However, one can assume the net
charge of the system is neutralized by a uniform background plasma,
and a correction to the system energy can be applied to reduce
artifacts. For more information see :ref:`(Bogusz) <Bogusz>`. If the
*boundary* keyword is set to *yes*, which is the default, and *kspace*
contributions are included, then this energy correction term will be
added to the total group-group energy. This correction term does not
affect the force calculation and will be zero if one or both of the
groups are charge neutral. This energy correction term is the same as
that included in the regular Ewald and PPPM routines.
This compute does not calculate any bond or angle or dihedral or
improper interactions between atoms in the two groups.
----------
The pairwise contributions to the group-group interactions are
calculated by looping over a neighbor list. The Kspace contribution
to the group-group interactions require essentially the same amount of
work (FFTs, Ewald summation) as computing long-range forces for the
entire system. Thus it can be costly to invoke this compute too
frequently.
If you desire a breakdown of the interactions into a pairwise and
Kspace component, simply invoke the compute twice with the appropriate
yes/no settings for the *pair* and *kspace* keywords. This is no more
costly than using a single compute with both keywords set to *yes*.
The individual contributions can be summed in a
:doc:`variable <variable>` if desired.
This `document <PDF/kspace.pdf>`_ describes how the long-range
group-group calculations are performed.
----------
**Output info:**
This compute calculates a global scalar (the energy) and a global
vector of length 3 (force), which can be accessed by indices 1-3.
These values can be used by any command that uses global scalar or
vector values from a compute as input. See :ref:`this section <howto_15>` for an overview of LAMMPS output
options.
Both the scalar and vector values calculated by this compute are
"extensive". The scalar value will be in energy :doc:`units <units>`.
The vector values will be in force :doc:`units <units>`.
Restrictions
""""""""""""
Not all pair styles can be evaluated in a pairwise mode as required by
this compute. For example, 3-body and other many-body potentials,
such as :doc:`Tersoff <pair_tersoff>` and
:doc:`Stillinger-Weber <pair_sw>` cannot be used. :doc:`EAM <pair_eam>`
potentials only include the pair potential portion of the EAM
interaction when used by this compute, not the embedding term.
Not all Kspace styles support calculation of group/group interactions.
The *ewald* and *pppm* styles do.
**Related commands:** none
Default
"""""""
The option defaults are pair = yes, kspace = no, and boundary = yes.
----------
.. _Bogusz:
Bogusz et al, J Chem Phys, 108, 7070 (1998)
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

83
doc/_sources/compute_gyration.txt Normal file
View File

@ -0,0 +1,83 @@
.. index:: compute gyration
compute gyration command
========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID gyration
* ID, group-ID are documented in :doc:`compute <compute>` command
* gyration = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 molecule gyration
Description
"""""""""""
Define a computation that calculates the radius of gyration Rg of the
group of atoms, including all effects due to atoms passing thru
periodic boundaries.
Rg is a measure of the size of the group of atoms, and is computed as
the square root of the Rg^2 value in this formula
.. image:: Eqs/compute_gyration.jpg
:align: center
where M is the total mass of the group, Rcm is the center-of-mass
position of the group, and the sum is over all atoms in the group.
A Rg^2 tensor, stored as a 6-element vector, is also calculated by
this compute. The formula for the components of the tensor is the
same as the above formula, except that (Ri - Rcm)^2 is replaced by
(Rix - Rcmx) * (Riy - Rcmy) for the xy component, etc. The 6
components of the vector are ordered xx, yy, zz, xy, xz, yz. Note
that unlike the scalar Rg, each of the 6 values of the tensor is
effectively a "squared" value, since the cross-terms may be negative
and taking a sqrt() would be invalid.
.. note::
The coordinates of an atom contribute to Rg in "unwrapped" form,
by using the image flags associated with each atom. See the :doc:`dump custom <dump>` command for a discussion of "unwrapped" coordinates.
See the Atoms section of the :doc:`read_data <read_data>` command for a
discussion of image flags and how they are set for each atom. You can
reset the image flags (e.g. to 0) before invoking this compute by
using the :doc:`set image <set>` command.
**Output info:**
This compute calculates a global scalar (Rg) and a global vector of
length 6 (Rg^2 tensor), which can be accessed by indices 1-6. These
values can be used by any command that uses a global scalar value or
vector values from a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
The scalar and vector values calculated by this compute are
"intensive". The scalar and vector values will be in distance and
distance^2 :doc:`units <units>` respectively.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute gyration/chunk <compute_gyration_chunk>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

122
doc/_sources/compute_gyration_chunk.txt Normal file
View File

@ -0,0 +1,122 @@
.. index:: compute gyration/chunk
compute gyration/chunk command
==============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID gyration/chunk chunkID keyword value ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* gyration/chunk = style name of this compute command
* chunkID = ID of :doc:`compute chunk/atom <compute_chunk_atom>` command
* zero or more keyword/value pairs may be appended
* keyword = *tensor*
.. parsed-literal::
*tensor* value = none
Examples
""""""""
.. parsed-literal::
compute 1 molecule gyration/chunk molchunk
compute 2 molecule gyration/chunk molchunk tensor
Description
"""""""""""
Define a computation that calculates the radius of gyration Rg for
multiple chunks of atoms.
In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom <compute_chunk_atom>` command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom <compute_chunk_atom>` doc page and ":ref:`Section_howto 23 <howto_23>` for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.
This compute calculates the radius of gyration Rg for each chunk,
which includes all effects due to atoms passing thru periodic
boundaries.
Rg is a measure of the size of a chunk, and is computed by this
formula
.. image:: Eqs/compute_gyration.jpg
:align: center
where M is the total mass of the chunk, Rcm is the center-of-mass
position of the chunk, and the sum is over all atoms in the
chunk.
Note that only atoms in the specified group contribute to the
calculation. The :doc:`compute chunk/atom <compute_chunk_atom>` command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
"all" group for this command if you simply want to include atoms with
non-zero chunk IDs.
If the *tensor* keyword is specified, then the scalar Rg value is not
calculated, but an Rg tensor is instead calculated for each chunk.
The formula for the components of the tensor is the same as the above
formula, except that (Ri - Rcm)^2 is replaced by (Rix - Rcmx) * (Riy -
Rcmy) for the xy component, etc. The 6 components of the tensor are
ordered xx, yy, zz, xy, xz, yz.
.. note::
The coordinates of an atom contribute to Rg in "unwrapped" form,
by using the image flags associated with each atom. See the :doc:`dump custom <dump>` command for a discussion of "unwrapped" coordinates.
See the Atoms section of the :doc:`read_data <read_data>` command for a
discussion of image flags and how they are set for each atom. You can
reset the image flags (e.g. to 0) before invoking this compute by
using the :doc:`set image <set>` command.
The simplest way to output the results of the compute gyration/chunk
calculation to a file is to use the :doc:`fix ave/time <fix_ave_time>`
command, for example:
.. parsed-literal::
compute cc1 all chunk/atom molecule
compute myChunk all gyration/chunk cc1
fix 1 all ave/time 100 1 100 c_myChunk file tmp.out mode vector
**Output info:**
This compute calculates a global vector if the *tensor* keyword is not
specified and a global array if it is. The length of the vector or
number of rows in the array = the number of chunks *Nchunk* as
calculated by the specified :doc:`compute chunk/atom <compute_chunk_atom>` command. If the *tensor* keyword
is specified, the global array has 6 columns. The vector or array can
be accessed by any command that uses global values from a compute as
input. See :ref:`this section <howto_15>` for an overview
of LAMMPS output options.
All the vector or array values calculated by this compute are
"intensive". The vector or array values will be in distance
:doc:`units <units>`, since they are the square root of values
represented by the formula above.
Restrictions
""""""""""""
none
**Related commands:** none
:doc:`compute gyration <compute_gyration>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

225
doc/_sources/compute_heat_flux.txt Normal file
View File

@ -0,0 +1,225 @@
.. index:: compute heat/flux
compute heat/flux command
=========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID heat/flux ke-ID pe-ID stress-ID
* ID, group-ID are documented in :doc:`compute <compute>` command
* heat/flux = style name of this compute command
* ke-ID = ID of a compute that calculates per-atom kinetic energy
* pe-ID = ID of a compute that calculates per-atom potential energy
* stress-ID = ID of a compute that calculates per-atom stress
Examples
""""""""
.. parsed-literal::
compute myFlux all heat/flux myKE myPE myStress
Description
"""""""""""
Define a computation that calculates the heat flux vector based on
contributions from atoms in the specified group. This can be used by
itself to measure the heat flux into or out of a reservoir of atoms,
or to calculate a thermal conductivity using the Green-Kubo formalism.
See the :doc:`fix thermal/conductivity <fix_thermal_conductivity>`
command for details on how to compute thermal conductivity in an
alternate way, via the Muller-Plathe method. See the :doc:`fix heat <fix_heat>` command for a way to control the heat added or
subtracted to a group of atoms.
The compute takes three arguments which are IDs of other
:doc:`computes <compute>`. One calculates per-atom kinetic energy
(*ke-ID*), one calculates per-atom potential energy (*pe-ID)*, and the
third calcualtes per-atom stress (*stress-ID*). These should be
defined for the same group used by compute heat/flux, though LAMMPS
does not check for this.
The Green-Kubo formulas relate the ensemble average of the
auto-correlation of the heat flux J to the thermal conductivity kappa:
.. image:: Eqs/heat_flux_J.jpg
:align: center
.. image:: Eqs/heat_flux_k.jpg
:align: center
Ei in the first term of the equation for J is the per-atom energy
(potential and kinetic). This is calculated by the computes *ke-ID*
and *pe-ID*. Si in the second term of the equation for J is the
per-atom stress tensor calculated by the compute *stress-ID*. The
tensor multiplies Vi as a 3x3 matrix-vector multiply to yield a
vector. Note that as discussed below, the 1/V scaling factor in the
equation for J is NOT included in the calculation performed by this
compute; you need to add it for a volume appropriate to the atoms
included in the calculation.
.. note::
The :doc:`compute pe/atom <compute_pe_atom>` and :doc:`compute stress/atom <compute_stress_atom>` commands have options for which
terms to include in their calculation (pair, bond, etc). The heat
flux calculation will thus include exactly the same terms. Normally
you should use :doc:`compute stress/atom virial <compute_stress_atom>`
so as not to include a kinetic energy term in the heat flux.
This compute calculates 6 quantities and stores them in a 6-component
vector. The first 3 components are the x, y, z components of the full
heat flux vector, i.e. (Jx, Jy, Jz). The next 3 components are the x,
y, z components of just the convective portion of the flux, i.e. the
first term in the equation for J above.
----------
The heat flux can be output every so many timesteps (e.g. via the
:doc:`thermo_style custom <thermo_style>` command). Then as a
post-processing operation, an autocorrelation can be performed, its
integral estimated, and the Green-Kubo formula above evaluated.
The :doc:`fix ave/correlate <fix_ave_correlate>` command can calclate
the autocorrelation. The trap() function in the
:doc:`variable <variable>` command can calculate the integral.
An example LAMMPS input script for solid Ar is appended below. The
result should be: average conductivity ~0.29 in W/mK.
----------
**Output info:**
This compute calculates a global vector of length 6 (total heat flux
vector, followed by convective heat flux vector), which can be
accessed by indices 1-6. These values can be used by any command that
uses global vector values from a compute as input. See :ref:`this section <howto_15>` for an overview of LAMMPS output
options.
The vector values calculated by this compute are "extensive", meaning
they scale with the number of atoms in the simulation. They can be
divided by the appropriate volume to get a flux, which would then be
an "intensive" value, meaning independent of the number of atoms in
the simulation. Note that if the compute is "all", then the
appropriate volume to divide by is the simulation box volume.
However, if a sub-group is used, it should be the volume containing
those atoms.
The vector values will be in energy*velocity :doc:`units <units>`. Once
divided by a volume the units will be that of flux, namely
energy/area/time :doc:`units <units>`
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`fix thermal/conductivity <fix_thermal_conductivity>`,
:doc:`fix ave/correlate <fix_ave_correlate>`,
:doc:`variable <variable>`
**Default:** none
----------
.. parsed-literal::
# Sample LAMMPS input script for thermal conductivity of solid Ar
.. parsed-literal::
units real
variable T equal 70
variable V equal vol
variable dt equal 4.0
variable p equal 200 # correlation length
variable s equal 10 # sample interval
variable d equal $p*$s # dump interval
.. parsed-literal::
# convert from LAMMPS real units to SI
.. parsed-literal::
variable kB equal 1.3806504e-23 # [J/K] Boltzmann
variable kCal2J equal 4186.0/6.02214e23
variable A2m equal 1.0e-10
variable fs2s equal 1.0e-15
variable convert equal ${kCal2J}*${kCal2J}/${fs2s}/${A2m}
.. parsed-literal::
# setup problem
.. parsed-literal::
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
.. parsed-literal::
# equilibration and thermalization
.. parsed-literal::
velocity all create $T 102486 mom yes rot yes dist gaussian
fix NVT all nvt temp $T $T 10 drag 0.2
run 8000
.. parsed-literal::
# thermal conductivity calculation, switch to NVE if desired
.. parsed-literal::
#unfix NVT
#fix NVE all nve
.. parsed-literal::
reset_timestep 0
compute myKE all ke/atom
compute myPE all pe/atom
compute myStress all stress/atom NULL virial
compute flux all heat/flux myKE myPE myStress
variable Jx equal c_flux[1]/vol
variable Jy equal c_flux[2]/vol
variable Jz equal c_flux[3]/vol
fix JJ all ave/correlate $s $p $d &
c_flux[1] c_flux[2] c_flux[3] type auto file J0Jt.dat ave running
variable scale equal ${convert}/${kB}/$T/$T/$V*$s*${dt}
variable k11 equal trap(f_JJ[3])*${scale}
variable k22 equal trap(f_JJ[4])*${scale}
variable k33 equal trap(f_JJ[5])*${scale}
thermo_style custom step temp v_Jx v_Jy v_Jz v_k11 v_k22 v_k33
run 100000
variable k equal (v_k11+v_k22+v_k33)/3.0
variable ndens equal count(all)/vol
print "average conductivity: $k[W/mK] @ $T K, ${ndens} /A^3"
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

136
doc/_sources/compute_hexorder_atom.txt Normal file
View File

@ -0,0 +1,136 @@
.. index:: compute hexorder/atom
compute hexorder/atom command
=============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID hexorder/atom keyword values ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* hexorder/atom = style name of this compute command
* one or more keyword/value pairs may be appended
.. parsed-literal::
keyword = *degree* or *nnn* or *cutoff*
*cutoff* value = distance cutoff
*nnn* value = number of nearest neighbors
*degree* value = degree *n* of order parameter
Examples
""""""""
.. parsed-literal::
compute 1 all hexorder/atom
compute 1 all hexorder/atom degree 4 nnn 4 cutoff 1.2
Description
"""""""""""
Define a computation that calculates *qn* the bond-orientational
order parameter for each atom in a group. The hexatic (*n* = 6) order
parameter was introduced by :ref:`Nelson and Halperin <Nelson>` as a way to detect
hexagonal symmetry in two-dimensional systems. For each atom, *qn*
is a complex number (stored as two real numbers) defined as follows:
.. image:: Eqs/hexorder.jpg
:align: center
where the sum is over the *nnn* nearest neighbors
of the central atom. The angle theta
is formed by the bond vector rij and the *x* axis. theta is calculated
only using the *x* and *y* components, whereas the distance from the
central atom is calculated using all three
*x*, *y*, and *z* components of the bond vector.
Neighbor atoms not in the group
are included in the order parameter of atoms in the group.
The optional keyword *cutoff* defines the distance cutoff
used when searching for neighbors. The default value, also
the maximum allowable value, is the cutoff specified
by the pair style.
The optional keyword *nnn* defines the number of nearest
neighbors used to calculate *qn*. The default value is 6.
If the value is NULL, then all neighbors up to the
distance cutoff are used.
The optional keyword *degree* sets the degree *n* of the order parameter.
The default value is 6. For a perfect hexagonal lattice with
*nnn* = 6,
*q*6 = exp(6 i phi) for all atoms, where the constant 0 < phi < pi/3
depends only on the orientation of the lattice relative to the *x* axis.
In an isotropic liquid, local neighborhoods may still exhibit
weak hexagonal symmetry, but because the orientational correlation
decays quickly with distance, the value of phi will be different for
different atoms, and so when *q*6 is averaged over all the atoms
in the system, |<*q*6>| << 1.
The value of *qn* is set to zero for atoms not in the
specified compute group, as well as for atoms that have less than
*nnn* neighbors within the distance cutoff.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently.
.. note::
If you have a bonded system, then the settings of
:doc:`special_bonds <special_bonds>` command can remove pairwise
interactions between atoms in the same bond, angle, or dihedral. This
is the default setting for the :doc:`special_bonds <special_bonds>`
command, and means those pairwise interactions do not appear in the
neighbor list. Because this fix uses the neighbor list, it also means
those pairs will not be included in the order parameter. This
difficulty can be circumvented by writing a dump file, and using the
:doc:`rerun <rerun>` command to compute the order parameter for
snapshots in the dump file. The rerun script can use a
:doc:`special_bonds <special_bonds>` command that includes all pairs in
the neighbor list.
**Output info:**
This compute calculates a per-atom array with 2 columns, giving the
real and imaginary parts *qn*, a complex number restricted to the
unit disk of the complex plane i.e. Re(*qn*)^2 + Im(*qn*)^2 <= 1 .
These values can be accessed by any command that uses
per-atom values from a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute orientorder/atom <compute_orientorder_atom>`, :doc:`compute coord/atom <compute_coord_atom>`, :doc:`compute centro/atom <compute_centro_atom>`
Default
"""""""
The option defaults are *cutoff* = pair style cutoff, *nnn* = 6, *degree* = 6
----------
.. _Nelson:
**(Nelson)** Nelson, Halperin, Phys Rev B, 19, 2457 (1979).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

79
doc/_sources/compute_improper_local.txt Normal file
View File

@ -0,0 +1,79 @@
.. index:: compute improper/local
compute improper/local command
==============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID improper/local input1 input2 ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* improper/local = style name of this compute command
* one or more keywords may be appended
* keyword = *chi*
.. parsed-literal::
*chi* = tabulate improper angles
Examples
""""""""
.. parsed-literal::
compute 1 all improper/local chi
Description
"""""""""""
Define a computation that calculates properties of individual improper
interactions. The number of datums generated, aggregated across all
processors, equals the number of impropers in the system, modified by
the group parameter as explained below.
The local data stored by this command is generated by looping over all
the atoms owned on a processor and their impropers. An improper will
only be included if all 4 atoms in the improper are in the specified
compute group.
Note that as atoms migrate from processor to processor, there will be
no consistent ordering of the entries within the local vector or array
from one timestep to the next. The only consistency that is
guaranteed is that the ordering on a particular timestep will be the
same for local vectors or arrays generated by other compute commands.
For example, improper output from the :doc:`compute property/local <compute_property_local>` command can be combined
with data from this command and output by the :doc:`dump local <dump>`
command in a consistent way.
**Output info:**
This compute calculates a local vector or local array depending on the
number of keywords. The length of the vector or number of rows in the
array is the number of impropers. If a single keyword is specified, a
local vector is produced. If two or more keywords are specified, a
local array is produced where the number of columns = the number of
keywords. The vector or array can be accessed by any command that
uses local values from a compute as input. See :ref:`this section <howto_15>` for an overview of LAMMPS output
options.
The output for *chi* will be in degrees.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`dump local <dump>`, :doc:`compute property/local <compute_property_local>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

96
doc/_sources/compute_inertia_chunk.txt Normal file
View File

@ -0,0 +1,96 @@
.. index:: compute inertia/chunk
compute inertia/chunk command
=============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID inertia/chunk chunkID
* ID, group-ID are documented in :doc:`compute <compute>` command
* inertia/chunk = style name of this compute command
* chunkID = ID of :doc:`compute chunk/atom <compute_chunk_atom>` command
Examples
""""""""
.. parsed-literal::
compute 1 fluid inertia/chunk molchunk
Description
"""""""""""
Define a computation that calculates the inertia tensor for multiple
chunks of atoms.
In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom <compute_chunk_atom>` command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom <compute_chunk_atom>` doc page and ":ref:`Section_howto 23 <howto_23>` for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.
This compute calculates the 6 components of the symmetric intertia
tensor for each chunk, ordered Ixx,Iyy,Izz,Ixy,Iyz,Ixz. The
calculation includes all effects due to atoms passing thru periodic
boundaries.
Note that only atoms in the specified group contribute to the
calculation. The :doc:`compute chunk/atom <compute_chunk_atom>` command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
"all" group for this command if you simply want to include atoms with
non-zero chunk IDs.
.. note::
The coordinates of an atom contribute to the chunk's inertia
tensor in "unwrapped" form, by using the image flags associated with
each atom. See the :doc:`dump custom <dump>` command for a discussion
of "unwrapped" coordinates. See the Atoms section of the
:doc:`read_data <read_data>` command for a discussion of image flags and
how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the :doc:`set image <set>` command.
The simplest way to output the results of the compute inertia/chunk
calculation to a file is to use the :doc:`fix ave/time <fix_ave_time>`
command, for example:
.. parsed-literal::
compute cc1 all chunk/atom molecule
compute myChunk all inertia/chunk cc1
fix 1 all ave/time 100 1 100 c_myChunk file tmp.out mode vector
**Output info:**
This compute calculates a global array where the number of rows = the
number of chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom <compute_chunk_atom>` command. The number of columns =
6 for the 6 components of the inertia tensor for each chunk, ordered
as listed above. These values can be accessed by any command that
uses global array values from a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
The array values are "intensive". The array values will be in
mass*distance^2 :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`variable inertia() function <variable>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

69
doc/_sources/compute_ke.txt Normal file
View File

@ -0,0 +1,69 @@
.. index:: compute ke
compute ke command
==================
Syntax
""""""
.. parsed-literal::
compute ID group-ID ke
* ID, group-ID are documented in :doc:`compute <compute>` command
* ke = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all ke
Description
"""""""""""
Define a computation that calculates the translational kinetic energy
of a group of particles.
The kinetic energy of each particle is computed as 1/2 m v^2, where m
and v are the mass and velocity of the particle.
There is a subtle difference between the quantity calculated by this
compute and the kinetic energy calculated by the *ke* or *etotal*
keyword used in thermodynamic output, as specified by the
:doc:`thermo_style <thermo_style>` command. For this compute, kinetic
energy is "translational" kinetic energy, calculated by the simple
formula above. For thermodynamic output, the *ke* keyword infers
kinetic energy from the temperature of the system with 1/2 Kb T of
energy for each degree of freedom. For the default temperature
computation via the :doc:`compute temp <compute_temp>` command, these
are the same. But different computes that calculate temperature can
subtract out different non-thermal components of velocity and/or
include different degrees of freedom (translational, rotational, etc).
**Output info:**
This compute calculates a global scalar (the summed KE). This value
can be used by any command that uses a global scalar value from a
compute as input. See :ref:`Section_howto 15 <howto_15>`
for an overview of LAMMPS output options.
The scalar value calculated by this compute is "extensive". The
scalar value will be in energy :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute erotate/sphere <compute_erotate_sphere>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

58
doc/_sources/compute_ke_atom.txt Normal file
View File

@ -0,0 +1,58 @@
.. index:: compute ke/atom
compute ke/atom command
=======================
Syntax
""""""
.. parsed-literal::
compute ID group-ID ke/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* ke/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all ke/atom
Description
"""""""""""
Define a computation that calculates the per-atom translational
kinetic energy for each atom in a group.
The kinetic energy is simply 1/2 m v^2, where m is the mass and v is
the velocity of each atom.
The value of the kinetic energy will be 0.0 for atoms not in the
specified compute group.
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The per-atom vector values will be in energy :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`dump custom <dump>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

88
doc/_sources/compute_ke_atom_eff.txt Normal file
View File

@ -0,0 +1,88 @@
.. index:: compute ke/atom/eff
compute ke/atom/eff command
===========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID ke/atom/eff
* ID, group-ID are documented in :doc:`compute <compute>` command
* ke/atom/eff = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all ke/atom/eff
Description
"""""""""""
Define a computation that calculates the per-atom translational
(nuclei and electrons) and radial kinetic energy (electron only) in a
group. The particles are assumed to be nuclei and electrons modeled
with the :doc:`electronic force field <pair_eff>`.
The kinetic energy for each nucleus is computed as 1/2 m v^2, where m
corresponds to the corresponding nuclear mass, and the kinetic energy
for each electron is computed as 1/2 (me v^2 + 3/4 me s^2), where me
and v correspond to the mass and translational velocity of each
electron, and s to its radial velocity, respectively.
There is a subtle difference between the quantity calculated by this
compute and the kinetic energy calculated by the *ke* or *etotal*
keyword used in thermodynamic output, as specified by the
:doc:`thermo_style <thermo_style>` command. For this compute, kinetic
energy is "translational" plus electronic "radial" kinetic energy,
calculated by the simple formula above. For thermodynamic output, the
*ke* keyword infers kinetic energy from the temperature of the system
with 1/2 Kb T of energy for each (nuclear-only) degree of freedom in
eFF.
.. note::
The temperature in eFF should be monitored via the :doc:`compute temp/eff <compute_temp_eff>` command, which can be printed with
thermodynamic output by using the :doc:`thermo_modify <thermo_modify>`
command, as shown in the following example:
.. parsed-literal::
compute effTemp all temp/eff
thermo_style custom step etotal pe ke temp press
thermo_modify temp effTemp
The value of the kinetic energy will be 0.0 for atoms (nuclei or
electrons) not in the specified compute group.
**Output info:**
This compute calculates a scalar quantity for each atom, which can be
accessed by any command that uses per-atom computes as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The per-atom vector values will be in energy :doc:`units <units>`.
Restrictions
""""""""""""
This compute is part of the USER-EFF package. It is only enabled if
LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
Related commands
""""""""""""""""
:doc:`dump custom <dump>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

87
doc/_sources/compute_ke_eff.txt Normal file
View File

@ -0,0 +1,87 @@
.. index:: compute ke/eff
compute ke/eff command
======================
Syntax
""""""
.. parsed-literal::
compute ID group-ID ke/eff
* ID, group-ID are documented in :doc:`compute <compute>` command
* ke/eff = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all ke/eff
Description
"""""""""""
Define a computation that calculates the kinetic energy of motion of a
group of eFF particles (nuclei and electrons), as modeled with the
:doc:`electronic force field <pair_eff>`.
The kinetic energy for each nucleus is computed as 1/2 m v^2 and the
kinetic energy for each electron is computed as 1/2(me v^2 + 3/4 me
s^2), where m corresponds to the nuclear mass, me to the electron
mass, v to the translational velocity of each particle, and s to the
radial velocity of the electron, respectively.
There is a subtle difference between the quantity calculated by this
compute and the kinetic energy calculated by the *ke* or *etotal*
keyword used in thermodynamic output, as specified by the
:doc:`thermo_style <thermo_style>` command. For this compute, kinetic
energy is "translational" and "radial" (only for electrons) kinetic
energy, calculated by the simple formula above. For thermodynamic
output, the *ke* keyword infers kinetic energy from the temperature of
the system with 1/2 Kb T of energy for each degree of freedom. For
the eFF temperature computation via the :doc:`compute temp_eff <compute_temp_eff>` command, these are the same. But
different computes that calculate temperature can subtract out
different non-thermal components of velocity and/or include other
degrees of freedom.
IMPRORTANT NOTE: The temperature in eFF models should be monitored via
the :doc:`compute temp/eff <compute_temp_eff>` command, which can be
printed with thermodynamic output by using the
:doc:`thermo_modify <thermo_modify>` command, as shown in the following
example:
.. parsed-literal::
compute effTemp all temp/eff
thermo_style custom step etotal pe ke temp press
thermo_modify temp effTemp
See :doc:`compute temp/eff <compute_temp_eff>`.
**Output info:**
This compute calculates a global scalar (the KE). This value can be
used by any command that uses a global scalar value from a compute as
input. See :ref:`Section_howto 15 <howto_15>` for an
overview of LAMMPS output options.
The scalar value calculated by this compute is "extensive". The
scalar value will be in energy :doc:`units <units>`.
Restrictions
""""""""""""
This compute is part of the USER-EFF package. It is only enabled if
LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
**Related commands:** none
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

67
doc/_sources/compute_ke_rigid.txt Normal file
View File

@ -0,0 +1,67 @@
.. index:: compute ke/rigid
compute ke/rigid command
========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID ke/rigid fix-ID
* ID, group-ID are documented in :doc:`compute <compute>` command
* ke = style name of this compute command
* fix-ID = ID of rigid body fix
Examples
""""""""
.. parsed-literal::
compute 1 all ke/rigid myRigid
Description
"""""""""""
Define a computation that calculates the translational kinetic energy
of a collection of rigid bodies, as defined by one of the :doc:`fix rigid <fix_rigid>` command variants.
The kinetic energy of each rigid body is computed as 1/2 M Vcm^2,
where M is the total mass of the rigid body, and Vcm is its
center-of-mass velocity.
The *fix-ID* should be the ID of one of the :doc:`fix rigid <fix_rigid>`
commands which defines the rigid bodies. The group specified in the
compute command is ignored. The kinetic energy of all the rigid
bodies defined by the fix rigid command in included in the
calculation.
**Output info:**
This compute calculates a global scalar (the summed KE of all the
rigid bodies). This value can be used by any command that uses a
global scalar value from a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
The scalar value calculated by this compute is "extensive". The
scalar value will be in energy :doc:`units <units>`.
Restrictions
""""""""""""
This compute is part of the RIGID package. It is only enabled if
LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
Related commands
""""""""""""""""
:doc:`compute erotate/rigid <compute_erotate_rigid>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

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