diff --git a/doc/html/Section_python.html b/doc/html/Section_python.html index f59ef777d..3d8acc2de 100644 --- a/doc/html/Section_python.html +++ b/doc/html/Section_python.html @@ -1,1027 +1,1027 @@ 11. Python interface to LAMMPS — LAMMPS documentation

11. Python interface to LAMMPS

LAMMPS can work together with Python in two ways. First, Python can wrap LAMMPS through the LAMMPS library interface, so that a Python script can create one or more instances of LAMMPS and launch one or more simulations. In Python lingo, this is “extending” Python with LAMMPS.

Second, LAMMPS can use the Python interpreter, so that a LAMMPS input script can invoke Python code, and pass information back-and-forth between the input script and Python functions you write. The Python code can also callback to LAMMPS to query or change its attributes. In Python lingo, this is “embedding” Python in LAMMPS.

This section describes how to do both.

If you are not familiar with it, Python is a powerful scripting and programming language which can essentially do anything that faster, lower-level languages like C or C++ can do, but typically with much fewer lines of code. When used in embedded mode, Python can perform operations that the simplistic LAMMPS input script syntax cannot. Python can be also be used as a “glue” language to drive a program through its library interface, or to hook multiple pieces of software together, such as a simulation package plus a visualization package, or to run a coupled multiscale or multiphysics model.

See Section 6.10 of the manual and the couple directory of the distribution for more ideas about coupling -LAMMPS to other codes. See Section_howto 19 for a description of the LAMMPS +LAMMPS to other codes. See Section 6.19 for a description of the LAMMPS library interface provided in src/library.cpp and src/library.h, and how to extend it for your needs. As described below, that interface is what is exposed to Python either when calling LAMMPS from Python or when calling Python from a LAMMPS input script and then calling back to LAMMPS from Python code. The library interface is designed to be easy to add functions to. Thus the Python interface to LAMMPS is also easy to extend as well.

If you create interesting Python scripts that run LAMMPS or interesting Python functions that can be called from a LAMMPS input script, that you think would be useful to other users, please email them to the developers. We can include them in the LAMMPS distribution.

11.1. Overview of running LAMMPS from Python

The LAMMPS distribution includes a python directory with all you need to run LAMMPS from Python. The python/lammps.py file wraps the LAMMPS library interface, with one wrapper function per LAMMPS library function. This file makes it is possible to do the following either from a Python script, or interactively from a Python prompt: create one or more instances of LAMMPS, invoke LAMMPS commands or give it an input script, run LAMMPS incrementally, extract LAMMPS results, an modify internal LAMMPS variables. From a Python script you can do this in serial or parallel. Running Python interactively in parallel does not generally work, unless you have a version of Python that extends standard Python to enable multiple instances of Python to read what you type.

To do all of this, you must first build LAMMPS as a shared library, then insure that your Python can find the python/lammps.py file and the shared library. These steps are explained in subsequent sections 11.3 and 11.4. Sections 11.5 and 11.6 discuss using MPI from a parallel Python program and how to test that you are ready to use LAMMPS from Python. Section 11.7 lists all the functions in the current LAMMPS library interface and how to call them from Python.

Section 11.8 gives some examples of coupling LAMMPS to other tools via Python. For example, LAMMPS can easily be coupled to a GUI or other visualization tools that display graphs or animations in real time as LAMMPS runs. Examples of such scripts are inlcluded in the python directory.

Two advantages of using Python to run LAMMPS are how concise the language is, and that it can be run interactively, enabling rapid development and debugging of programs. If you use it to mostly invoke costly operations within LAMMPS, such as running a simulation for a reasonable number of timesteps, then the overhead cost of invoking LAMMPS thru Python will be negligible.

The Python wrapper for LAMMPS uses the amazing and magical (to me) “ctypes” package in Python, which auto-generates the interface code needed between Python and a set of C interface routines for a library. Ctypes is part of standard Python for versions 2.5 and later. You can check which version of Python you have installed, by simply typing “python” at a shell prompt.

11.2. Overview of using Python from a LAMMPS script

Note

It is not currently possible to use the python command described in this section with Python 3, only with Python 2. The C API changed from Python 2 to 3 and the LAMMPS code is not compatible with both.

LAMMPS has a python command which can be used in an input script to define and execute a Python function that you write the code for. The Python function can also be assigned to a LAMMPS python-style variable via the variable command. Each time the variable is evaluated, either in the LAMMPS input script itself, or by another LAMMPS command that uses the variable, this will trigger the Python function to be invoked.

The Python code for the function can be included directly in the input script or in an auxiliary file. The function can have arguments which are mapped to LAMMPS variables (also defined in the input script) and it can return a value to a LAMMPS variable. This is thus a mechanism for your input script to pass information to a piece of Python code, ask Python to execute the code, and return information to your input script.

Note that a Python function can be arbitrarily complex. It can import other Python modules, instantiate Python classes, call other Python functions, etc. The Python code that you provide can contain more code than the single function. It can contain other functions or Python classes, as well as global variables or other mechanisms for storing state between calls from LAMMPS to the function.

The Python function you provide can consist of “pure” Python code that only performs operations provided by standard Python. However, the Python function can also “call back” to LAMMPS through its Python-wrapped library interface, in the manner described in the previous section 11.1. This means it can issue LAMMPS input script commands or query and set internal LAMMPS state. As an example, this can be useful in an input script to create a more complex loop with branching logic, than can be created using the simple looping and branching logic enabled by the next and if commands.

See the python doc page and the variable doc page for its python-style variables for more info, including examples of Python code you can write for both pure Python operations and callbacks to LAMMPS.

To run pure Python code from LAMMPS, you only need to build LAMMPS with the PYTHON package installed:

make yes-python
 make machine

Note that this will link LAMMPS with the Python library on your system, which typically requires several auxiliary system libraries to also be linked. The list of these libraries and the paths to find them are specified in the lib/python/Makefile.lammps file. You need to insure that file contains the correct information for your version of Python and your machine to successfully build LAMMPS. See the lib/python/README file for more info.

If you want to write Python code with callbacks to LAMMPS, then you must also follow the steps overviewed in the preceeding section (11.1) for running LAMMPS from Python. I.e. you must build LAMMPS as a shared library and insure that Python can find the python/lammps.py file and the shared library.

11.3. Building LAMMPS as a shared library

Instructions on how to build LAMMPS as a shared library are given in Section 2.5. A shared library is one that is dynamically loadable, which is what Python requires to wrap LAMMPS. On Linux this is a library file that ends in ”.so”, not ”.a”.

From the src directory, type

make foo mode=shlib

where foo is the machine target name, such as linux or g++ or serial. This should create the file liblammps_foo.so in the src directory, as well as a soft link liblammps.so, which is what the Python wrapper will load by default. Note that if you are building multiple machine versions of the shared library, the soft link is always set to the most recently built version.

Note

If you are building LAMMPS with an MPI or FFT library or other auxiliary libraries (used by various packages), then all of these extra libraries must also be shared libraries. If the LAMMPS shared-library build fails with an error complaining about this, see Section 2.5 for more details.

11.4. Installing the Python wrapper into Python

For Python to invoke LAMMPS, there are 2 files it needs to know about:

  • python/lammps.py
  • src/liblammps.so

Lammps.py is the Python wrapper on the LAMMPS library interface. Liblammps.so is the shared LAMMPS library that Python loads, as described above.

You can insure Python can find these files in one of two ways:

  • set two environment variables
  • run the python/install.py script

If you set the paths to these files as environment variables, you only have to do it once. For the csh or tcsh shells, add something like this to your ~/.cshrc file, one line for each of the two files:

 setenv PYTHONPATH ${PYTHONPATH}:/home/sjplimp/lammps/python
 setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src

If you use the python/install.py script, you need to invoke it every time you rebuild LAMMPS (as a shared library) or make changes to the python/lammps.py file.

You can invoke install.py from the python directory as

% python install.py [libdir] [pydir]

The optional libdir is where to copy the LAMMPS shared library to; the default is /usr/local/lib. The optional pydir is where to copy the lammps.py file to; the default is the site-packages directory of the version of Python that is running the install script.

Note that libdir must be a location that is in your default LD_LIBRARY_PATH, like /usr/local/lib or /usr/lib. And pydir must be a location that Python looks in by default for imported modules, like its site-packages dir. If you want to copy these files to non-standard locations, such as within your own user space, you will need to set your PYTHONPATH and LD_LIBRARY_PATH environment variables accordingly, as above.

If the install.py script does not allow you to copy files into system directories, prefix the python command with “sudo”. If you do this, make sure that the Python that root runs is the same as the Python you run. E.g. you may need to do something like

% sudo /usr/local/bin/python install.py [libdir] [pydir]

You can also invoke install.py from the make command in the src directory as

% make install-python

In this mode you cannot append optional arguments. Again, you may need to prefix this with “sudo”. In this mode you cannot control which Python is invoked by root.

Note that if you want Python to be able to load different versions of the LAMMPS shared library (see this section below), you will need to manually copy files like liblammps_g++.so into the appropriate system directory. This is not needed if you set the LD_LIBRARY_PATH environment variable as described above.

11.5. Extending Python with MPI to run in parallel

If you wish to run LAMMPS in parallel from Python, you need to extend your Python with an interface to MPI. This also allows you to make MPI calls directly from Python in your script, if you desire.

There are several Python packages available that purport to wrap MPI as a library and allow MPI functions to be called from Python. However, development on most of them seems to be halted except on:

Both packages, PyPar and mpi4py have been successfully tested with LAMMPS. PyPar is simpler and easy to set up and use, but supports only a subset of MPI. Mpi4py is more MPI-feature complete, but also a bit more complex to use. As of version 2.0.0, mpi4py is the only python MPI wrapper that allows passing a custom MPI communicator to the LAMMPS constructor, which means one can easily run one or more LAMMPS instances on subsets of the total MPI ranks.

PyPar requires the ubiquitous Numpy package be installed in your Python. After launching Python, type

import numpy

to see if it is installed. If not, here is how to install it (version 1.3.0b1 as of April 2009). Unpack the numpy tarball and from its top-level directory, type

python setup.py build
 sudo python setup.py install

The “sudo” is only needed if required to copy Numpy files into your Python distribution’s site-packages directory.

To install PyPar (version pypar-2.1.4_94 as of Aug 2012), unpack it and from its “source” directory, type

python setup.py build
 sudo python setup.py install

Again, the “sudo” is only needed if required to copy PyPar files into your Python distribution’s site-packages directory.

If you have successully installed PyPar, you should be able to run Python and type

import pypar

without error. You should also be able to run python in parallel on a simple test script

% mpirun -np 4 python test.py

where test.py contains the lines

import pypar
 print "Proc %d out of %d procs" % (pypar.rank(),pypar.size())

and see one line of output for each processor you run on.

Note

To use PyPar and LAMMPS in parallel from Python, you must insure both are using the same version of MPI. If you only have one MPI installed on your system, this is not an issue, but it can be if you have multiple MPIs. Your LAMMPS build is explicit about which MPI it is using, since you specify the details in your lo-level src/MAKE/Makefile.foo file. PyPar uses the “mpicc” command to find information about the MPI it uses to build against. And it tries to load “libmpi.so” from the LD_LIBRARY_PATH. This may or may not find the MPI library that LAMMPS is using. If you have problems running both PyPar and LAMMPS together, this is an issue you may need to address, e.g. by moving other MPI installations so that PyPar finds the right one.

To install mpi4py (version mpi4py-2.0.0 as of Oct 2015), unpack it and from its main directory, type

python setup.py build
 sudo python setup.py install

Again, the “sudo” is only needed if required to copy mpi4py files into your Python distribution’s site-packages directory. To install with user privilege into the user local directory type

python setup.py install --user

If you have successully installed mpi4py, you should be able to run Python and type

from mpi4py import MPI

without error. You should also be able to run python in parallel on a simple test script

% mpirun -np 4 python test.py

where test.py contains the lines

 from mpi4py import MPI
 comm = MPI.COMM_WORLD
 print "Proc %d out of %d procs" % (comm.Get_rank(),comm.Get_size())

and see one line of output for each processor you run on.

Note

To use mpi4py and LAMMPS in parallel from Python, you must insure both are using the same version of MPI. If you only have one MPI installed on your system, this is not an issue, but it can be if you have multiple MPIs. Your LAMMPS build is explicit about which MPI it is using, since you specify the details in your lo-level src/MAKE/Makefile.foo file. Mpi4py uses the “mpicc” command to find information about the MPI it uses to build against. And it tries to load “libmpi.so” from the LD_LIBRARY_PATH. This may or may not find the MPI library that LAMMPS is using. If you have problems running both mpi4py and LAMMPS together, this is an issue you may need to address, e.g. by moving other MPI installations so that mpi4py finds the right one.

11.6. Testing the Python-LAMMPS interface

To test if LAMMPS is callable from Python, launch Python interactively and type:

>>> from lammps import lammps
 >>> lmp = lammps()

If you get no errors, you’re ready to use LAMMPS from Python. If the 2nd command fails, the most common error to see is

OSError: Could not load LAMMPS dynamic library

which means Python was unable to load the LAMMPS shared library. This typically occurs if the system can’t find the LAMMPS shared library or one of the auxiliary shared libraries it depends on, or if something about the library is incompatible with your Python. The error message should give you an indication of what went wrong.

You can also test the load directly in Python as follows, without first importing from the lammps.py file:

>>> from ctypes import CDLL
 >>> CDLL("liblammps.so")

If an error occurs, carefully go thru the steps in Section 2.5 and above about building a shared library and about insuring Python can find the necessary two files it needs.

11.6.1. Test LAMMPS and Python in serial:

To run a LAMMPS test in serial, type these lines into Python interactively from the bench directory:

>>> from lammps import lammps
 >>> lmp = lammps()
 >>> lmp.file("in.lj")

Or put the same lines in the file test.py and run it as

% python test.py

Either way, you should see the results of running the in.lj benchmark on a single processor appear on the screen, the same as if you had typed something like:

 lmp_g++ -in in.lj

11.6.2. Test LAMMPS and Python in parallel:

To run LAMMPS in parallel, assuming you have installed the PyPar package as discussed above, create a test.py file containing these lines:

import pypar
 from lammps import lammps
 lmp = lammps()
 lmp.file("in.lj")
 print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()),lmp
 pypar.finalize()

To run LAMMPS in parallel, assuming you have installed the mpi4py package as discussed above, create a test.py file containing these lines:

 from mpi4py import MPI
 from lammps import lammps
 lmp = lammps()
 lmp.file("in.lj")
 me = MPI.COMM_WORLD.Get_rank()
 nprocs = MPI.COMM_WORLD.Get_size()
 print "Proc %d out of %d procs has" % (me,nprocs),lmp
 MPI.Finalize()

You can either script in parallel as:

% mpirun -np 4 python test.py

and you should see the same output as if you had typed

 % mpirun -np 4 lmp_g++ -in in.lj

Note that if you leave out the 3 lines from test.py that specify PyPar commands you will instantiate and run LAMMPS independently on each of the P processors specified in the mpirun command. In this case you should get 4 sets of output, each showing that a LAMMPS run was made on a single processor, instead of one set of output showing that LAMMPS ran on 4 processors. If the 1-processor outputs occur, it means that PyPar is not working correctly.

Also note that once you import the PyPar module, PyPar initializes MPI for you, and you can use MPI calls directly in your Python script, as described in the PyPar documentation. The last line of your Python script should be pypar.finalize(), to insure MPI is shut down correctly.

11.6.3. Running Python scripts:

Note that any Python script (not just for LAMMPS) can be invoked in one of several ways:

% python foo.script
 % python -i foo.script
 % foo.script

The last command requires that the first line of the script be something like this:

#!/usr/local/bin/python
 #!/usr/local/bin/python -i

where the path points to where you have Python installed, and that you have made the script file executable:

% chmod +x foo.script

Without the “-i” flag, Python will exit when the script finishes. With the “-i” flag, you will be left in the Python interpreter when the script finishes, so you can type subsequent commands. As mentioned above, you can only run Python interactively when running Python on a single processor, not in parallel.

11.7. Using LAMMPS from Python

As described above, the Python interface to LAMMPS consists of a Python “lammps” module, the source code for which is in python/lammps.py, which creates a “lammps” object, with a set of methods that can be invoked on that object. The sample Python code below assumes you have first imported the “lammps” module in your Python script, as follows:

from lammps import lammps

These are the methods defined by the lammps module. If you look at the files src/library.cpp and src/library.h you will see that they correspond one-to-one with calls you can make to the LAMMPS library from a C++ or C or Fortran program.

 lmp = lammps()           # create a LAMMPS object using the default liblammps.so library
                          4 optional args are allowed: name, cmdargs, ptr, comm
 lmp = lammps(ptr=lmpptr) # use lmpptr as previously created LAMMPS object
 lmp = lammps(comm=split) # create a LAMMPS object with a custom communicator, requires mpi4py 2.0.0 or later
 lmp = lammps(name="g++")   # create a LAMMPS object using the liblammps_g++.so library
 lmp = lammps(name="g++",cmdargs=list)    # add LAMMPS command-line args, e.g. list = ["-echo","screen"]
 
lmp.close()              # destroy a LAMMPS object

version = lmp.version() # return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902

lmp.file(file)           # run an entire input script, file = "in.lj"
 lmp.command(cmd)         # invoke a single LAMMPS command, cmd = "run 100"
 
 xlo = lmp.extract_global(name,type)  # extract a global quantity
                                      # name = "boxxlo", "nlocal", etc
                                   # type = 0 = int
                                   #        1 = double
 
 coords = lmp.extract_atom(name,type)      # extract a per-atom quantity
                                           # name = "x", "type", etc
                                        # type = 0 = vector of ints
                                        #        1 = array of ints
                                        #        2 = vector of doubles
                                        #        3 = array of doubles
 
 eng = lmp.extract_compute(id,style,type)  # extract value(s) from a compute
 v3 = lmp.extract_fix(id,style,type,i,j)   # extract value(s) from a fix
                                           # id = ID of compute or fix
                                        # style = 0 = global data
                                        #         1 = per-atom data
                                        #         2 = local data
                                        # type = 0 = scalar
                                        #        1 = vector
                                        #        2 = array
                                        # i,j = indices of value in global vector or array
 
 var = lmp.extract_variable(name,group,flag)  # extract value(s) from a variable
                                           # name = name of variable
                                           # group = group ID (ignored for equal-style variables)
                                           # flag = 0 = equal-style variable
                                           #        1 = atom-style variable
 
 flag = lmp.set_variable(name,value)       # set existing named string-style variable to value, flag = 0 if successful
 natoms = lmp.get_natoms()                 # total # of atoms as int
 data = lmp.gather_atoms(name,type,count)  # return atom attribute of all atoms gathered into data, ordered by atom ID
                                           # name = "x", "charge", "type", etc
                                           # count = # of per-atom values, 1 or 3, etc
 lmp.scatter_atoms(name,type,count,data)   # scatter atom attribute of all atoms from data, ordered by atom ID
                                           # name = "x", "charge", "type", etc
                                           # count = # of per-atom values, 1 or 3, etc

The lines

from lammps import lammps
 lmp = lammps()

create an instance of LAMMPS, wrapped in a Python class by the lammps Python module, and return an instance of the Python class as lmp. It is used to make all subequent calls to the LAMMPS library.

Additional arguments can be used to tell Python the name of the shared library to load or to pass arguments to the LAMMPS instance, the same as if LAMMPS were launched from a command-line prompt.

If the ptr argument is set like this:

lmp = lammps(ptr=lmpptr)

then lmpptr must be an argument passed to Python via the LAMMPS python command, when it is used to define a Python function that is invoked by the LAMMPS input script. This mode of using Python with LAMMPS is described above in 11.2. The variable lmpptr refers to the instance of LAMMPS that called the embedded Python interpreter. Using it as an argument to lammps() allows the returned Python class instance “lmp” to make calls to that instance of LAMMPS. See the python command doc page for examples using this syntax.

Note that you can create multiple LAMMPS objects in your Python script, and coordinate and run multiple simulations, e.g.

from lammps import lammps
 lmp1 = lammps()
 lmp2 = lammps()
 lmp1.file("in.file1")
 lmp2.file("in.file2")

The file() and command() methods allow an input script or single commands to be invoked.

The extract_global(), extract_atom(), extract_compute(), extract_fix(), and extract_variable() methods return values or pointers to data structures internal to LAMMPS.

For extract_global() see the src/library.cpp file for the list of valid names. New names could easily be added. A double or integer is returned. You need to specify the appropriate data type via the type argument.

For extract_atom(), a pointer to internal LAMMPS atom-based data is returned, which you can use via normal Python subscripting. See the extract() method in the src/atom.cpp file for a list of valid names. Again, new names could easily be added. A pointer to a vector of doubles or integers, or a pointer to an array of doubles (double **) or integers (int **) is returned. You need to specify the appropriate data type via the type argument.

For extract_compute() and extract_fix(), the global, per-atom, or local data calulated by the compute or fix can be accessed. What is returned depends on whether the compute or fix calculates a scalar or vector or array. For a scalar, a single double value is returned. If the compute or fix calculates a vector or array, a pointer to the internal LAMMPS data is returned, which you can use via normal Python subscripting. The one exception is that for a fix that calculates a global vector or array, a single double value from the vector or array is returned, indexed by I (vector) or I and J (array). I,J are zero-based indices. The I,J arguments can be left out if not needed. See Section 6.15 of the manual for a discussion of global, per-atom, and local data, and of scalar, vector, and array data types. See the doc pages for individual computes and fixes for a description of what they calculate and store.

For extract_variable(), an equal-style or atom-style variable is evaluated and its result returned.

For equal-style variables a single double value is returned and the group argument is ignored. For atom-style variables, a vector of doubles is returned, one value per atom, which you can use via normal Python subscripting. The values will be zero for atoms not in the specified group.

The get_natoms() method returns the total number of atoms in the simulation, as an int.

The gather_atoms() method returns a ctypes vector of ints or doubles as specified by type, of length count*natoms, for the property of all the atoms in the simulation specified by name, ordered by count and then by atom ID. The vector can be used via normal Python subscripting. If atom IDs are not consecutively ordered within LAMMPS, a None is returned as indication of an error.

Note that the data structure gather_atoms(“x”) returns is different from the data structure returned by extract_atom(“x”) in four ways. (1) Gather_atoms() returns a vector which you index as x[i]; extract_atom() returns an array which you index as x[i][j]. (2) Gather_atoms() orders the atoms by atom ID while extract_atom() does not. (3) Gathert_atoms() returns a list of all atoms in the simulation; extract_atoms() returns just the atoms local to each processor. (4) Finally, the gather_atoms() data structure is a copy of the atom coords stored internally in LAMMPS, whereas extract_atom() returns an array that effectively points directly to the internal data. This means you can change values inside LAMMPS from Python by assigning a new values to the extract_atom() array. To do this with the gather_atoms() vector, you need to change values in the vector, then invoke the scatter_atoms() method.

The scatter_atoms() method takes a vector of ints or doubles as specified by type, of length count*natoms, for the property of all the atoms in the simulation specified by name, ordered by bount and then by atom ID. It uses the vector of data to overwrite the corresponding properties for each atom inside LAMMPS. This requires LAMMPS to have its “map” option enabled; see the atom_modify command for details. If it is not, or if atom IDs are not consecutively ordered, no coordinates are reset.

The array of coordinates passed to scatter_atoms() must be a ctypes vector of ints or doubles, allocated and initialized something like this:

 from ctypes import *
 natoms = lmp.get_natoms()
 n3 = 3*natoms
 x = (n3*c_double)()
 x[0] = x coord of atom with ID 1
 x[1] = y coord of atom with ID 1
 x[2] = z coord of atom with ID 1
 x[3] = x coord of atom with ID 2
 ...
 x[n3-1] = z coord of atom with ID natoms
 lmp.scatter_coords("x",1,3,x)

Alternatively, you can just change values in the vector returned by gather_atoms(“x”,1,3), since it is a ctypes vector of doubles.

As noted above, these Python class methods correspond one-to-one with the functions in the LAMMPS library interface in src/library.cpp and library.h. This means you can extend the Python wrapper via the following steps:

  • Add a new interface function to src/library.cpp and src/library.h.
  • Rebuild LAMMPS as a shared library.
  • Add a wrapper method to python/lammps.py for this interface function.
  • You should now be able to invoke the new interface function from a Python script. Isn’t ctypes amazing?

11.8. Example Python scripts that use LAMMPS

These are the Python scripts included as demos in the python/examples directory of the LAMMPS distribution, to illustrate the kinds of things that are possible when Python wraps LAMMPS. If you create your own scripts, send them to us and we can include them in the LAMMPS distribution.

trivial.py read/run a LAMMPS input script thru Python
demo.py invoke various LAMMPS library interface routines
simple.py run in parallel
similar to examples/COUPLE/simple/simple.cpp split.py
same as simple.py but running in parallel on a subset of procs gui.py
GUI go/stop/temperature-slider to control LAMMPS plot.py
real-time temeperature plot with GnuPlot via Pizza.py viz_tool.py
real-time viz via some viz package vizplotgui_tool.py
combination of viz_tool.py and plot.py and gui.py  

For the viz_tool.py and vizplotgui_tool.py commands, replace “tool” with “gl” or “atomeye” or “pymol” or “vmd”, depending on what visualization package you have installed.

Note that for GL, you need to be able to run the Pizza.py GL tool, which is included in the pizza sub-directory. See the Pizza.py doc pages for more info:

Note that for AtomEye, you need version 3, and there is a line in the scripts that specifies the path and name of the executable. See the AtomEye WWW pages here or here for more details:

http://mt.seas.upenn.edu/Archive/Graphics/A
 http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html

The latter link is to AtomEye 3 which has the scriping capability needed by these Python scripts.

Note that for PyMol, you need to have built and installed the open-source version of PyMol in your Python, so that you can import it from a Python script. See the PyMol WWW pages here or here for more details:

 http://www.pymol.org
 http://sourceforge.net/scm/?type=svn&group_id=4546

The latter link is to the open-source version.

Note that for VMD, you need a fairly current version (1.8.7 works for me) and there are some lines in the pizza/vmd.py script for 4 PIZZA variables that have to match the VMD installation on your system.

See the python/README file for instructions on how to run them and the source code for individual scripts for comments about what they do.

Here are screenshots of the vizplotgui_tool.py script in action for different visualization package options. Click to see larger images:

\ No newline at end of file diff --git a/doc/html/Section_start.html b/doc/html/Section_start.html index f01f969f7..bc1af70cd 100644 --- a/doc/html/Section_start.html +++ b/doc/html/Section_start.html @@ -1,2043 +1,2043 @@ 2. Getting Started — LAMMPS documentation

2. Getting Started

This section describes how to build and run LAMMPS, for both new and experienced users.

2.1 What’s in the LAMMPS distribution
2.2 Making LAMMPS
2.3 Making LAMMPS with optional packages
2.4 Building LAMMPS via the Make.py script
2.5 Building LAMMPS as a library
2.6 Running LAMMPS
2.7 Command-line options
2.8 Screen output
2.9 Tips for users of previous versions

2.1. What’s in the LAMMPS distribution

When you download a LAMMPS tarball you will need to unzip and untar the downloaded file with the following commands, after placing the tarball in an appropriate directory.

 tar -xzvf lammps*.tar.gz

This will create a LAMMPS directory containing two files and several sub-directories:

README text file
LICENSE the GNU General Public License (GPL)
bench benchmark problems
doc documentation
examples simple test problems
potentials embedded atom method (EAM) potential files
src source files
tools pre- and post-processing tools

Note that the download page also has links to download pre-build Windows installers, as well as pre-built packages for several widely used Linux distributions. It also has instructions for how to download/install LAMMPS for Macs (via Homebrew), and to download and update LAMMPS from SVN and Git repositories, which gives you access to the up-to-date sources that are used by the LAMMPS core developers.

The Windows and Linux packages for serial or parallel include only selected packages and bug-fixes/upgrades listed on this page up to a certain date, as stated on the download page. If you want an executable with non-included packages or that is more current, then you’ll need to build LAMMPS yourself, as discussed in the next section.

Skip to the Running LAMMPS sections for info on how to launch a LAMMPS Windows executable on a Windows box.

2.2. Making LAMMPS

This section has the following sub-sections:

2.2.1. Read this first

If you want to avoid building LAMMPS yourself, read the preceeding section about options available for downloading and installing executables. Details are discussed on the download page.

Building LAMMPS can be simple or not-so-simple. If all you need are the default packages installed in LAMMPS, and MPI is already installed on your machine, or you just want to run LAMMPS in serial, then you can typically use the Makefile.mpi or Makefile.serial files in src/MAKE by typing one of these lines (from the src dir):

make mpi
 make serial

Note that on a facility supercomputer, there are often “modules” loaded in your environment that provide the compilers and MPI you should use. In this case, the “mpicxx” compile/link command in Makefile.mpi should just work by accessing those modules.

It may be the case that one of the other Makefile.machine files in the src/MAKE sub-directories is a better match to your system (type “make” to see a list), you can use it as-is by typing (for example):

make stampede

If any of these builds (with an existing Makefile.machine) works on your system, then you’re done!

If you want to do one of the following:

  • use optional LAMMPS features that require additional libraries
  • use optional packages that require additional libraries
  • use optional accelerator packages that require special compiler/linker settings
  • run on a specialized platform that has its own compilers, settings, or other libs to use

then building LAMMPS is more complicated. You may need to find where auxiliary libraries exist on your machine or install them if they don’t. You may need to build additional libraries that are part of the LAMMPS package, before building LAMMPS. You may need to edit a Makefile.machine file to make it compatible with your system.

Note that there is a Make.py tool in the src directory that automates several of these steps, but you still have to know what you are doing. Section 2.4 below describes the tool. It is a convenient way to work with installing/un-installing various packages, the Makefile.machine changes required by some packages, and the auxiliary libraries some of them use.

Please read the following sections carefully. If you are not comfortable with makefiles, or building codes on a Unix platform, or running an MPI job on your machine, please find a local expert to help you. Many compilation, linking, and run problems that users have are often not really LAMMPS issues - they are peculiar to the user’s system, compilers, libraries, etc. Such questions are better answered by a local expert.

If you have a build problem that you are convinced is a LAMMPS issue (e.g. the compiler complains about a line of LAMMPS source code), then please post the issue to the LAMMPS mail list.

If you succeed in building LAMMPS on a new kind of machine, for which there isn’t a similar machine Makefile included in the src/MAKE/MACHINES directory, then send it to the developers and we can include it in the LAMMPS distribution.

2.2.2. Steps to build a LAMMPS executable

2.2.2.1. Step 0

The src directory contains the C++ source and header files for LAMMPS. It also contains a top-level Makefile and a MAKE sub-directory with low-level Makefile.* files for many systems and machines. See the src/MAKE/README file for a quick overview of what files are available and what sub-directories they are in.

The src/MAKE dir has a few files that should work as-is on many platforms. The src/MAKE/OPTIONS dir has more that invoke additional compiler, MPI, and other setting options commonly used by LAMMPS, to illustrate their syntax. The src/MAKE/MACHINES dir has many more that have been tweaked or optimized for specific machines. These files are all good starting points if you find you need to change them for your machine. Put any file you edit into the src/MAKE/MINE directory and it will be never be touched by any LAMMPS updates.

>From within the src directory, type “make” or “gmake”. You should see a list of available choices from src/MAKE and all of its sub-directories. If one of those has the options you want or is the machine you want, you can type a command like:

make mpi

or

make serial

or

gmake mac

Note that the corresponding Makefile.machine can exist in src/MAKE or any of its sub-directories. If a file with the same name appears in multiple places (not a good idea), the order they are used is as follows: src/MAKE/MINE, src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives preference to a file you have created/edited and put in src/MAKE/MINE.

Note that on a multi-processor or multi-core platform you can launch a parallel make, by using the “-j” switch with the make command, which will build LAMMPS more quickly.

If you get no errors and an executable like lmp_mpi or lmp_serial or lmp_mac is produced, then you’re done; it’s your lucky day.

Note that by default only a few of LAMMPS optional packages are installed. To build LAMMPS with optional packages, see this section below.

2.2.2.2. Step 1

If Step 0 did not work, you will need to create a low-level Makefile for your machine, like Makefile.foo. You should make a copy of an existing Makefile.* in src/MAKE or one of its sub-directories as a starting point. The only portions of the file you need to edit are the first line, the “compiler/linker settings” section, and the “LAMMPS-specific settings” section. When it works, put the edited file in src/MAKE/MINE and it will not be altered by any future LAMMPS updates.

2.2.2.3. Step 2

Change the first line of Makefile.foo to list the word “foo” after the “#”, and whatever other options it will set. This is the line you will see if you just type “make”.

2.2.2.4. Step 3

The “compiler/linker settings” section lists compiler and linker settings for your C++ compiler, including optimization flags. You can use g++, the open-source GNU compiler, which is available on all Unix systems. You can also use mpicxx which will typically be available if MPI is installed on your system, though you should check which actual compiler it wraps. Vendor compilers often produce faster code. On boxes with Intel CPUs, we suggest using the Intel icc compiler, which can be downloaded from Intel’s compiler site.

If building a C++ code on your machine requires additional libraries, then you should list them as part of the LIB variable. You should not need to do this if you use mpicxx.

The DEPFLAGS setting is what triggers the C++ compiler to create a dependency list for a source file. This speeds re-compilation when source (*.cpp) or header (*.h) files are edited. Some compilers do not support dependency file creation, or may use a different switch than -D. GNU g++ and Intel icc works with -D. If your compiler can’t create dependency files, then you’ll need to create a Makefile.foo patterned after Makefile.storm, which uses different rules that do not involve dependency files. Note that when you build LAMMPS for the first time on a new platform, a long list of *.d files will be printed out rapidly. This is not an error; it is the Makefile doing its normal creation of dependencies.

2.2.2.5. Step 4

The “system-specific settings” section has several parts. Note that if you change any -D setting in this section, you should do a full re-compile, after typing “make clean” (which will describe different clean options).

The LMP_INC variable is used to include options that turn on ifdefs within the LAMMPS code. The options that are currently recogized are:

  • -DLAMMPS_GZIP
  • -DLAMMPS_JPEG
  • -DLAMMPS_PNG
  • -DLAMMPS_FFMPEG
  • -DLAMMPS_MEMALIGN
  • -DLAMMPS_XDR
  • -DLAMMPS_SMALLBIG
  • -DLAMMPS_BIGBIG
  • -DLAMMPS_SMALLSMALL
  • -DLAMMPS_LONGLONG_TO_LONG
  • -DLAMMPS_EXCEPTIONS
  • -DPACK_ARRAY
  • -DPACK_POINTER
  • -DPACK_MEMCPY

The read_data and dump commands will read/write gzipped files if you compile with -DLAMMPS_GZIP. It requires that your machine supports the “popen()” function in the standard runtime library and that a gzip executable can be found by LAMMPS during a run.

Note

on some clusters with high-speed networks, using the fork() library calls (required by popen()) can interfere with the fast communication library and lead to simulations using compressed output or input to hang or crash. For selected operations, compressed file I/O is also available using a compression library instead, which are provided in the COMPRESS package. From more details about compiling LAMMPS with packages, please see below.

If you use -DLAMMPS_JPEG, the dump image command will be able to write out JPEG image files. For JPEG files, you must also link LAMMPS with a JPEG library, as described below. If you use -DLAMMPS_PNG, the dump image command will be able to write out PNG image files. For PNG files, you must also link LAMMPS with a PNG library, as described below. If neither of those two defines are used, LAMMPS will only be able to write out uncompressed PPM image files.

If you use -DLAMMPS_FFMPEG, the dump movie command will be available to support on-the-fly generation of rendered movies the need to store intermediate image files. It requires that your machines supports the “popen” function in the standard runtime library and that an FFmpeg executable can be found by LAMMPS during the run.

Note

Similar to the note above, this option can conflict with high-speed networks, because it uses popen().

Using -DLAMMPS_MEMALIGN=<bytes> enables the use of the posix_memalign() call instead of malloc() when large chunks or memory are allocated by LAMMPS. This can help to make more efficient use of vector instructions of modern CPUS, since dynamically allocated memory has to be aligned on larger than default byte boundaries (e.g. 16 bytes instead of 8 bytes on x86 type platforms) for optimal performance.

If you use -DLAMMPS_XDR, the build will include XDR compatibility files for doing particle dumps in XTC format. This is only necessary if your platform does have its own XDR files available. See the Restrictions section of the dump command for details.

Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG, -DLAMMPS_SMALLSMALL settings. The default is -DLAMMPS_SMALLBIG. These settings refer to use of 4-byte (small) vs 8-byte (big) integers within LAMMPS, as specified in src/lmptype.h. The only reason to use the BIGBIG setting is to enable simulation of huge molecular systems (which store bond topology info) with more than 2 billion atoms, or to track the image flags of moving atoms that wrap around a periodic box more than 512 times. Normally, the only reason to use SMALLSMALL is if your machine does not support 64-bit integers, though you can use SMALLSMALL setting if you are running in serial or on a desktop machine or small cluster where you will never run large systems or for long time (more than 2 billion atoms, more than 2 billion timesteps). See the Additional build tips section below for more details on these settings.

Note that the USER-ATC package is not currently compatible with -DLAMMPS_BIGBIG. Also the GPU package requires the lib/gpu library to be compiled with the same setting, or the link will fail.

The -DLAMMPS_LONGLONG_TO_LONG setting may be needed if your system or MPI version does not recognize “long long” data types. In this case a “long” data type is likely already 64-bits, in which case this setting will convert to that data type.

The -DLAMMPS_EXCEPTIONS setting can be used to activate alternative versions of error handling inside of LAMMPS. This is useful when external codes drive LAMMPS as a library. Using this option, LAMMPS errors do not kill the caller. Instead, the call stack is unwound and control returns to the caller. The library interface provides the lammps_has_error() and lammps_get_last_error_message() functions to detect and find out more about a LAMMPS error.

Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY options can make for faster parallel FFTs (in the PPPM solver) on some platforms. The -DPACK_ARRAY setting is the default. See the kspace_style command for info about PPPM. See Step 6 below for info about building LAMMPS with an FFT library.

2.2.2.6. Step 5

The 3 MPI variables are used to specify an MPI library to build LAMMPS with. Note that you do not need to set these if you use the MPI compiler mpicxx for your CC and LINK setting in the section above. The MPI wrapper knows where to find the needed files.

If you want LAMMPS to run in parallel, you must have an MPI library installed on your platform. If MPI is installed on your system in the usual place (under /usr/local), you also may not need to specify these 3 variables, assuming /usr/local is in your path. On some large parallel machines which use “modules” for their compile/link environements, you may simply need to include the correct module in your build environment, before building LAMMPS. Or the parallel machine may have a vendor-provided MPI which the compiler has no trouble finding.

Failing this, these 3 variables can be used to specify where the mpi.h file (MPI_INC) and the MPI library file (MPI_PATH) are found and the name of the library file (MPI_LIB).

If you are installing MPI yourself, we recommend Argonne’s MPICH2 or OpenMPI. MPICH can be downloaded from the Argonne MPI site. OpenMPI can be downloaded from the OpenMPI site. Other MPI packages should also work. If you are running on a big parallel platform, your system people or the vendor should have already installed a version of MPI, which is likely to be faster than a self-installed MPICH or OpenMPI, so find out how to build and link with it. If you use MPICH or OpenMPI, you will have to configure and build it for your platform. The MPI configure script should have compiler options to enable you to use the same compiler you are using for the LAMMPS build, which can avoid problems that can arise when linking LAMMPS to the MPI library.

If you just want to run LAMMPS on a single processor, you can use the dummy MPI library provided in src/STUBS, since you don’t need a true MPI library installed on your system. See src/MAKE/Makefile.serial for how to specify the 3 MPI variables in this case. You will also need to build the STUBS library for your platform before making LAMMPS itself. Note that if you are building with src/MAKE/Makefile.serial, e.g. by typing “make serial”, then the STUBS library is built for you.

To build the STUBS library from the src directory, type “make mpi-stubs”, or from the src/STUBS dir, type “make”. This should create a libmpi_stubs.a file suitable for linking to LAMMPS. If the build fails, you will need to edit the STUBS/Makefile for your platform.

The file STUBS/mpi.c provides a CPU timer function called MPI_Wtime() that calls gettimeofday() . If your system doesn’t support gettimeofday() , you’ll need to insert code to call another timer. Note that the ANSI-standard function clock() rolls over after an hour or so, and is therefore insufficient for timing long LAMMPS simulations.

2.2.2.7. Step 6

The 3 FFT variables allow you to specify an FFT library which LAMMPS uses (for performing 1d FFTs) when running the particle-particle particle-mesh (PPPM) option for long-range Coulombics via the kspace_style command.

LAMMPS supports various open-source or vendor-supplied FFT libraries for this purpose. If you leave these 3 variables blank, LAMMPS will use the open-source KISS FFT library, which is included in the LAMMPS distribution. This library is portable to all platforms and for typical LAMMPS simulations is almost as fast as FFTW or vendor optimized libraries. If you are not including the KSPACE package in your build, you can also leave the 3 variables blank.

Otherwise, select which kinds of FFTs to use as part of the FFT_INC setting by a switch of the form -DFFT_XXX. Recommended values for XXX are: MKL, SCSL, FFTW2, and FFTW3. Legacy options are: INTEL, SGI, ACML, and T3E. For backward compatability, using -DFFT_FFTW will use the FFTW2 library. Using -DFFT_NONE will use the KISS library described above.

You may also need to set the FFT_INC, FFT_PATH, and FFT_LIB variables, so the compiler and linker can find the needed FFT header and library files. Note that on some large parallel machines which use “modules” for their compile/link environements, you may simply need to include the correct module in your build environment. Or the parallel machine may have a vendor-provided FFT library which the compiler has no trouble finding.

FFTW is a fast, portable library that should also work on any platform. You can download it from www.fftw.org. Both the legacy version 2.1.X and the newer 3.X versions are supported as -DFFT_FFTW2 or -DFFT_FFTW3. Building FFTW for your box should be as simple as ./configure; make. Note that on some platforms FFTW2 has been pre-installed, and uses renamed files indicating the precision it was compiled with, e.g. sfftw.h, or dfftw.h instead of fftw.h. In this case, you can specify an additional define variable for FFT_INC called -DFFTW_SIZE, which will select the correct include file. In this case, for FFT_LIB you must also manually specify the correct library, namely -lsfftw or -ldfftw.

The FFT_INC variable also allows for a -DFFT_SINGLE setting that will use single-precision FFTs with PPPM, which can speed-up long-range calulations, particularly in parallel or on GPUs. Fourier transform and related PPPM operations are somewhat insensitive to floating point truncation errors and thus do not always need to be performed in double precision. Using the -DFFT_SINGLE setting trades off a little accuracy for reduced memory use and parallel communication costs for transposing 3d FFT data. Note that single precision FFTs have only been tested with the FFTW3, FFTW2, MKL, and KISS FFT options.

2.2.2.8. Step 7

The 3 JPG variables allow you to specify a JPEG and/or PNG library which LAMMPS uses when writing out JPEG or PNG files via the dump image command. These can be left blank if you do not use the -DLAMMPS_JPEG or -DLAMMPS_PNG switches discussed above in Step 4, since in that case JPEG/PNG output will be disabled.

A standard JPEG library usually goes by the name libjpeg.a or libjpeg.so and has an associated header file jpeglib.h. Whichever JPEG library you have on your platform, you’ll need to set the appropriate JPG_INC, JPG_PATH, and JPG_LIB variables, so that the compiler and linker can find it.

A standard PNG library usually goes by the name libpng.a or libpng.so and has an associated header file png.h. Whichever PNG library you have on your platform, you’ll need to set the appropriate JPG_INC, JPG_PATH, and JPG_LIB variables, so that the compiler and linker can find it.

As before, if these header and library files are in the usual place on your machine, you may not need to set these variables.

2.2.2.9. Step 8

Note that by default only a few of LAMMPS optional packages are installed. To build LAMMPS with optional packages, see this section below, before proceeding to Step 9.

2.2.2.10. Step 9

That’s it. Once you have a correct Makefile.foo, and you have pre-built any other needed libraries (e.g. MPI, FFT, etc) all you need to do from the src directory is type something like this:

make foo
 make -j N foo
 gmake foo
 gmake -j N foo

The -j or -j N switches perform a parallel build which can be much faster, depending on how many cores your compilation machine has. N is the number of cores the build runs on.

You should get the executable lmp_foo when the build is complete.

Errors that can occur when making LAMMPS: h5

Note

If an error occurs when building LAMMPS, the compiler or linker will state very explicitly what the problem is. The error message should give you a hint as to which of the steps above has failed, and what you need to do in order to fix it. Building a code with a Makefile is a very logical process. The compiler and linker need to find the appropriate files and those files need to be compatible with LAMMPS source files. When a make fails, there is usually a very simple reason, which you or a local expert will need to fix.

Here are two non-obvious errors that can occur:

(1) If the make command breaks immediately with errors that indicate it can’t find files with a “*” in their names, this can be because your machine’s native make doesn’t support wildcard expansion in a makefile. Try gmake instead of make. If that doesn’t work, try using a -f switch with your make command to use a pre-generated Makefile.list which explicitly lists all the needed files, e.g.

make makelist
 make -f Makefile.list linux
 gmake -f Makefile.list mac

The first “make” command will create a current Makefile.list with all the file names in your src dir. The 2nd “make” command (make or gmake) will use it to build LAMMPS. Note that you should include/exclude any desired optional packages before using the “make makelist” command.

(2) If you get an error that says something like ‘identifier “atoll” is undefined’, then your machine does not support “long long” integers. Try using the -DLAMMPS_LONGLONG_TO_LONG setting described above in Step 4.

2.2.3. Additional build tips

2.2.3.1. Building LAMMPS for multiple platforms.

You can make LAMMPS for multiple platforms from the same src directory. Each target creates its own object sub-directory called Obj_target where it stores the system-specific *.o files.

2.2.3.2. Cleaning up.

Typing “make clean-all” or “make clean-machine” will delete *.o object files created when LAMMPS is built, for either all builds or for a particular machine.

Changing the LAMMPS size limits via -DLAMMPS_SMALLBIG or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL “”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”“”

As explained above, any of these 3 settings can be specified on the LMP_INC line in your low-level src/MAKE/Makefile.foo.

The default is -DLAMMPS_SMALLBIG which allows for systems with up to 2^63 atoms and 2^63 timesteps (about 9e18). The atom limit is for atomic systems which do not store bond topology info and thus do not require atom IDs. If you use atom IDs for atomic systems (which is the default) or if you use a molecular model, which stores bond topology info and thus requires atom IDs, the limit is 2^31 atoms (about 2 billion). This is because the IDs are stored in 32-bit integers.

Likewise, with this setting, the 3 image flags for each atom (see the dump doc page for a discussion) are stored in a 32-bit integer, which means the atoms can only wrap around a periodic box (in each dimension) at most 512 times. If atoms move through the periodic box more than this many times, the image flags will “roll over”, e.g. from 511 to -512, which can cause diagnostics like the mean-squared displacement, as calculated by the compute msd command, to be faulty.

To allow for larger atomic systems with atom IDs or larger molecular systems or larger image flags, compile with -DLAMMPS_BIGBIG. This stores atom IDs and image flags in 64-bit integers. This enables atomic or molecular systems with atom IDS of up to 2^63 atoms (about 9e18). And image flags will not “roll over” until they reach 2^20 = 1048576.

If your system does not support 8-byte integers, you will need to compile with the -DLAMMPS_SMALLSMALL setting. This will restrict the total number of atoms (for atomic or molecular systems) and timesteps to 2^31 (about 2 billion). Image flags will roll over at 2^9 = 512.

Note that in src/lmptype.h there are definitions of all these data types as well as the MPI data types associated with them. The MPI types need to be consistent with the associated C data types, or else LAMMPS will generate a run-time error. As far as we know, the settings defined in src/lmptype.h are portable and work on every current system.

In all cases, the size of problem that can be run on a per-processor basis is limited by 4-byte integer storage to 2^31 atoms per processor (about 2 billion). This should not normally be a limitation since such a problem would have a huge per-processor memory footprint due to neighbor lists and would run very slowly in terms of CPU secs/timestep.

2.2.4. Building for a Mac

OS X is BSD Unix, so it should just work. See the src/MAKE/MACHINES/Makefile.mac and Makefile.mac_mpi files.

2.2.5. Building for Windows

If you want to build a Windows version of LAMMPS, you can build it yourself, but it may require some effort. LAMMPS expects a Unix-like build environment for the default build procedure. This can be done using either Cygwin or MinGW; the latter also exists as a ready-to-use Linux-to-Windows cross-compiler in several Linux distributions. In these cases, you can do the installation after installing several unix-style commands like make, grep, sed and bash with some shell utilities.

For Cygwin and the MinGW cross-compilers, suitable makefiles are provided in src/MAKE/MACHINES. When using other compilers, like Visual C++ or Intel compilers for Windows, you may have to implement your own build system. Since none of the current LAMMPS core developers has significant experience building executables on Windows, we are happy to distribute contributed instructions and modifications, but we cannot provide support for those.

With the so-called “Anniversary Update” to Windows 10, there is a Ubuntu subsystem available for Windows, that can be installed and then it can be used to compile/install LAMMPS as if you are running on a Ubuntu Linux system.

As an alternative, you can download “daily builds” (and some older versions) of the installer packages from rpm.lammps.org/windows.html. These executables are built with most optional packages and the download includes documentation, potential files, some tools and many examples, but no source code.

2.3. Making LAMMPS with optional packages

This section has the following sub-sections:

Note that the following Section 2.4 describes the Make.py tool which can be used to install/un-install packages and build the auxiliary libraries which some of them use. It can also auto-edit a Makefile.machine to add settings needed by some packages.

2.3.1. Package basics:

The source code for LAMMPS is structured as a set of core files which are always included, plus optional packages. Packages are groups of files that enable a specific set of features. For example, force fields for molecular systems or granular systems are in packages.

Section packages in the manual has details about all the packages, including specific instructions for building LAMMPS with each package, which are covered in a more general manner below.

You can see the list of all packages by typing “make package” from within the src directory of the LAMMPS distribution. This also lists various make commands that can be used to manipulate packages.

If you use a command in a LAMMPS input script that is part of a package, you must have built LAMMPS with that package, else you will get an error that the style is invalid or the command is unknown. Every command’s doc page specfies if it is part of a package. You can also type

 lmp_machine -h

to run your executable with the optional -h command-line switch for “help”, which will simply list the styles and commands known to your executable, and immediately exit.

There are two kinds of packages in LAMMPS, standard and user packages. More information about the contents of standard and user packages is given in Section 4 of the manual. The difference between standard and user packages is as follows:

Standard packages, such as molecule or kspace, are supported by the LAMMPS developers and are written in a syntax and style consistent with the rest of LAMMPS. This means we will answer questions about them, debug and fix them if necessary, and keep them compatible with future changes to LAMMPS.

User packages, such as user-atc or user-omp, have been contributed by users, and always begin with the user prefix. If they are a single command (single file), they are typically in the user-misc package. Otherwise, they are a a set of files grouped together which add a specific functionality to the code.

User packages don’t necessarily meet the requirements of the standard packages. If you have problems using a feature provided in a user package, you may need to contact the contributor directly to get help. Information on how to submit additions you make to LAMMPS as single files or either a standard or user-contributed package are given in this section of the documentation.

2.3.2. Including/excluding packages

To use (or not use) a package you must include it (or exclude it) before building LAMMPS. From the src directory, this is typically as simple as:

make yes-colloid
 make g++

or

make no-manybody
 make g++

Note

You should NOT include/exclude packages and build LAMMPS in a single make command using multiple targets, e.g. make yes-colloid g++. This is because the make procedure creates a list of source files that will be out-of-date for the build if the package configuration changes within the same command.

Some packages have individual files that depend on other packages being included. LAMMPS checks for this and does the right thing. I.e. individual files are only included if their dependencies are already included. Likewise, if a package is excluded, other files dependent on that package are also excluded.

If you will never run simulations that use the features in a particular packages, there is no reason to include it in your build. For some packages, this will keep you from having to build auxiliary libraries (see below), and will also produce a smaller executable which may run a bit faster.

When you download a LAMMPS tarball, these packages are pre-installed in the src directory: KSPACE, MANYBODY,MOLECULE, because they are so commonly used. When you download LAMMPS source files from the SVN or Git repositories, no packages are pre-installed.

Packages are included or excluded by typing “make yes-name” or “make no-name”, where “name” is the name of the package in lower-case, e.g. name = kspace for the KSPACE package or name = user-atc for the USER-ATC package. You can also type “make yes-standard”, “make no-standard”, “make yes-std”, “make no-std”, “make yes-user”, “make no-user”, “make yes-lib”, “make no-lib”, “make yes-all”, or “make no-all” to include/exclude various sets of packages. Type “make package” to see all of the package-related make options.

Note

Inclusion/exclusion of a package works by simply moving files back and forth between the main src directory and sub-directories with the package name (e.g. src/KSPACE, src/USER-ATC), so that the files are seen or not seen when LAMMPS is built. After you have included or excluded a package, you must re-build LAMMPS.

Additional package-related make options exist to help manage LAMMPS files that exist in both the src directory and in package sub-directories. You do not normally need to use these commands unless you are editing LAMMPS files or have downloaded a patch from the LAMMPS WWW site.

Typing “make package-update” or “make pu” will overwrite src files with files from the package sub-directories if the package has been included. It should be used after a patch is installed, since patches only update the files in the package sub-directory, but not the src files. Typing “make package-overwrite” will overwrite files in the package sub-directories with src files.

Typing “make package-status” or “make ps” will show which packages are currently included. For those that are included, it will list any files that are different in the src directory and package sub-directory. Typing “make package-diff” lists all differences between these files. Again, type “make package” to see all of the package-related make options.

2.3.3. Packages that require extra libraries

A few of the standard and user packages require additional auxiliary libraries. Many of them are provided with LAMMPS, in which case they must be compiled first, before LAMMPS is built, if you wish to include that package. If you get a LAMMPS build error about a missing library, this is likely the reason. See the Section 4 doc page for a list of packages that have these kinds of auxiliary libraries.

The lib directory in the distribution has sub-directories with package names that correspond to the needed auxiliary libs, e.g. lib/gpu. Each sub-directory has a README file that gives more details. Code for most of the auxiliary libraries is included in that directory. Examples are the USER-ATC and MEAM packages.

A few of the lib sub-directories do not include code, but do include instructions (and sometimes scripts) that automate the process of downloading the auxiliary library and installing it so LAMMPS can link to it. Examples are the KIM, VORONOI, USER-MOLFILE, and USER-SMD packages.

The lib/python directory (for the PYTHON package) contains only a choice of Makefile.lammps.* files. This is because no auxiliary code or libraries are needed, only the Python library and other system libs that should already available on your system. However, the Makefile.lammps file is needed to tell LAMMPS which libs to use and where to find them.

For libraries with provided code, the sub-directory README file (e.g. lib/atc/README) has instructions on how to build that library. This information is also summarized in Section packages. Typically this is done by typing something like:

make -f Makefile.g++

If one of the provided Makefiles is not appropriate for your system you will need to edit or add one. Note that all the Makefiles have a setting for EXTRAMAKE at the top that specifies a Makefile.lammps.* file.

If the library build is successful, it will produce 2 files in the lib directory:

libpackage.a
 Makefile.lammps

The Makefile.lammps file will typically be a copy of one of the Makefile.lammps.* files in the library directory.

Note that you must insure that the settings in Makefile.lammps are appropriate for your system. If they are not, the LAMMPS build may fail. To fix this, you can edit or create a new Makefile.lammps.* file for your system, and copy it to Makefile.lammps.

As explained in the lib/package/README files, the settings in Makefile.lammps are used to specify additional system libraries and their locations so that LAMMPS can build with the auxiliary library. For example, if the MEAM package is used, the auxiliary library consists of F90 code, built with a Fortran complier. To link that library with LAMMPS (a C++ code) via whatever C++ compiler LAMMPS is built with, typically requires additional Fortran-to-C libraries be included in the link. Another example are the BLAS and LAPACK libraries needed to use the USER-ATC or USER-AWPMD packages.

For libraries without provided code, the sub-directory README file has information on where to download the library and how to build it, e.g. lib/voronoi/README and lib/smd/README. The README files also describe how you must either (a) create soft links, via the “ln” command, in those directories to point to where you built or installed the packages, or (b) check or edit the Makefile.lammps file in the same directory to provide that information.

Some of the sub-directories, e.g. lib/voronoi, also have an install.py script which can be used to automate the process of downloading/building/installing the auxiliary library, and setting the needed soft links. Type “python install.py” for further instructions.

As with the sub-directories containing library code, if the soft links or settings in the lib/package/Makefile.lammps files are not correct, the LAMMPS build will typically fail.

2.3.4. Packages that require Makefile.machine settings

A few packages require specific settings in Makefile.machine, to either build or use the package effectively. These are the USER-INTEL, KOKKOS, USER-OMP, and OPT packages, used for accelerating code performance on CPUs or other hardware, as discussed in Section acclerate.

A summary of what Makefile.machine changes are needed for each of these packages is given in Section packages. The details are given on the doc pages that describe each of these accelerator packages in detail:

You can also look at the following machine Makefiles in src/MAKE/OPTIONS, which include the changes. Note that the USER-INTEL and KOKKOS packages allow for settings that build LAMMPS for different hardware. The USER-INTEL package builds for CPU and the Xeon Phi, the KOKKOS package builds for OpenMP, GPUs (Cuda), and the Xeon Phi.

  • Makefile.intel_cpu
  • Makefile.intel_phi
  • Makefile.kokkos_omp
  • Makefile.kokkos_cuda
  • Makefile.kokkos_phi
  • Makefile.omp
  • Makefile.opt

Also note that the Make.py tool, described in the next Section 2.4 can automatically add the needed info to an existing machine Makefile, using simple command-line arguments.

2.4. Building LAMMPS via the Make.py tool

The src directory includes a Make.py script, written in Python, which can be used to automate various steps of the build process. It is particularly useful for working with the accelerator packages, as well as other packages which require auxiliary libraries to be built.

The goal of the Make.py tool is to allow any complex multi-step LAMMPS build to be performed as a single Make.py command. And you can archive the commands, so they can be re-invoked later via the -r (redo) switch. If you find some LAMMPS build procedure that can’t be done in a single Make.py command, let the developers know, and we’ll see if we can augment the tool.

You can run Make.py from the src directory by typing either:

Make.py -h
 python Make.py -h

which will give you help info about the tool. For the former to work, you may need to edit the first line of Make.py to point to your local Python. And you may need to insure the script is executable:

chmod +x Make.py

Here are examples of build tasks you can perform with Make.py:

Install/uninstall packages Make.py -p no-lib kokkos omp intel
Build specific auxiliary libs Make.py -a lib-atc lib-meam
Build libs for all installed packages Make.py -p cuda gpu -gpu mode=double arch=31 -a lib-all
Create a Makefile from scratch with compiler and MPI settings Make.py -m none -cc g++ -mpi mpich -a file
Augment Makefile.serial with settings for installed packages Make.py -p intel -intel cpu -m serial -a file
Add JPG and FFTW support to Makefile.mpi Make.py -m mpi -jpg -fft fftw -a file
Build LAMMPS with a parallel make using Makefile.mpi Make.py -j 16 -m mpi -a exe
Build LAMMPS and libs it needs using Makefile.serial with accelerator settings Make.py -p gpu intel -intel cpu -a lib-all file serial

The bench and examples directories give Make.py commands that can be used to build LAMMPS with the various packages and options needed to run all the benchmark and example input scripts. See these files for more details:

  • bench/README
  • bench/FERMI/README
  • bench/KEPLER/README
  • bench/PHI/README
  • examples/README
  • examples/accelerate/README
  • examples/accelerate/make.list

All of the Make.py options and syntax help can be accessed by using the “-h” switch.

E.g. typing “Make.py -h” gives

Syntax: Make.py switch args ...
   switches can be listed in any order
   help switch:
     -h prints help and syntax for all other specified switches
   switch for actions:
     -a lib-all, lib-dir, clean, file, exe or machine
     list one or more actions, in any order
     machine is a Makefile.machine suffix, must be last if used
   one-letter switches:
     -d (dir), -j (jmake), -m (makefile), -o (output),
     -p (packages), -r (redo), -s (settings), -v (verbose)
   switches for libs:
     -atc, -awpmd, -colvars, -cuda
     -gpu, -meam, -poems, -qmmm, -reax
   switches for build and makefile options:
     -intel, -kokkos, -cc, -mpi, -fft, -jpg, -png

Using the “-h” switch with other switches and actions gives additional info on all the other specified switches or actions. The “-h” can be anywhere in the command-line and the other switches do not need their arguments. E.g. type “Make.py -h -d -atc -intel” will print:

-d dir
   dir = LAMMPS home dir
   if -d not specified, working dir must be lammps/src
 
-atc make=suffix lammps=suffix2
   all args are optional and can be in any order
   make = use Makefile.suffix (def = g++)
   lammps = use Makefile.lammps.suffix2 (def = EXTRAMAKE in makefile)
 
-intel mode
   mode = cpu or phi (def = cpu)
     build Intel package for CPU or Xeon Phi

Note that Make.py never overwrites an existing Makefile.machine. Instead, it creates src/MAKE/MINE/Makefile.auto, which you can save or rename if desired. Likewise it creates an executable named src/lmp_auto, which you can rename using the -o switch if desired.

The most recently executed Make.py commmand is saved in src/Make.py.last. You can use the “-r” switch (for redo) to re-invoke the last command, or you can save a sequence of one or more Make.py commands to a file and invoke the file of commands using “-r”. You can also label the commands in the file and invoke one or more of them by name.

A typical use of Make.py is to start with a valid Makefile.machine for your system, that works for a vanilla LAMMPS build, i.e. when optional packages are not installed. You can then use Make.py to add various settings (FFT, JPG, PNG) to the Makefile.machine as well as change its compiler and MPI options. You can also add additional packages to the build, as well as build the needed supporting libraries.

You can also use Make.py to create a new Makefile.machine from scratch, using the “-m none” switch, if you also specify what compiler and MPI options to use, via the “-cc” and “-mpi” switches.

2.5. Building LAMMPS as a library

LAMMPS can be built as either a static or shared library, which can then be called from another application or a scripting language. See this section for more info on coupling LAMMPS to other codes. See this section for more info on wrapping and running LAMMPS from Python.

2.5.1. Static library

To build LAMMPS as a static library (*.a file on Linux), type

make foo mode=lib

where foo is the machine name. This kind of library is typically used to statically link a driver application to LAMMPS, so that you can insure all dependencies are satisfied at compile time. This will use the ARCHIVE and ARFLAGS settings in src/MAKE/Makefile.foo. The build will create the file liblammps_foo.a which another application can link to. It will also create a soft link liblammps.a, which will point to the most recently built static library.

2.5.2. Shared library

To build LAMMPS as a shared library (*.so file on Linux), which can be dynamically loaded, e.g. from Python, type

make foo mode=shlib

where foo is the machine name. This kind of library is required when wrapping LAMMPS with Python; see Section 11 for details. This will use the SHFLAGS and SHLIBFLAGS settings in src/MAKE/Makefile.foo and perform the build in the directory Obj_shared_foo. This is so that each file can be compiled with the -fPIC flag which is required for inclusion in a shared library. The build will create the file liblammps_foo.so which another application can link to dyamically. It will also create a soft link liblammps.so, which will point to the most recently built shared library. This is the file the Python wrapper loads by default.

Note that for a shared library to be usable by a calling program, all the auxiliary libraries it depends on must also exist as shared libraries. This will be the case for libraries included with LAMMPS, such as the dummy MPI library in src/STUBS or any package libraries in lib/packages, since they are always built as shared libraries using the -fPIC switch. However, if a library like MPI or FFTW does not exist as a shared library, the shared library build will generate an error. This means you will need to install a shared library version of the auxiliary library. The build instructions for the library should tell you how to do this.

Here is an example of such errors when the system FFTW or provided lib/colvars library have not been built as shared libraries:

 /usr/bin/ld: /usr/local/lib/libfftw3.a(mapflags.o): relocation
 R_X86_64_32 against '.rodata' can not be used when making a shared
 object; recompile with -fPIC
 /usr/local/lib/libfftw3.a: could not read symbols: Bad value
 
 /usr/bin/ld: ../../lib/colvars/libcolvars.a(colvarmodule.o):
 relocation R_X86_64_32 against '__pthread_key_create' can not be used
 when making a shared object; recompile with -fPIC
 ../../lib/colvars/libcolvars.a: error adding symbols: Bad value

As an example, here is how to build and install the MPICH library, a popular open-source version of MPI, distributed by Argonne National Labs, as a shared library in the default /usr/local/lib location:

./configure --enable-shared
 make
 make install

You may need to use “sudo make install” in place of the last line if you do not have write privileges for /usr/local/lib. The end result should be the file /usr/local/lib/libmpich.so.

2.5.3. Additional requirement for using a shared library:

The operating system finds shared libraries to load at run-time using the environment variable LD_LIBRARY_PATH. So you may wish to copy the file src/liblammps.so or src/liblammps_g++.so (for example) to a place the system can find it by default, such as /usr/local/lib, or you may wish to add the LAMMPS src directory to LD_LIBRARY_PATH, so that the current version of the shared library is always available to programs that use it.

For the csh or tcsh shells, you would add something like this to your ~/.cshrc file:

 setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src

2.5.4. Calling the LAMMPS library

Either flavor of library (static or shared) allows one or more LAMMPS objects to be instantiated from the calling program.

When used from a C++ program, all of LAMMPS is wrapped in a LAMMPS_NS namespace; you can safely use any of its classes and methods from within the calling code, as needed.

When used from a C or Fortran program or a scripting language like Python, the library has a simple function-style interface, provided in src/library.cpp and src/library.h.

See the sample codes in examples/COUPLE/simple for examples of C++ and C and Fortran codes that invoke LAMMPS thru its library interface. There are other examples as well in the COUPLE directory which are discussed in Section 6.10 of the manual. See Section 11 of the manual for a description of the Python wrapper provided with LAMMPS that operates through the LAMMPS library interface.

The files src/library.cpp and library.h define the C-style API for -using LAMMPS as a library. See Section_howto 19 of the manual for a description of the +using LAMMPS as a library. See Section 6.19 of the manual for a description of the interface and how to extend it for your needs.

2.6. Running LAMMPS

By default, LAMMPS runs by reading commands from standard input. Thus if you run the LAMMPS executable by itself, e.g.

 lmp_linux

it will simply wait, expecting commands from the keyboard. Typically you should put commands in an input script and use I/O redirection, e.g.

 lmp_linux < in.file

For parallel environments this should also work. If it does not, use the ‘-in’ command-line switch, e.g.

 lmp_linux -in in.file

This section describes how input scripts are structured and what commands they contain.

You can test LAMMPS on any of the sample inputs provided in the examples or bench directory. Input scripts are named in.* and sample outputs are named log.*.name.P where name is a machine and P is the number of processors it was run on.

Here is how you might run a standard Lennard-Jones benchmark on a Linux box, using mpirun to launch a parallel job:

 cd src
 make linux
 cp lmp_linux ../bench
 cd ../bench
 mpirun -np 4 lmp_linux -in in.lj

See this page for timings for this and the other benchmarks on various platforms. Note that some of the example scripts require LAMMPS to be built with one or more of its optional packages.

On a Windows box, you can skip making LAMMPS and simply download an installer package from here

For running the non-MPI executable, follow these steps:

  • Get a command prompt by going to Start->Run... , then typing “cmd”.
  • Move to the directory where you have your input, e.g. a copy of the in.lj input from the bench folder. (e.g. by typing: cd “Documents”).
  • At the command prompt, type “lmp_serial -in in.lj”, replacing in.lj with the name of your LAMMPS input script.

For the MPI version, which allows you to run LAMMPS under Windows on multiple processors, follow these steps:

  • Download and install MPICH2 for Windows.

The LAMMPS Windows installer packages will automatically adjust your path for the default location of this MPI package. After the installation of the MPICH software, it needs to be integrated into the system. For this you need to start a Command Prompt in Administrator Mode (right click on the icon and select it). Change into the MPICH2 installation directory, then into the subdirectory bin and execute smpd.exe -install. Exit the command window.

  • Get a new, regular command prompt by going to Start->Run... , then typing “cmd”.
  • Move to the directory where you have your input file (e.g. by typing: cd “Documents”).

Then type something like this:

 mpiexec -localonly 4 lmp_mpi -in in.lj

or

 mpiexec -np 4 lmp_mpi -in in.lj
  • replacing in.lj with the name of your LAMMPS input script. For the latter case, you may be prompted to enter your password.
  • In this mode, output may not immediately show up on the screen, so if your input script takes a long time to execute, you may need to be patient before the output shows up.

The parallel executable can also run on a single processor by typing something like:

 lmp_mpi -in in.lj

The screen output from LAMMPS is described in a section below. As it runs, LAMMPS also writes a log.lammps file with the same information.

Note that this sequence of commands copies the LAMMPS executable (lmp_linux) to the directory with the input files. This may not be necessary, but some versions of MPI reset the working directory to where the executable is, rather than leave it as the directory where you launch mpirun from (if you launch lmp_linux on its own and not under mpirun). If that happens, LAMMPS will look for additional input files and write its output files to the executable directory, rather than your working directory, which is probably not what you want.

If LAMMPS encounters errors in the input script or while running a simulation it will print an ERROR message and stop or a WARNING message and continue. See Section 12 for a discussion of the various kinds of errors LAMMPS can or can’t detect, a list of all ERROR and WARNING messages, and what to do about them.

LAMMPS can run a problem on any number of processors, including a single processor. In theory you should get identical answers on any number of processors and on any machine. In practice, numerical round-off can cause slight differences and eventual divergence of molecular dynamics phase space trajectories.

LAMMPS can run as large a problem as will fit in the physical memory of one or more processors. If you run out of memory, you must run on more processors or setup a smaller problem.

2.7. Command-line options

At run time, LAMMPS recognizes several optional command-line switches which may be used in any order. Either the full word or a one-or-two letter abbreviation can be used:

  • -e or -echo
  • -h or -help
  • -i or -in
  • -k or -kokkos
  • -l or -log
  • -nc or -nocite
  • -pk or -package
  • -p or -partition
  • -pl or -plog
  • -ps or -pscreen
  • -r or -restart
  • -ro or -reorder
  • -sc or -screen
  • -sf or -suffix
  • -v or -var

For example, lmp_ibm might be launched as follows:

 mpirun -np 16 lmp_ibm -v f tmp.out -l my.log -sc none -in in.alloy
 mpirun -np 16 lmp_ibm -var f tmp.out -log my.log -screen none -in in.alloy

Here are the details on the options:

-echo style

Set the style of command echoing. The style can be none or screen or log or both. Depending on the style, each command read from the input script will be echoed to the screen and/or logfile. This can be useful to figure out which line of your script is causing an input error. The default value is log. The echo style can also be set by using the echo command in the input script itself.

-help

Print a brief help summary and a list of options compiled into this executable for each LAMMPS style (atom_style, fix, compute, pair_style, bond_style, etc). This can tell you if the command you want to use was included via the appropriate package at compile time. LAMMPS will print the info and immediately exit if this switch is used.

-in file

Specify a file to use as an input script. This is an optional switch when running LAMMPS in one-partition mode. If it is not specified, LAMMPS reads its script from standard input, typically from a script via I/O redirection; e.g. lmp_linux < in.run. I/O redirection should also work in parallel, but if it does not (in the unlikely case that an MPI implementation does not support it), then use the -in flag. Note that this is a required switch when running LAMMPS in multi-partition mode, since multiple processors cannot all read from stdin.

-kokkos on/off keyword/value ...

Explicitly enable or disable KOKKOS support, as provided by the KOKKOS package. Even if LAMMPS is built with this package, as described above in Section 2.3, this switch must be set to enable running with the KOKKOS-enabled styles the package provides. If the switch is not set (the default), LAMMPS will operate as if the KOKKOS package were not installed; i.e. you can run standard LAMMPS or with the GPU or USER-OMP packages, for testing or benchmarking purposes.

Additional optional keyword/value pairs can be specified which determine how Kokkos will use the underlying hardware on your platform. These settings apply to each MPI task you launch via the “mpirun” or “mpiexec” command. You may choose to run one or more MPI tasks per physical node. Note that if you are running on a desktop machine, you typically have one physical node. On a cluster or supercomputer there may be dozens or 1000s of physical nodes.

Either the full word or an abbreviation can be used for the keywords. Note that the keywords do not use a leading minus sign. I.e. the keyword is “t”, not “-t”. Also note that each of the keywords has a default setting. Example of when to use these options and what settings to use on different platforms is given in Section 5.8.

  • d or device
  • g or gpus
  • t or threads
  • n or numa
device Nd

This option is only relevant if you built LAMMPS with CUDA=yes, you have more than one GPU per node, and if you are running with only one MPI task per node. The Nd setting is the ID of the GPU on the node to run on. By default Nd = 0. If you have multiple GPUs per node, they have consecutive IDs numbered as 0,1,2,etc. This setting allows you to launch multiple independent jobs on the node, each with a single MPI task per node, and assign each job to run on a different GPU.

gpus Ng Ns

This option is only relevant if you built LAMMPS with CUDA=yes, you have more than one GPU per node, and you are running with multiple MPI tasks per node (up to one per GPU). The Ng setting is how many GPUs you will use. The Ns setting is optional. If set, it is the ID of a GPU to skip when assigning MPI tasks to GPUs. This may be useful if your desktop system reserves one GPU to drive the screen and the rest are intended for computational work like running LAMMPS. By default Ng = 1 and Ns is not set.

Depending on which flavor of MPI you are running, LAMMPS will look for one of these 3 environment variables

 SLURM_LOCALID (various MPI variants compiled with SLURM support)
 MV2_COMM_WORLD_LOCAL_RANK (Mvapich)
 OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI)

which are initialized by the “srun”, “mpirun” or “mpiexec” commands. The environment variable setting for each MPI rank is used to assign a unique GPU ID to the MPI task.

threads Nt

This option assigns Nt number of threads to each MPI task for performing work when Kokkos is executing in OpenMP or pthreads mode. The default is Nt = 1, which essentially runs in MPI-only mode. If there are Np MPI tasks per physical node, you generally want Np*Nt = the number of physical cores per node, to use your available hardware optimally. This also sets the number of threads used by the host when LAMMPS is compiled with CUDA=yes.

numa Nm

This option is only relevant when using pthreads with hwloc support. In this case Nm defines the number of NUMA regions (typicaly sockets) on a node which will be utilizied by a single MPI rank. By default Nm = 1. If this option is used the total number of worker-threads per MPI rank is threads*numa. Currently it is always almost better to assign at least one MPI rank per NUMA region, and leave numa set to its default value of 1. This is because letting a single process span multiple NUMA regions induces a significant amount of cross NUMA data traffic which is slow.

-log file

Specify a log file for LAMMPS to write status information to. In one-partition mode, if the switch is not used, LAMMPS writes to the file log.lammps. If this switch is used, LAMMPS writes to the specified file. In multi-partition mode, if the switch is not used, a log.lammps file is created with hi-level status information. Each partition also writes to a log.lammps.N file where N is the partition ID. If the switch is specified in multi-partition mode, the hi-level logfile is named “file” and each partition also logs information to a file.N. For both one-partition and multi-partition mode, if the specified file is “none”, then no log files are created. Using a log command in the input script will override this setting. Option -plog will override the name of the partition log files file.N.

-nocite

Disable writing the log.cite file which is normally written to list references for specific cite-able features used during a LAMMPS run. See the citation page for more details.

-package style args ....

Invoke the package command with style and args. The syntax is the same as if the command appeared at the top of the input script. For example “-package gpu 2” or “-pk gpu 2” is the same as package gpu 2 in the input script. The possible styles and args are documented on the package doc page. This switch can be used multiple times, e.g. to set options for the USER-INTEL and USER-OMP packages which can be used together.

Along with the “-suffix” command-line switch, this is a convenient mechanism for invoking accelerator packages and their options without having to edit an input script.

-partition 8x2 4 5 ...

Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P processors and this switch is not used, LAMMPS runs in one partition, i.e. all P processors run a single simulation. If this switch is used, the P processors are split into separate partitions and each partition runs its own simulation. The arguments to the switch specify the number of processors in each partition. Arguments of the form MxN mean M partitions, each with N processors. Arguments of the form N mean a single partition with N processors. The sum of processors in all partitions must equal P. Thus the command “-partition 8x2 4 5” has 10 partitions and runs on a total of 25 processors.

Running with multiple partitions can e useful for running multi-replica simulations, where each replica runs on on one or a few processors. Note that with MPI installed on a machine (e.g. your desktop), you can run on more (virtual) processors than you have physical processors.

To run multiple independent simulatoins from one input script, using multiple partitions, see Section 6.4 of the manual. World- and universe-style variables are useful in this context.

-plog file

Specify the base name for the partition log files, so partition N writes log information to file.N. If file is none, then no partition log files are created. This overrides the filename specified in the -log command-line option. This option is useful when working with large numbers of partitions, allowing the partition log files to be suppressed (-plog none) or placed in a sub-directory (-plog replica_files/log.lammps) If this option is not used the log file for partition N is log.lammps.N or whatever is specified by the -log command-line option.

-pscreen file

Specify the base name for the partition screen file, so partition N writes screen information to file.N. If file is none, then no partition screen files are created. This overrides the filename specified in the -screen command-line option. This option is useful when working with large numbers of partitions, allowing the partition screen files to be suppressed (-pscreen none) or placed in a sub-directory (-pscreen replica_files/screen). If this option is not used the screen file for partition N is screen.N or whatever is specified by the -screen command-line option.

 -restart restartfile remap datafile keyword value ...

Convert the restart file into a data file and immediately exit. This is the same operation as if the following 2-line input script were run:

 read_restart restartfile remap
 write_data datafile keyword value ...

Note that the specified restartfile and datafile can have wild-card characters (“*”,%”) as described by the read_restart and write_data commands. But a filename such as file.* will need to be enclosed in quotes to avoid shell expansion of the “*” character.

Note that following restartfile, the optional flag remap can be used. This has the same effect as adding it to the read_restart command, as explained on its doc page. This is only useful if the reading of the restart file triggers an error that atoms have been lost. In that case, use of the remap flag should allow the data file to still be produced.

Also note that following datafile, the same optional keyword/value pairs can be listed as used by the write_data command.

-reorder nth N
 -reorder custom filename

Reorder the processors in the MPI communicator used to instantiate LAMMPS, in one of several ways. The original MPI communicator ranks all P processors from 0 to P-1. The mapping of these ranks to physical processors is done by MPI before LAMMPS begins. It may be useful in some cases to alter the rank order. E.g. to insure that cores within each node are ranked in a desired order. Or when using the run_style verlet/split command with 2 partitions to insure that a specific Kspace processor (in the 2nd partition) is matched up with a specific set of processors in the 1st partition. See the Section 5 doc pages for more details.

If the keyword nth is used with a setting N, then it means every Nth processor will be moved to the end of the ranking. This is useful when using the run_style verlet/split command with 2 partitions via the -partition command-line switch. The first set of processors will be in the first partition, the 2nd set in the 2nd partition. The -reorder command-line switch can alter this so that the 1st N procs in the 1st partition and one proc in the 2nd partition will be ordered consecutively, e.g. as the cores on one physical node. This can boost performance. For example, if you use “-reorder nth 4” and “-partition 9 3” and you are running on 12 processors, the processors will be reordered from

0 1 2 3 4 5 6 7 8 9 10 11

to

0 1 2 4 5 6 8 9 10 3 7 11

so that the processors in each partition will be

0 1 2 4 5 6 8 9 10
 3 7 11

See the “processors” command for how to insure processors from each partition could then be grouped optimally for quad-core nodes.

If the keyword is custom, then a file that specifies a permutation of the processor ranks is also specified. The format of the reorder file is as follows. Any number of initial blank or comment lines (starting with a “#” character) can be present. These should be followed by P lines of the form:

I J

where P is the number of processors LAMMPS was launched with. Note that if running in multi-partition mode (see the -partition switch above) P is the total number of processors in all partitions. The I and J values describe a permutation of the P processors. Every I and J should be values from 0 to P-1 inclusive. In the set of P I values, every proc ID should appear exactly once. Ditto for the set of P J values. A single I,J pairing means that the physical processor with rank I in the original MPI communicator will have rank J in the reordered communicator.

Note that rank ordering can also be specified by many MPI implementations, either by environment variables that specify how to order physical processors, or by config files that specify what physical processors to assign to each MPI rank. The -reorder switch simply gives you a portable way to do this without relying on MPI itself. See the processors out command for how to output info on the final assignment of physical processors to the LAMMPS simulation domain.

-screen file

Specify a file for LAMMPS to write its screen information to. In one-partition mode, if the switch is not used, LAMMPS writes to the screen. If this switch is used, LAMMPS writes to the specified file instead and you will see no screen output. In multi-partition mode, if the switch is not used, hi-level status information is written to the screen. Each partition also writes to a screen.N file where N is the partition ID. If the switch is specified in multi-partition mode, the hi-level screen dump is named “file” and each partition also writes screen information to a file.N. For both one-partition and multi-partition mode, if the specified file is “none”, then no screen output is performed. Option -pscreen will override the name of the partition screen files file.N.

-suffix style args

Use variants of various styles if they exist. The specified style can be cuda, gpu, intel, kk, omp, opt, or hybrid. These refer to optional packages that LAMMPS can be built with, as described above in Section 2.3. The “gpu” style corresponds to the GPU package, the “intel” style to the USER-INTEL package, the “kk” style to the KOKKOS package, the “opt” style to the OPT package, and the “omp” style to the USER-OMP package. The hybrid style is the only style that accepts arguments. It allows for two packages to be specified. The first package specified is the default and will be used if it is available. If no style is available for the first package, the style for the second package will be used if available. For example, “-suffix hybrid intel omp” will use styles from the USER-INTEL package if they are installed and available, but styles for the USER-OMP package otherwise.

Along with the “-package” command-line switch, this is a convenient mechanism for invoking accelerator packages and their options without having to edit an input script.

As an example, all of the packages provide a pair_style lj/cut variant, with style names lj/cut/gpu, lj/cut/intel, lj/cut/kk, lj/cut/omp, and lj/cut/opt. A variant style can be specified explicitly in your input script, e.g. pair_style lj/cut/gpu. If the -suffix switch is used the specified suffix (gpu,intel,kk,omp,opt) is automatically appended whenever your input script command creates a new atom, pair, fix, compute, or run style. If the variant version does not exist, the standard version is created.

For the GPU package, using this command-line switch also invokes the default GPU settings, as if the command “package gpu 1” were used at the top of your input script. These settings can be changed by using the “-package gpu” command-line switch or the package gpu command in your script.

For the USER-INTEL package, using this command-line switch also invokes the default USER-INTEL settings, as if the command “package intel 1” were used at the top of your input script. These settings can be changed by using the “-package intel” command-line switch or the package intel command in your script. If the USER-OMP package is also installed, the hybrid style with “intel omp” arguments can be used to make the omp suffix a second choice, if a requested style is not available in the USER-INTEL package. It will also invoke the default USER-OMP settings, as if the command “package omp 0” were used at the top of your input script. These settings can be changed by using the “-package omp” command-line switch or the package omp command in your script.

For the KOKKOS package, using this command-line switch also invokes the default KOKKOS settings, as if the command “package kokkos” were used at the top of your input script. These settings can be changed by using the “-package kokkos” command-line switch or the package kokkos command in your script.

For the OMP package, using this command-line switch also invokes the default OMP settings, as if the command “package omp 0” were used at the top of your input script. These settings can be changed by using the “-package omp” command-line switch or the package omp command in your script.

The suffix command can also be used within an input script to set a suffix, or to turn off or back on any suffix setting made via the command line.

-var name value1 value2 ...

Specify a variable that will be defined for substitution purposes when the input script is read. This switch can be used multiple times to define multiple variables. “Name” is the variable name which can be a single character (referenced as $x in the input script) or a full string (referenced as ${abc}). An index-style variable will be created and populated with the subsequent values, e.g. a set of filenames. Using this command-line option is equivalent to putting the line “variable name index value1 value2 ...” at the beginning of the input script. Defining an index variable as a command-line argument overrides any setting for the same index variable in the input script, since index variables cannot be re-defined. See the variable command for more info on defining index and other kinds of variables and this section for more info on using variables in input scripts.

Note

Currently, the command-line parser looks for arguments that start with “-” to indicate new switches. Thus you cannot specify multiple variable values if any of they start with a “-”, e.g. a negative numeric value. It is OK if the first value1 starts with a “-”, since it is automatically skipped.

2.8. LAMMPS screen output

As LAMMPS reads an input script, it prints information to both the screen and a log file about significant actions it takes to setup a simulation. When the simulation is ready to begin, LAMMPS performs various initializations and prints the amount of memory (in MBytes per processor) that the simulation requires. It also prints details of the initial thermodynamic state of the system. During the run itself, thermodynamic information is printed periodically, every few timesteps. When the run concludes, LAMMPS prints the final thermodynamic state and a total run time for the simulation. It then appends statistics about the CPU time and storage requirements for the simulation. An example set of statistics is shown here:

Loop time of 2.81192 on 4 procs for 300 steps with 2004 atoms

Performance: 18.436 ns/day  1.302 hours/ns  106.689 timesteps/s
 97.0% CPU use with 4 MPI tasks x no OpenMP threads
 
MPI task timings breakdown:
 Section |  min time  |  avg time  |  max time  |%varavg| %total
 ---------------------------------------------------------------
 Pair    | 1.9808     | 2.0134     | 2.0318     |   1.4 | 71.60
 Bond    | 0.0021894  | 0.0060319  | 0.010058   |   4.7 |  0.21
 Kspace  | 0.3207     | 0.3366     | 0.36616    |   3.1 | 11.97
 Neigh   | 0.28411    | 0.28464    | 0.28516    |   0.1 | 10.12
 Comm    | 0.075732   | 0.077018   | 0.07883    |   0.4 |  2.74
 Output  | 0.00030518 | 0.00042665 | 0.00078821 |   1.0 |  0.02
 Modify  | 0.086606   | 0.086631   | 0.086668   |   0.0 |  3.08
 Other   |            | 0.007178   |            |       |  0.26
 
Nlocal:    501 ave 508 max 490 min
 Histogram: 1 0 0 0 0 0 1 1 0 1
 Nghost:    6586.25 ave 6628 max 6548 min
 Histogram: 1 0 1 0 0 0 1 0 0 1
 Neighs:    177007 ave 180562 max 170212 min
 Histogram: 1 0 0 0 0 0 0 1 1 1
 
Total # of neighbors = 708028
 Ave neighs/atom = 353.307
 Ave special neighs/atom = 2.34032
 Neighbor list builds = 26
 Dangerous builds = 0

The first section provides a global loop timing summary. The loop time is the total wall time for the section. The Performance line is provided for convenience to help predicting the number of loop continuations required and for comparing performance with other similar MD codes. The CPU use line provides the CPU utilzation per MPI task; it should be close to 100% times the number of OpenMP threads (or 1). Lower numbers correspond to delays due to file I/O or insufficient thread utilization.

The MPI task section gives the breakdown of the CPU run time (in seconds) into major categories:

  • Pair stands for all non-bonded force computation
  • Bond stands for bonded interactions: bonds, angles, dihedrals, impropers
  • Kspace stands for reciprocal space interactions: Ewald, PPPM, MSM
  • Neigh stands for neighbor list construction
  • Comm stands for communicating atoms and their properties
  • Output stands for writing dumps and thermo output
  • Modify stands for fixes and computes called by them
  • Other is the remaining time

For each category, there is a breakdown of the least, average and most amount of wall time a processor spent on this section. Also you have the variation from the average time. Together these numbers allow to gauge the amount of load imbalance in this segment of the calculation. Ideally the difference between minimum, maximum and average is small and thus the variation from the average close to zero. The final column shows the percentage of the total loop time is spent in this section.

When using the timer full setting, an additional column is present that also prints the CPU utilization in percent. In addition, when using timer full and the package omp command are active, a similar timing summary of time spent in threaded regions to monitor thread utilization and load balance is provided. A new entry is the Reduce section, which lists the time spend in reducing the per-thread data elements to the storage for non-threaded computation. These thread timings are taking from the first MPI rank only and and thus, as the breakdown for MPI tasks can change from MPI rank to MPI rank, this breakdown can be very different for individual ranks. Here is an example output for this section:

Thread timings breakdown (MPI rank 0):
 Total threaded time 0.6846 / 90.6%
 Section |  min time  |  avg time  |  max time  |%varavg| %total
 ---------------------------------------------------------------
 Pair    | 0.5127     | 0.5147     | 0.5167     |   0.3 | 75.18
 Bond    | 0.0043139  | 0.0046779  | 0.0050418  |   0.5 |  0.68
 Kspace  | 0.070572   | 0.074541   | 0.07851    |   1.5 | 10.89
 Neigh   | 0.084778   | 0.086969   | 0.089161   |   0.7 | 12.70
 Reduce  | 0.0036485  | 0.003737   | 0.0038254  |   0.1 |  0.55

The third section lists the number of owned atoms (Nlocal), ghost atoms (Nghost), and pair-wise neighbors stored per processor. The max and min values give the spread of these values across processors with a 10-bin histogram showing the distribution. The total number of histogram counts is equal to the number of processors.

The last section gives aggregate statistics for pair-wise neighbors and special neighbors that LAMMPS keeps track of (see the special_bonds command). The number of times neighbor lists were rebuilt during the run is given as well as the number of potentially “dangerous” rebuilds. If atom movement triggered neighbor list rebuilding (see the neigh_modify command), then dangerous reneighborings are those that were triggered on the first timestep atom movement was checked for. If this count is non-zero you may wish to reduce the delay factor to insure no force interactions are missed by atoms moving beyond the neighbor skin distance before a rebuild takes place.

If an energy minimization was performed via the minimize command, additional information is printed, e.g.

Minimization stats:
   Stopping criterion = linesearch alpha is zero
   Energy initial, next-to-last, final =
          -6372.3765206     -8328.46998942     -8328.46998942
   Force two-norm initial, final = 1059.36 5.36874
   Force max component initial, final = 58.6026 1.46872
   Final line search alpha, max atom move = 2.7842e-10 4.0892e-10
   Iterations, force evaluations = 701 1516

The first line prints the criterion that determined the minimization to be completed. The third line lists the initial and final energy, as well as the energy on the next-to-last iteration. The next 2 lines give a measure of the gradient of the energy (force on all atoms). The 2-norm is the “length” of this force vector; the inf-norm is the largest component. Then some information about the line search and statistics on how many iterations and force-evaluations the minimizer required. Multiple force evaluations are typically done at each iteration to perform a 1d line minimization in the search direction.

If a kspace_style long-range Coulombics solve was performed during the run (PPPM, Ewald), then additional information is printed, e.g.

FFT time (% of Kspce) = 0.200313 (8.34477)
 FFT Gflps 3d 1d-only = 2.31074 9.19989

The first line gives the time spent doing 3d FFTs (4 per timestep) and the fraction it represents of the total KSpace time (listed above). Each 3d FFT requires computation (3 sets of 1d FFTs) and communication (transposes). The total flops performed is 5Nlog_2(N), where N is the number of points in the 3d grid. The FFTs are timed with and without the communication and a Gflop rate is computed. The 3d rate is with communication; the 1d rate is without (just the 1d FFTs). Thus you can estimate what fraction of your FFT time was spent in communication, roughly 75% in the example above.

2.9. Tips for users of previous LAMMPS versions

The current C++ began with a complete rewrite of LAMMPS 2001, which was written in F90. Features of earlier versions of LAMMPS are listed in Section 13. The F90 and F77 versions (2001 and 99) are also freely distributed as open-source codes; check the LAMMPS WWW Site for distribution information if you prefer those versions. The 99 and 2001 versions are no longer under active development; they do not have all the features of C++ LAMMPS.

If you are a previous user of LAMMPS 2001, these are the most significant changes you will notice in C++ LAMMPS:

(1) The names and arguments of many input script commands have changed. All commands are now a single word (e.g. read_data instead of read data).

(2) All the functionality of LAMMPS 2001 is included in C++ LAMMPS, but you may need to specify the relevant commands in different ways.

(3) The format of the data file can be streamlined for some problems. See the read_data command for details. The data file section “Nonbond Coeff” has been renamed to “Pair Coeff” in C++ LAMMPS.

(4) Binary restart files written by LAMMPS 2001 cannot be read by C++ LAMMPS with a read_restart command. This is because they were output by F90 which writes in a different binary format than C or C++ writes or reads. Use the restart2data tool provided with LAMMPS 2001 to convert the 2001 restart file to a text data file. Then edit the data file as necessary before using the C++ LAMMPS read_data command to read it in.

(5) There are numerous small numerical changes in C++ LAMMPS that mean you will not get identical answers when comparing to a 2001 run. However, your initial thermodynamic energy and MD trajectory should be close if you have setup the problem for both codes the same.

\ No newline at end of file diff --git a/doc/html/atom_style.html b/doc/html/atom_style.html index 0ec90b2ce..21aa1f2d5 100644 --- a/doc/html/atom_style.html +++ b/doc/html/atom_style.html @@ -1,507 +1,507 @@ atom_style command — LAMMPS documentation

atom_style command

Syntax

 atom_style style args
  • style = angle or atomic or body or bond or charge or dipole or dpd or electron or ellipsoid or full or line or meso or molecular or peri or smd or sphere or tri or template or hybrid
 args = none for any style except the following
 body args = bstyle bstyle-args
   bstyle = style of body particles
   bstyle-args = additional arguments specific to the bstyle
                 see the body doc page for details
 template args = template-ID
   template-ID = ID of molecule template specified in a separate molecule command
 hybrid args = list of one or more sub-styles, each with their args
  • accelerated styles (with same args) = angle/kk or atomic/kk or bond/kk or charge/kk or full/kk or molecular/kk

Examples

 atom_style atomic
 atom_style bond
 atom_style full
 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 read_data, read_restart, or create_box command.

Note

Many of the atom styles discussed here are only enabled if LAMMPS was built with a specific package, as listed below in the Restrictions section.

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 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 read_data, create_atoms, and 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
dpd internal temperature and internal energies DPD 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 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 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 Section_howto 14 for an overview of using finite-size +body styles, which define finite-size particles. See Section 6.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 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 dpd style is for dissipative particle dynamics (DPD) particles. Note that it is part of the USER-DPD package, and is not for use with the pair_style dpd or dpd/stat commands, which can simply use atom_style atomic. Atom_style dpd extends DPD particle properties with internal temperature (dpdTheta), internal conductive energy (uCond), internal mechanical energy (uMech), and internal chemical energy (uChem).

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 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 (Grime), for examples of how this can be advantageous for large-scale coarse-grained systems.

Note

When using the template style with a molecule template 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 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 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 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 this section.

Styles with a 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 Section 5 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 KOKKOS package. They are only enabled if LAMMPS was built with those packages. See the Making LAMMPS section for more info.

You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.

See Section 5 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 read_data or create_box command.

Many of the styles listed above are only enabled if LAMMPS was built with a specific package, as listed below. See the Making LAMMPS section for more info.

The angle, bond, full, molecular, and template styles are part of the MOLECULE package.

The line and tri styles are part of the ASPHERE package.

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 electronic force fields.

The dpd style is part of the USER-DPD package for dissipative particle dynamics (DPD).

The meso style is part of the USER-SPH package for smoothed particle hydrodyanmics (SPH). See this PDF guide to using SPH in LAMMPS.

The wavepacket style is part of the USER-AWPMD package for the antisymmetrized wave packet MD method.

Default

atom_style atomic

(Grime) Grime and Voth, to appear in J Chem Theory & Computation (2014).

\ No newline at end of file diff --git a/doc/html/compute_angmom_chunk.html b/doc/html/compute_angmom_chunk.html index 88bb01d89..619b229f3 100644 --- a/doc/html/compute_angmom_chunk.html +++ b/doc/html/compute_angmom_chunk.html @@ -1,270 +1,270 @@ compute angmom/chunk command — LAMMPS documentation

compute angmom/chunk command

Syntax

compute ID group-ID angmom/chunk chunkID
  • ID, group-ID are documented in compute command
  • angmom/chunk = style name of this compute command
  • chunkID = ID of compute chunk/atom command

Examples

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 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 compute chunk/atom doc page and “Section_howto 23 for details of how chunks can be +molecule or atoms in a spatial bin. See the compute chunk/atom doc page and Section 6.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 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 dump custom command for a discussion of “unwrapped” coordinates. See the Atoms section of the 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 set image command.

The simplest way to output the results of the compute angmom/chunk calculation to a file is to use the fix ave/time command, for example:

 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 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 Section_howto 15 for an overview of LAMMPS output +values from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The array values are “intensive”. The array values will be in mass-velocity-distance units.

Restrictions

none
\ No newline at end of file diff --git a/doc/html/compute_basal_atom.html b/doc/html/compute_basal_atom.html index 683fcf61d..fe4f20db0 100644 --- a/doc/html/compute_basal_atom.html +++ b/doc/html/compute_basal_atom.html @@ -1,250 +1,250 @@ compute basal/atom command — LAMMPS documentation

compute basal/atom command

Syntax

compute ID group-ID basal/atom
  • ID, group-ID are documented in compute command
  • basal/atom = style name of this compute command

Examples

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 (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 Section_howto 15 for an overview of LAMMPS output +a compute as input. See Section 6.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 Making LAMMPS 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.

\ No newline at end of file diff --git a/doc/html/compute_centro_atom.html b/doc/html/compute_centro_atom.html index 5b1779546..bb862d687 100644 --- a/doc/html/compute_centro_atom.html +++ b/doc/html/compute_centro_atom.html @@ -1,328 +1,328 @@ compute centro/atom command — LAMMPS documentation

compute centro/atom command

Syntax

compute ID group-ID centro/atom lattice keyword value ...
  • ID, group-ID are documented in compute command centro/atom = style name of this compute command lattice = fcc or bcc or N = # of neighbors per atom to include
  • zero or more keyword/value pairs may be appended
  • keyword = axes
 axes value = no or yes
   no = do not calulate 3 symmetry axes
   yes = calulate 3 symmetry axes

Examples

compute 1 all centro/atom fcc
 
compute 1 all centro/atom 8

Description

Define a computation that calculates the centro-symmetry parameter for each atom in the group, for either FCC or BCC lattices, depending on the choice of the lattice argument. 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 (Kelchner)

_images/centro_symmetry.jpg

where the N nearest neighbors of 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.

If the keyword axes has the setting yes, then this compute also estimates three symmetry axes for each atom’s local neighborhood. The first two of these are the vectors joining the two pairs of neighbor atoms with smallest contributions to the centrosymmetry parameter, i.e. the two most symmetric pairs of atoms. The third vector is normal to the first two by the right-hand rule. All three vectors are normalized to unit length. For FCC crystals, the first two vectors will lie along a <110> direction, while the third vector will lie along either a <100> or <111> direction. For HCP crystals, the first two vectors will lie along <1000> directions, while the third vector will lie along <0001>. This provides a simple way to measure local orientation in HCP structures. In general, the axes keyword can be used to estimate the orientation of symmetry axes in the neighborhood of any atom.

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:

By default, this compute calculates the centrosymmetry value for each atom as 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 +uses per-atom values from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

If the axes keyword setting is yes, then a per-atom array is calculated. The first column is the centrosymmetry parameter. The next three columns are the x, y, and z components of the first symmetry axis, followed by the second, and third symmetry axes in columns 5-7 and 8-10.

The centrosymmetry 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. For the axes yes case, the vector components are also unitless, since they represent spatial directions.

Here are typical centro-symmetry values, from a a nanoindentation simulation into gold (FCC). These were provided by Jon Zimmerman (Sandia):

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:

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

Default

The default value for the optional keyword is axes = no.

(Kelchner) Kelchner, Plimpton, Hamilton, Phys Rev B, 58, 11085 (1998).

\ No newline at end of file diff --git a/doc/html/compute_chunk_atom.html b/doc/html/compute_chunk_atom.html index 817d51117..cf45a9f2a 100644 --- a/doc/html/compute_chunk_atom.html +++ b/doc/html/compute_chunk_atom.html @@ -1,769 +1,769 @@ compute chunk/atom command — LAMMPS documentation

compute chunk/atom command

Syntax

compute ID group-ID chunk/atom style args keyword values ...
  • ID, group-ID are documented in compute command
  • chunk/atom = style name of this compute command
 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
 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 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

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 compute, fix, or atom-style variable. Per-atom chunk IDs can be used by other computes with “chunk” in their style name, such as compute com/chunk or compute msd/chunk. Or they can be used by the 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 Section_howto 15.

+compute as input, as discussed in Section 6.15.

See Section 6.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 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 this section 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 create_box or 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 add them to LAMMPS.

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 add them to LAMMPS.

If a value begins with “v_”, a variable name for an atom or atomfile style 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 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 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 fix ave/chunk command invokes this compute.

Note that multiple 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 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 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 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 restart file, 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 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 compute property/chunk command and its id keyword, or by the 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 fix ave/chunk command, or by using the fix ave/time command in conjunction with the 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 units command, e.g. Angstroms for units = real or metal. A lattice value means the distance units are in lattice spacings. The 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 Section 6.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.

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
\ No newline at end of file diff --git a/doc/html/compute_com_chunk.html b/doc/html/compute_com_chunk.html index e2bce3f87..87dbed66a 100644 --- a/doc/html/compute_com_chunk.html +++ b/doc/html/compute_com_chunk.html @@ -1,268 +1,268 @@ compute com/chunk command — LAMMPS documentation

compute com/chunk command

Syntax

compute ID group-ID com/chunk chunkID
  • ID, group-ID are documented in compute command
  • com/chunk = style name of this compute command
  • chunkID = ID of compute chunk/atom command

Examples

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 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 compute chunk/atom doc page and “Section_howto 23 for details of how chunks can be +molecule or atoms in a spatial bin. See the compute chunk/atom doc page and Section 6.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 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 dump custom command for a discussion of “unwrapped” coordinates. See the Atoms section of the 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 set image command.

The simplest way to output the results of the compute com/chunk calculation to a file is to use the fix ave/time command, for example:

 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 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 Section_howto 15 for an overview of LAMMPS output +from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The array values are “intensive”. The array values will be in distance units.

Restrictions

none
\ No newline at end of file diff --git a/doc/html/compute_coord_atom.html b/doc/html/compute_coord_atom.html index 67663e1ce..35a778e63 100644 --- a/doc/html/compute_coord_atom.html +++ b/doc/html/compute_coord_atom.html @@ -1,276 +1,276 @@ compute coord/atom command — LAMMPS documentation

compute coord/atom command

Syntax

compute ID group-ID coord/atom cutoff type1 type2 ...
  • ID, group-ID are documented in 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

 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 special_bonds command can remove pairwise interactions between atoms in the same bond, angle, or dihedral. This is the default setting for the 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 rerun command to compute the coordination for snapshots in the dump file. The rerun script can use a 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 Section_howto 15 for an overview of LAMMPS output +per-atom values from a compute as input. See Section 6.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
\ No newline at end of file diff --git a/doc/html/compute_dipole_chunk.html b/doc/html/compute_dipole_chunk.html index efedfa051..4a16b859c 100644 --- a/doc/html/compute_dipole_chunk.html +++ b/doc/html/compute_dipole_chunk.html @@ -1,273 +1,273 @@ compute dipole/chunk command — LAMMPS documentation

compute dipole/chunk command

Syntax

compute ID group-ID dipole/chunk chunkID charge-correction
  • ID, group-ID are documented in compute command
  • dipole/chunk = style name of this compute command
  • chunkID = ID of compute chunk/atom command
  • charge-correction = mass or geometry, use COM or geometric center for charged chunk correction (optional)

Examples

compute 1 fluid dipole/chunk molchunk
 compute dw water dipole/chunk 1 geometry

Description

Define a computation that calculates the dipole vector and total dipole for multiple chunks of atoms.

In LAMMPS, chunks are collections of atoms defined by a 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 compute chunk/atom doc page and “Section_howto 23 for details of how chunks can be +molecule or atoms in a spatial bin. See the compute chunk/atom doc page and Section 6.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 dipole vector and the total dipole moment for each chunk, which includes all effects due to atoms passing thru periodic boundaries. For chunks with a net charge the resulting dipole is made position independent by subtracting the position vector of the center of mass or geometric center times the net charge from the computed dipole vector.

Note that only atoms in the specified group contribute to the calculation. The 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 dipole in “unwrapped” form, by using the image flags associated with each atom. See the dump custom command for a discussion of “unwrapped” coordinates. See the Atoms section of the 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 set image command.

The simplest way to output the results of the compute com/chunk calculation to a file is to use the fix ave/time command, for example:

 compute cc1 all chunk/atom molecule
 compute myChunk all dipole/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 compute chunk/atom command. The number of columns = 4 for the x,y,z dipole vector components and the total dipole of each chunk. These values can be accessed by any command that uses global -array values from a compute as input. See Section_howto 15 for an overview of LAMMPS output +array values from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The array values are “intensive”. The array values will be in dipole units, i.e. charge units times distance units.

Restrictions

none
\ No newline at end of file diff --git a/doc/html/compute_displace_atom.html b/doc/html/compute_displace_atom.html index 14b3b0528..7cded17a7 100644 --- a/doc/html/compute_displace_atom.html +++ b/doc/html/compute_displace_atom.html @@ -1,256 +1,256 @@ compute displace/atom command — LAMMPS documentation

compute displace/atom command

Syntax

compute ID group-ID displace/atom
  • ID, group-ID are documented in compute command
  • displace/atom = style name of this compute command

Examples

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 dump custom command for a discussion of “unwrapped” coordinates. See the Atoms section of the 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 set image command.

Note

If you want the quantities calculated by this compute to be continuous when running from a restart file, 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 Section_howto 15 for an overview of LAMMPS output +a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The per-atom array values will be in distance units.

Restrictions

none
\ No newline at end of file diff --git a/doc/html/compute_dpd_atom.html b/doc/html/compute_dpd_atom.html index ef2c8dedf..e3bbb3c7c 100644 --- a/doc/html/compute_dpd_atom.html +++ b/doc/html/compute_dpd_atom.html @@ -1,244 +1,244 @@ compute dpd/atom command — LAMMPS documentation

compute dpd/atom command

Syntax

compute ID group-ID dpd/atom
  • ID, group-ID are documented in compute command
  • dpd/atom = style name of this compute command

Examples

compute 1 all dpd/atom

Description

Define a computation that accesses the per-particle internal conductive energy (u_cond), internal mechanical energy (u_mech), internal chemical energy (u_chem) and internal temperatures (dpdTheta) for each particle in a group. See the compute dpd command if you want the total internal conductive energy, the total internal mechanical energy, the total chemical energy and average internal temperature of the entire system or group of dpd particles.

Output info:

This compute calculates a per-particle array with 4 columns (u_cond, u_mech, u_chem, dpdTheta), which can be accessed by indices 1-4 by any command that uses per-particle values from a compute as input. See -Section_howto15 for an overview of +Section 6.15 for an overview of LAMMPS output options.

The per-particle array values will be in energy (u_cond, u_mech, u_chem) and temperature (dpdTheta) units.

Restrictions

This command is part of the USER-DPD package. It is only enabled if LAMMPS was built with that package. See the Making LAMMPS section for more info.

This command also requires use of the atom_style dpd command.

\ No newline at end of file diff --git a/doc/html/compute_fep.html b/doc/html/compute_fep.html index 0824a98ae..982fd7097 100644 --- a/doc/html/compute_fep.html +++ b/doc/html/compute_fep.html @@ -1,447 +1,447 @@ compute fep command — LAMMPS documentation

compute fep command

Syntax

compute ID group-ID fep temp attribute args ... keyword value ...
  • ID, group-ID are documented in the 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
 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
 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

 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_0\) corresponding to the initial interactions of the atoms that will undergo perturbation, and a term \(U_1\) corresponding to the final interactions of these atoms:

_images/compute_fep_u.jpg

A coupling parameter \(\lambda\) varying from 0 to 1 connects the reference and perturbed systems:

_images/compute_fep_lambda.jpg

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 fix adapt to perform multistage free-energy perturbation calculations along stepwise alchemical transformations during a simulation run:

_images/compute_fep_fep.jpg

This compute is suitable for the finite-difference thermodynamic integration (FDTI) method (Mezei), which is based on an evaluation of the numerical derivative of the free energy by a perturbation method using a very small \(\delta\):

_images/compute_fep_fdti.jpg

where \(w_i\) are weights of a numerical quadrature. The 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_1 -U_0\). 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\):

_images/compute_fep_ti.jpg

Another technique to calculate free energy differences is the acceptance ratio method (Bennet), which can be implemented by calculating the potential energy differences with \(\delta\) = 1.0 on both the forward and reverse routes:

_images/compute_fep_bar.jpg

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 (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 (Boresch, Karplus).

The pair attribute enables various parameters of potentials defined by the pair_style and 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:

lj/cut epsilon,sigma type pairs
lj/cut/coul/cut epsilon,sigma type pairs
lj/cut/coul/long epsilon,sigma type pairs
lj/cut/soft epsilon,sigma,lambda type pairs
coul/cut/soft lambda type pairs
coul/long/soft lambda type pairs
lj/cut/coul/cut/soft epsilon,sigma,lambda type pairs
lj/cut/coul/long/soft epsilon,sigma,lambda type pairs
lj/cut/tip4p/long/soft epsilon,sigma,lambda type pairs
tip4p/long/soft lambda type pairs
lj/charmm/coul/long/soft epsilon,sigma,lambda type pairs
born a,b,c type pairs
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 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 pair_style hybrid or hybrid/overlay 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 pair_coeff command) for that sub-style.

The v_name argument for keyword pair is the name of an equal-style 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 equal-style 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 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 (Allen and Tildesley):

_images/compute_fep_vol.jpg

Output info:

This compute calculates a global vector of length 3 which contains the energy difference ( \(U_1-U_0\) ) as c_ID[1], the Boltzmann factor \(\exp(-(U_1-U_0)/kT)\), or \(V \exp(-(U_1-U_0)/kT)\), as c_ID[2] and the volume of the simulation box \(V\) as c_ID[3]. \(U_1\) is the pair potential energy obtained with the perturbed parameters and \(U_0\) 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 Section_howto 15 for an overview of LAMMPS output +scalar or vector from a compute as input. See Section 6.15 for an overview of LAMMPS output options. For example, the computed values can be averaged using 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 Making LAMMPS section for more info.

Default

The option defaults are tail = no, volume = no.

(Pearlman) Pearlman, J Chem Phys, 98, 1487 (1994)

(Mezei) Mezei, J Chem Phys, 86, 7084 (1987)

(Bennet) Bennet, J Comput Phys, 22, 245 (1976)

(BoreschKarplus) Boresch and Karplus, J Phys Chem A, 103, 103 (1999)

(AllenTildesley) Allen and Tildesley, Computer Simulation of Liquids, Oxford University Press (1987)

\ No newline at end of file diff --git a/doc/html/compute_gyration.html b/doc/html/compute_gyration.html index 9d92b09b0..ce2d46809 100644 --- a/doc/html/compute_gyration.html +++ b/doc/html/compute_gyration.html @@ -1,256 +1,256 @@ compute gyration command — LAMMPS documentation

compute gyration command

Syntax

compute ID group-ID gyration
  • ID, group-ID are documented in compute command
  • gyration = style name of this compute command

Examples

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

_images/compute_gyration.jpg

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 dump custom command for a discussion of “unwrapped” coordinates. See the Atoms section of the 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 set image 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 Section_howto 15 for an overview of LAMMPS output +vector values from a compute as input. See Section 6.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 units respectively.

Restrictions

none
\ No newline at end of file diff --git a/doc/html/compute_gyration_chunk.html b/doc/html/compute_gyration_chunk.html index 3ec0dca37..71d868cd8 100644 --- a/doc/html/compute_gyration_chunk.html +++ b/doc/html/compute_gyration_chunk.html @@ -1,287 +1,287 @@ compute gyration/chunk command — LAMMPS documentation

compute gyration/chunk command

Syntax

compute ID group-ID gyration/chunk chunkID keyword value ...
  • ID, group-ID are documented in compute command
  • gyration/chunk = style name of this compute command
  • chunkID = ID of compute chunk/atom command
  • zero or more keyword/value pairs may be appended
  • keyword = tensor
 tensor value = none

Examples

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 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 compute chunk/atom doc page and “Section_howto 23 for details of how chunks can be +molecule or atoms in a spatial bin. See the compute chunk/atom doc page and Section 6.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

_images/compute_gyration.jpg

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 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 dump custom command for a discussion of “unwrapped” coordinates. See the Atoms section of the 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 set image command.

The simplest way to output the results of the compute gyration/chunk calculation to a file is to use the fix ave/time command, for example:

 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 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 this section 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 units, since they are the square root of values represented by the formula above.

Restrictions

none

Related commands: none

compute gyration

Default: none

\ No newline at end of file diff --git a/doc/html/compute_hexorder_atom.html b/doc/html/compute_hexorder_atom.html index 7f7ef8f45..da55aa52d 100644 --- a/doc/html/compute_hexorder_atom.html +++ b/doc/html/compute_hexorder_atom.html @@ -1,296 +1,296 @@ compute hexorder/atom command — LAMMPS documentation

compute hexorder/atom command

Syntax

compute ID group-ID hexorder/atom keyword values ...
  • ID, group-ID are documented in compute command
  • hexorder/atom = style name of this compute command
  • one or more keyword/value pairs may be appended
 keyword = degree or nnn or cutoff
   cutoff value = distance cutoff
   nnn value = number of nearest neighbors
   degree value = degree n of order parameter

Examples

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 Nelson and Halperin 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:

_images/hexorder.jpg

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, q6 = 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 q6 is averaged over all the atoms in the system, |<q6>| << 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 special_bonds command can remove pairwise interactions between atoms in the same bond, angle, or dihedral. This is the default setting for the 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 rerun command to compute the order parameter for snapshots in the dump file. The rerun script can use a 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 Section_howto 15 for an overview of LAMMPS output +per-atom values from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

Restrictions

none

Default

The option defaults are cutoff = pair style cutoff, nnn = 6, degree = 6

(Nelson) Nelson, Halperin, Phys Rev B, 19, 2457 (1979).

\ No newline at end of file diff --git a/doc/html/compute_inertia_chunk.html b/doc/html/compute_inertia_chunk.html index d718f90f4..102400c23 100644 --- a/doc/html/compute_inertia_chunk.html +++ b/doc/html/compute_inertia_chunk.html @@ -1,269 +1,269 @@ compute inertia/chunk command — LAMMPS documentation

compute inertia/chunk command

Syntax

compute ID group-ID inertia/chunk chunkID
  • ID, group-ID are documented in compute command
  • inertia/chunk = style name of this compute command
  • chunkID = ID of compute chunk/atom command

Examples

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 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 compute chunk/atom doc page and “Section_howto 23 for details of how chunks can be +molecule or atoms in a spatial bin. See the compute chunk/atom doc page and Section 6.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 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 dump custom command for a discussion of “unwrapped” coordinates. See the Atoms section of the 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 set image command.

The simplest way to output the results of the compute inertia/chunk calculation to a file is to use the fix ave/time command, for example:

 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 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 Section_howto 15 for an overview of LAMMPS output +uses global array values from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The array values are “intensive”. The array values will be in mass*distance^2 units.

Restrictions

none
\ No newline at end of file diff --git a/doc/html/compute_ke_rigid.html b/doc/html/compute_ke_rigid.html index 27c5451b2..36653ade5 100644 --- a/doc/html/compute_ke_rigid.html +++ b/doc/html/compute_ke_rigid.html @@ -1,240 +1,240 @@ compute ke/rigid command — LAMMPS documentation

compute ke/rigid command

Syntax

compute ID group-ID ke/rigid fix-ID
  • ID, group-ID are documented in compute command
  • ke = style name of this compute command
  • fix-ID = ID of rigid body fix

Examples

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 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 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 Section_howto 15 for an overview of LAMMPS output +global scalar value from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The scalar value calculated by this compute is “extensive”. The scalar value will be in energy units.

Restrictions

This compute is part of the RIGID package. It is only enabled if LAMMPS was built with that package. See the Making LAMMPS section for more info.

\ No newline at end of file diff --git a/doc/html/compute_msd_chunk.html b/doc/html/compute_msd_chunk.html index 2ef599ab2..024d81682 100644 --- a/doc/html/compute_msd_chunk.html +++ b/doc/html/compute_msd_chunk.html @@ -1,305 +1,305 @@ compute msd/chunk command — LAMMPS documentation

compute msd/chunk command

Syntax

compute ID group-ID msd/chunk chunkID
  • ID, group-ID are documented in compute command
  • msd/chunk = style name of this compute command
  • chunkID = ID of compute chunk/atom command

Examples

compute 1 all msd/chunk molchunk

Description

Define a computation that calculates the mean-squared displacement (MSD) for multiple chunks of atoms.

In LAMMPS, chunks are collections of atoms defined by a 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 compute chunk/atom doc page and “Section_howto 23 for details of how chunks can be +molecule or atoms in a spatial bin. See the compute chunk/atom doc page and Section 6.23 for details of how chunks can be defined and examples of how they can be used to measure properties of a system.

Four quantites are calculated by this compute for each chunk. The first 3 quantities are the squared dx,dy,dz displacements of the center-of-mass. The 4th component is the total squared displacement, i.e. (dx*dx + dy*dy + dz*dz) of the center-of-mass. These calculations include all effects due to atoms passing thru periodic boundaries.

Note that only atoms in the specified group contribute to the calculation. The compute chunk/atom command defines its own group; atoms will have a chunk ID = 0 if they are not in that group, signifying they are not assigned to a chunk, and will thus also not contribute to this calculation. You can specify the “all” group for this command if you simply want to include atoms with non-zero chunk IDs.

The slope of the mean-squared displacement (MSD) versus time is proportional to the diffusion coefficient of the diffusing chunks.

The displacement of the center-of-mass of the chunk is from its original center-of-mass position, calculated on the timestep this compute command was first invoked.

Note

The number of chunks Nchunk calculated by the compute chunk/atom command must remain constant each time this compute is invoked, so that the displacement for each chunk from its original position can be computed consistently. If Nchunk does not remain constant, an error will be generated. If needed, you can enforce a constant Nchunk by using the nchunk once or ids once options when specifying the compute chunk/atom command.

Note

This compute stores the original position (of the center-of-mass) of each chunk. When a displacement is calculated on a later timestep, it is assumed that the same atoms are assigned to the same chunk ID. However LAMMPS has no simple way to insure this is the case, though you can use the ids once option when specifying the compute chunk/atom command. Note that if this is not the case, the MSD calculation does not have a sensible meaning.

Note

The initial coordinates of the atoms in each chunk are stored in “unwrapped” form, by using the image flags associated with each atom. See the dump custom command for a discussion of “unwrapped” coordinates. See the Atoms section of the 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 set image command.

Note

If you want the quantities calculated by this compute to be continuous when running from a restart file, 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-chunk quantities will also have the same ID, and thus be initialized correctly with chunk reference positions from the restart file.

The simplest way to output the results of the compute com/msd calculation to a file is to use the fix ave/time command, for example:

 compute cc1 all chunk/atom molecule
 compute myChunk all com/msd 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 compute chunk/atom command. The number of columns = 4 for dx,dy,dz and the total displacement. These values can be accessed by any command that uses global array values from a compute as input. See this section for an overview of LAMMPS output options.

The array values are “intensive”. The array values will be in distance^2 units.

Restrictions

none
\ No newline at end of file diff --git a/doc/html/compute_omega_chunk.html b/doc/html/compute_omega_chunk.html index cb2e60090..a2c9a0511 100644 --- a/doc/html/compute_omega_chunk.html +++ b/doc/html/compute_omega_chunk.html @@ -1,270 +1,270 @@ compute omega/chunk command — LAMMPS documentation

compute omega/chunk command

Syntax

compute ID group-ID omega/chunk chunkID
  • ID, group-ID are documented in compute command
  • omega/chunk = style name of this compute command
  • chunkID = ID of compute chunk/atom command

Examples

compute 1 fluid omega/chunk molchunk

Description

Define a computation that calculates the angular velocity (omega) of multiple chunks of atoms.

In LAMMPS, chunks are collections of atoms defined by a 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 compute chunk/atom doc page and “Section_howto 23 for details of how chunks can be +molecule or atoms in a spatial bin. See the compute chunk/atom doc page and Section 6.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 velocity vector for each chunk, via the formula L = Iw where L is the angular momentum vector of the chunk, I is its moment of inertia tensor, and w is omega = angular velocity 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 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 velocity in “unwrapped” form, by using the image flags associated with each atom. See the dump custom command for a discussion of “unwrapped” coordinates. See the Atoms section of the 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 set image command.

The simplest way to output the results of the compute omega/chunk calculation to a file is to use the fix ave/time command, for example:

 compute cc1 all chunk/atom molecule
 compute myChunk all omega/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 compute chunk/atom command. The number of columns = 3 for the 3 xyz components of the angular velocity for each chunk. These values can be accessed by any command that uses global array -values from a compute as input. See Section_howto 15 for an overview of LAMMPS output +values from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The array values are “intensive”. The array values will be in velocity/distance units.

Restrictions

none
\ No newline at end of file diff --git a/doc/html/compute_orientorder_atom.html b/doc/html/compute_orientorder_atom.html index f3d10f42e..d4ac7d41d 100644 --- a/doc/html/compute_orientorder_atom.html +++ b/doc/html/compute_orientorder_atom.html @@ -1,300 +1,300 @@ compute orientorder/atom command — LAMMPS documentation

compute orientorder/atom command

Syntax

compute ID group-ID orientorder/atom keyword values ...
  • ID, group-ID are documented in compute command
  • orientorder/atom = style name of this compute command
  • one or more keyword/value pairs may be appended
 keyword = cutoff or nnn or ql
   cutoff value = distance cutoff
   nnn value = number of nearest neighbors
   degrees values = nlvalues, l1, l2,...

Examples

compute 1 all orientorder/atom
 compute 1 all orientorder/atom degrees 5 4 6 8 10 12 nnn NULL cutoff 1.5

Description

Define a computation that calculates a set of bond-orientational order parameters Ql for each atom in a group. These order parameters were introduced by Steinhardt et al. as a way to characterize the local orientational order in atomic structures. For each atom, Ql is a real number defined as follows:

_images/orientorder.jpg

The first equation defines the spherical harmonic order parameters. These are complex number components of the 3D analog of the 2D order parameter qn, which is implemented as LAMMPS compute hexorder/atom. The summation is over the nnn nearest neighbors of the central atom. The angles theta and phi are the standard spherical polar angles defining the direction of the bond vector rij. The second equation defines Ql, which is a rotationally invariant scalar quantity obtained by summing over all the components of degree l.

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 Ql. The default value is 12. If the value is NULL, then all neighbors up to the specified distance cutoff are used.

The optional keyword degrees defines the list of order parameters to be computed. The first argument nlvalues is the number of order parameters. This is followed by that number of integers giving the degree of each order parameter. Because Q2 and all odd-degree order parameters are zero for atoms in cubic crystals (see Steinhardt), the default order parameters are Q4, Q6, Q8, Q10, and Q12. For the FCC crystal with nnn=12, Q4 = sqrt(7/3)/8 = 0.19094.... The numerical values of all order parameters up to Q12 for a range of commonly encountered high-symmetry structures are given in Table I of Mickel et al..

The value of Ql is set to zero for atoms not in the specified compute group, as well as for atoms that have less than nnn neighbors within the distance cutoff.

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 special_bonds command can remove pairwise interactions between atoms in the same bond, angle, or dihedral. This is the default setting for the 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 rerun command to compute the order parameter for snapshots in the dump file. The rerun script can use a special_bonds command that includes all pairs in the neighbor list.

Output info:

This compute calculates a per-atom array with nlvalues columns, giving the Ql values for each atom, which are real numbers on the range 0 <= Ql <= 1.

These values 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 +per-atom values from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

Restrictions

none

Default

The option defaults are cutoff = pair style cutoff, nnn = 12, degrees = 5 4 6 8 9 10 12 i.e. Q4, Q6, Q8, Q10, and Q12.

(Steinhardt) P. Steinhardt, D. Nelson, and M. Ronchetti, Phys. Rev. B 28, 784 (1983).

(Mickel) W. Mickel, S. C. Kapfer, G. E. Schroeder-Turkand, K. Mecke, J. Chem. Phys. 138, 044501 (2013).

\ No newline at end of file diff --git a/doc/html/compute_pe.html b/doc/html/compute_pe.html index 6d81108da..f5520b05d 100644 --- a/doc/html/compute_pe.html +++ b/doc/html/compute_pe.html @@ -1,263 +1,263 @@ compute pe command — LAMMPS documentation

compute pe command

Syntax

compute ID group-ID pe keyword ...
  • ID, group-ID are documented in compute command
  • pe = style name of this compute command
  • zero or more keywords may be appended
  • keyword = pair or bond or angle or dihedral or improper or kspace or fix

Examples

compute 1 all pe
 compute molPE all pe bond angle dihedral improper

Description

Define a computation that calculates the potential energy of the entire system of atoms. The specified group must be “all”. See the compute pe/atom command if you want per-atom energies. These per-atom values could be summed for a group of atoms via the compute reduce command.

The energy is calculated by the various pair, bond, etc potentials defined for the simulation. If no extra keywords are listed, then the potential energy is the sum of pair, bond, angle, dihedral, improper, kspace (long-range), and fix energy. I.e. it is as if all the keywords were listed. If any extra keywords are listed, then only those components are summed to compute the potential energy.

The Kspace contribution requires 1 extra FFT each timestep the energy is calculated, if using the PPPM solver via the kspace_style pppm command. Thus it can increase the cost of the PPPM calculation if it is needed on a large fraction of the simulation timesteps.

Various fixes can contribute to the total potential energy of the system if the fix contribution is included. See the doc pages for individual fixes for details of which ones compute a potential energy.

Note

The fix_modify energy yes command must also be specified if a fix is to contribute potential energy to this command.

A compute of this style with the ID of “thermo_pe” is created when LAMMPS starts up, as if this command were in the input script:

 compute thermo_pe all pe

See the “thermo_style” command for more details.

Output info:

This compute calculates a global scalar (the potential energy). This value can be used by any command that uses a global scalar value from -a compute as input. See Section_howto 15 for an overview of LAMMPS output +a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The scalar value calculated by this compute is “extensive”. The scalar value will be in energy units.

Restrictions

none
\ No newline at end of file diff --git a/doc/html/compute_property_chunk.html b/doc/html/compute_property_chunk.html index 7cf73b649..9f1abcd41 100644 --- a/doc/html/compute_property_chunk.html +++ b/doc/html/compute_property_chunk.html @@ -1,291 +1,291 @@ compute property/chunk command — LAMMPS documentation

compute property/chunk command

Syntax

compute ID group-ID property/chunk chunkID input1 input2 ...
  • ID, group-ID are documented in compute command
  • property/chunk = style name of this compute command
  • input = one or more attributes
 attributes = count, id, coord1, coord2, coord3
   count = # of atoms in chunk
   id = original chunk IDs before compression by compute chunk/atom
   coord123 = coordinates for spatial bins calculated by compute chunk/atom

Examples

compute 1 all property/chunk count
 compute 1 all property/chunk ID coord1

Description

Define a computation that stores the specified attributes of chunks of atoms.

In LAMMPS, chunks are collections of atoms defined by a 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 compute chunk/atom doc page and “Section_howto 23 for details of how chunks can be +molecule or atoms in a spatial bin. See the compute chunk/atom doc page and Section 6.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 and stores the specified attributes of chunks as global data so they can be accessed by other output commands and used in conjunction with other commands that generate per-chunk data, such as compute com/chunk or compute msd/chunk.

Note that only atoms in the specified group contribute to the calculation of the count attribute. The compute chunk/atom command defines its own group; atoms will have a chunk ID = 0 if they are not in that group, signifying they are not assigned to a chunk, and will thus also not contribute to this calculation. You can specify the “all” group for this command if you simply want to include atoms with non-zero chunk IDs.

The count attribute is the number of atoms in the chunk.

The id attribute stores the original chunk ID for each chunk. It can only be used if the compress keyword was set to yes for the compute chunk/atom command referenced by chunkID. This means that the original chunk IDs (e.g. molecule IDs) will have been compressed to remove chunk IDs with no atoms assigned to them. Thus a compresed chunk ID of 3 may correspond to an original chunk ID (molecule ID in this case) of 415. The id attribute will then be 415 for the 3rd chunk.

The coordN attributes can only be used if a binning style was used in the compute chunk/atom command referenced by chunkID. For bin/1d, bin/2d, and bin/3d styles the attribute is the center point of the bin in the corresponding dimension. Style bin/1d only defines a coord1 attribute. Style bin/2d adds a coord2 attribute. Style bin/3d adds a coord3 attribute.

Note that if the value of the units keyword used in the compute chunk/atom command is box or lattice, the coordN attributes will be in distance units. If the value of the units keyword is reduced, the coordN attributes will be in unitless reduced units (0-1).

The simplest way to output the results of the compute property/chunk calculation to a file is to use the fix ave/time command, for example:

 compute cc1 all chunk/atom molecule
 compute myChunk1 all property/chunk cc1 count
 compute myChunk2 all com/chunk cc1
 fix 1 all ave/time 100 1 100 c_myChunk1 c_myChunk2[*] file tmp.out mode vector

Output info:

This compute calculates a global vector or global array depending on the number of input values. The length of the vector or number of rows in the array is the number of chunks.

This compute calculates a global vector or global array where the number of rows = the number of chunks Nchunk as calculated by the specified compute chunk/atom command. If a single input is specified, a global vector is produced. If two or more inputs are specified, a global array is produced where the number of columns = the number of inputs. The vector or array can be accessed by any command that uses global values from a compute as input. See this section for an overview of LAMMPS output options.

The vector or array values are “intensive”. The values will be unitless or in the units discussed above.

Restrictions

none
\ No newline at end of file diff --git a/doc/html/compute_smd_ulsph_strain_rate.html b/doc/html/compute_smd_ulsph_strain_rate.html index 0f60ae8ef..239ca6516 100644 --- a/doc/html/compute_smd_ulsph_strain_rate.html +++ b/doc/html/compute_smd_ulsph_strain_rate.html @@ -1,237 +1,237 @@ compute smd/ulsph/strain/rate command — LAMMPS documentation

compute smd/ulsph/strain/rate command

Syntax

compute ID group-ID smd/ulsph/strain/rate
  • ID, group-ID are documented in compute command
  • smd/ulsph/strain/rate = style name of this compute command

Examples

compute 1 all smd/ulsph/strain/rate

Description

Define a computation that outputs the rate of the logarithmic strain tensor for particles interacting via the updated Lagrangian SPH pair style.

See this PDF guide to using Smooth Mach Dynamics in LAMMPS.

Output info:

This compute calculates a per-particle vector of vectors (tensors), which can be accessed by any command that uses per-particle values -from a compute as input. See Section_howto 15 for an overview of LAMMPS output +from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The values will be given in units of one over time.

The per-particle vector has 6 entries, corresponding to the xx, yy, zz, xy, xz, yz components of the symmetric strain rate tensor.

Restrictions

This compute is part of the USER-SMD package. It is only enabled if LAMMPS was built with that package. See the Making LAMMPS section for more info. This compute can only be used for particles which interact with the updated Lagrangian SPH pair style.

\ No newline at end of file diff --git a/doc/html/compute_smd_ulsph_stress.html b/doc/html/compute_smd_ulsph_stress.html index 51654a43e..9d4e7e9df 100644 --- a/doc/html/compute_smd_ulsph_stress.html +++ b/doc/html/compute_smd_ulsph_stress.html @@ -1,237 +1,237 @@ compute smd/ulsph/stress command — LAMMPS documentation

compute smd/ulsph/stress command

Syntax

compute ID group-ID smd/ulsph/stress
  • ID, group-ID are documented in compute command
  • smd/ulsph/stress = style name of this compute command

Examples

compute 1 all smd/ulsph/stress

Description

Define a computation that outputs the Cauchy stress tensor.

See this PDF guide to using Smooth Mach Dynamics in LAMMPS.

Output info:

This compute calculates a per-particle vector of vectors (tensors), which can be accessed by any command that uses per-particle values -from a compute as input. See Section_howto 15 for an overview of LAMMPS output +from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The values will be given in units of pressure.

The per-particle vector has 7 entries. The first six entries correspond to the xx, yy, zz, xy, xz, yz components of the symmetric Cauchy stress tensor. The seventh entry is the second invariant of the stress tensor, i.e., the von Mises equivalent stress.

Restrictions

This compute is part of the USER-SMD package. It is only enabled if LAMMPS was built with that package. See the Making LAMMPS section for more info. This compute can only be used for particles which interact with the updated Lagrangian SPH pair style.

\ No newline at end of file diff --git a/doc/html/compute_sna_atom.html b/doc/html/compute_sna_atom.html index 930f66a12..f95049436 100644 --- a/doc/html/compute_sna_atom.html +++ b/doc/html/compute_sna_atom.html @@ -1,396 +1,396 @@ compute sna/atom command — LAMMPS documentation

compute sna/atom command

compute snad/atom command

compute snav/atom command

Syntax

 compute ID group-ID sna/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ...
 compute ID group-ID snad/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ...
 compute ID group-ID snav/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ...
  • ID, group-ID are documented in compute command
  • sna/atom = style name of this compute command
  • rcutfac = scale factor applied to all cutoff radii (positive real)
  • rfac0 = parameter in distance to angle conversion (0 < rcutfac < 1)
  • twojmax = band limit for bispectrum components (non-negative integer)
  • R_1, R_2,... = list of cutoff radii, one for each type (distance units)
  • w_1, w_2,... = list of neighbor weights, one for each type
  • zero or more keyword/value pairs may be appended
  • keyword = diagonal or rmin0 or switchflag
 diagonal value = 0 or 1 or 2 or 3
    0 = all j1, j2, j <= twojmax, j2 <= j1
    1 = subset satisfying j1 == j2
    2 = subset satisfying j1 == j2 == j3
    3 = subset satisfying j2 <= j1 <= j
 rmin0 value = parameter in distance to angle conversion (distance units)
 switchflag value = 0 or 1
    0 = do not use switching function
    1 = use switching function

Examples

compute b all sna/atom 1.4 0.99363 6 2.0 2.4 0.75 1.0 diagonal 3 rmin0 0.0
 compute db all sna/atom 1.4 0.95 6 2.0 1.0
 compute vb all sna/atom 1.4 0.95 6 2.0 1.0

Description

Define a computation that calculates a set of bispectrum components for each atom in a group.

Bispectrum components of an atom are order parameters characterizing the radial and angular distribution of neighbor atoms. The detailed mathematical definition is given in the paper by Thompson et al. (Thompson)

The position of a neighbor atom i’ relative to a central atom i is a point within the 3D ball of radius R_ii’ = rcutfac*(R_i + R_i’)

Bartok et al. (Bartok), proposed mapping this 3D ball onto the 3-sphere, the surface of the unit ball in a four-dimensional space. The radial distance r within R_ii’ is mapped on to a third polar angle theta0 defined by,

_images/compute_sna_atom1.jpg

In this way, all possible neighbor positions are mapped on to a subset of the 3-sphere. Points south of the latitude theta0max=rfac0*Pi are excluded.

The natural basis for functions on the 3-sphere is formed by the 4D hyperspherical harmonics U^j_m,m’(theta, phi, theta0). These functions are better known as D^j_m,m’, the elements of the Wigner D-matrices (Meremianin, Varshalovich).

The density of neighbors on the 3-sphere can be written as a sum of Dirac-delta functions, one for each neighbor, weighted by species and radial distance. Expanding this density function as a generalized Fourier series in the basis functions, we can write each Fourier coefficient as

_images/compute_sna_atom2.jpg

The w_i’ neighbor weights are dimensionless numbers that are chosen to distinguish atoms of different types, while the central atom is arbitrarily assigned a unit weight. The function fc(r) ensures that the contribution of each neighbor atom goes smoothly to zero at R_ii’:

_images/compute_sna_atom4.jpg

The expansion coefficients u^j_m,m’ are complex-valued and they are not directly useful as descriptors, because they are not invariant under rotation of the polar coordinate frame. However, the following scalar triple products of expansion coefficients can be shown to be real-valued and invariant under rotation (Bartok).

_images/compute_sna_atom3.jpg

The constants H^jmm’_j1m1m1’_j2m2m2’ are coupling coefficients, analogous to Clebsch-Gordan coefficients for rotations on the 2-sphere. These invariants are the components of the bispectrum and these are the quantities calculated by the compute sna/atom. They characterize the strength of density correlations at three points on the 3-sphere. The j2=0 subset form the power spectrum, which characterizes the correlations of two points. The lowest-order components describe the coarsest features of the density function, while higher-order components reflect finer detail. Note that the central atom is included in the expansion, so three point-correlations can be either due to three neighbors, or two neighbors and the central atom.

Compute snad/atom calculates the derivative of the bispectrum components summed separately for each atom type:

_images/compute_sna_atom5.jpg

The sum is over all atoms i’ of atom type I. For each atom i, this compute evaluates the above expression for each direction, each atom type, and each bispectrum component. See section below on output for a detailed explanation.

Compute snav/atom calculates the virial contribution due to the derivatives:

_images/compute_sna_atom6.jpg

Again, the sum is over all atoms i’ of atom type I. For each atom i, this compute evaluates the above expression for each of the six virial components, each atom type, and each bispectrum component. See section below on output for a detailed explanation.

The value of all bispectrum components will be zero for atoms not in the group. Neighbor atoms not in the group do not contribute to the bispectrum of atoms in the 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.

The argument rcutfac is a scale factor that controls the ratio of atomic radius to radial cutoff distance.

The argument rfac0 and the optional keyword rmin0 define the linear mapping from radial distance to polar angle theta0 on the 3-sphere.

The argument twojmax and the keyword diagonal define which bispectrum components are generated. See section below on output for a detailed explanation of the number of bispectrum components and the ordered in which they are listed

The keyword switchflag can be used to turn off the switching function.

Note

If you have a bonded system, then the settings of special_bonds command can remove pairwise interactions between atoms in the same bond, angle, or dihedral. This is the default setting for the 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 calculation. One way to get around this, is to write a dump file, and use the rerun command to compute the bispectrum components for snapshots in the dump file. The rerun script can use a special_bonds command that includes all pairs in the neighbor list.

;line

Output info:

Compute sna/atom calculates a per-atom array, each column corresponding to a particular bispectrum component. The total number of columns and the identities of the bispectrum component contained in each column depend on the values of twojmax and diagonal, as described by the following piece of python code:

 for j1 in range(0,twojmax+1):
     if(diagonal==2):
         print j1/2.,j1/2.,j1/2.
     elif(diagonal==1):
         for j in range(0,min(twojmax,2*j1)+1,2):
             print j1/2.,j1/2.,j/2.
     elif(diagonal==0):
         for j2 in range(0,j1+1):
             for j in range(j1-j2,min(twojmax,j1+j2)+1,2):
                 print j1/2.,j2/2.,j/2.
     elif(diagonal==3):
         for j2 in range(0,j1+1):
             for j in range(j1-j2,min(twojmax,j1+j2)+1,2):
                 if (j>=j1): print j1/2.,j2/2.,j/2.

Compute snad/atom evaluates a per-atom array. The columns are arranged into ntypes blocks, listed in order of atom type I. Each block contains three sub-blocks corresponding to the x, y, and z components of the atom position. Each of these sub-blocks contains one column for each bispectrum component, the same as for compute sna/atom

Compute snav/atom evaluates a per-atom array. The columns are arranged into ntypes blocks, listed in order of atom type I. Each block contains six sub-blocks corresponding to the xx, yy, zz, yz, xz, and xy components of the virial tensor in Voigt notation. Each of these sub-blocks contains one column for each bispectrum component, the same as for compute sna/atom

These values 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 +from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

Restrictions

These computes are part of the SNAP package. They are only enabled if LAMMPS was built with that package. See the Making LAMMPS section for more info.

Default

The optional keyword defaults are diagonal = 0, rmin0 = 0, switchflag = 1.

(Thompson) Thompson, Swiler, Trott, Foiles, Tucker, under review, preprint available at arXiv:1409.3880

(Bartok) Bartok, Payne, Risi, Csanyi, Phys Rev Lett, 104, 136403 (2010).

(Meremianin) Meremianin, J. Phys. A, 39, 3099 (2006).

(Varshalovich) Varshalovich, Moskalev, Khersonskii, Quantum Theory of Angular Momentum, World Scientific, Singapore (1987).

\ No newline at end of file diff --git a/doc/html/compute_stress_atom.html b/doc/html/compute_stress_atom.html index c4704bbbb..8c0ad47f0 100644 --- a/doc/html/compute_stress_atom.html +++ b/doc/html/compute_stress_atom.html @@ -1,329 +1,329 @@ compute stress/atom command — LAMMPS documentation

compute stress/atom command

Syntax

compute ID group-ID stress/atom temp-ID keyword ...
  • ID, group-ID are documented in compute command
  • stress/atom = style name of this compute command
  • temp-ID = ID of compute that calculates temperature, can be NULL if not needed
  • zero or more keywords may be appended
  • keyword = ke or pair or bond or angle or dihedral or improper or kspace or fix or virial

Examples

compute 1 mobile stress/atom NULL
 compute 1 mobile stress/atom myRamp
 compute 1 all stress/atom NULL pair bond

Description

Define a computation that computes the symmetric per-atom stress tensor for each atom in a group. The tensor for each atom has 6 components and is stored as a 6-element vector in the following order: xx, yy, zz, xy, xz, yz. See the compute pressure command if you want the stress tensor (pressure) of the entire system.

The stress tensor for atom I is given by the following formula, where a and b take on values x,y,z to generate the 6 components of the symmetric tensor:

_images/stress_tensor.jpg

The first term is a kinetic energy contribution for atom I. See details below on how the specified temp-ID can affect the velocities used in this calculation. The second term is a pairwise energy contribution where n loops over the Np neighbors of atom I, r1 and r2 are the positions of the 2 atoms in the pairwise interaction, and F1 and F2 are the forces on the 2 atoms resulting from the pairwise interaction. The third term is a bond contribution of similar form for the Nb bonds which atom I is part of. There are similar terms for the Na angle, Nd dihedral, and Ni improper interactions atom I is part of. There is also a term for the KSpace contribution from long-range Coulombic interactions, if defined. Finally, there is a term for the Nf fixes that apply internal constraint forces to atom I. Currently, only the fix shake and fix rigid commands contribute to this term.

As the coefficients in the formula imply, a virial contribution produced by a small set of atoms (e.g. 4 atoms in a dihedral or 3 atoms in a Tersoff 3-body interaction) is assigned in equal portions to each atom in the set. E.g. 1/4 of the dihedral virial to each of the 4 atoms, or 1/3 of the fix virial due to SHAKE constraints applied to atoms in a a water molecule via the fix shake command.

If no extra keywords are listed, all of the terms in this formula are included in the per-atom stress tensor. If any extra keywords are listed, only those terms are summed to compute the tensor. The virial keyword means include all terms except the kinetic energy ke.

Note that the stress for each atom is due to its interaction with all other atoms in the simulation, not just with other atoms in the group.

Details of how LAMMPS computes the virial for individual atoms for either pairwise or manybody potentials, and including the effects of periodic boundary conditions is discussed in (Thompson). The basic idea for manybody potentials is to treat each component of the force computation between a small cluster of atoms in the same manner as in the formula above for bond, angle, dihedral, etc interactions. Namely the quantity R dot F is summed over the atoms in the interaction, with the R vectors unwrapped by periodic boundaries so that the cluster of atoms is close together. The total contribution for the cluster interaction is divided evenly among those atoms.

The dihedral_style charmm style calculates pairwise interactions between 1-4 atoms. The virial contribution of these terms is included in the pair virial, not the dihedral virial.

The KSpace contribution is calculated using the method in (Heyes) for the Ewald method and by the methodology described in (Sirk) for PPPM. The choice of KSpace solver is specified by the kspace_style pppm command. Note that for PPPM, the calcluation requires 6 extra FFTs each timestep that per-atom stress is calculated. Thus it can significantly increase the cost of the PPPM calculation if it is needed on a large fraction of the simulation timesteps.

The temp-ID argument can be used to affect the per-atom velocities used in the kinetic energy contribution to the total stress. If the kinetic energy is not included in the stress, than the temperature compute is not used and can be specified as NULL. If the kinetic energy is included and you wish to use atom velocities as-is, then temp-ID can also be specified as NULL. If desired, the specified temperature compute can be one that subtracts off a bias to leave each atom with only a thermal velocity to use in the formula above, e.g. by subtracting a background streaming velocity. See the doc pages for individual compute commands to determine which ones include a bias.

Note that as defined in the formula, per-atom stress is the negative of the per-atom pressure tensor. It is also really a stress*volume formulation, meaning the computed quantity is in units of pressure*volume. It would need to be divided by a per-atom volume to have units of stress (pressure), but an individual atom’s volume is not well defined or easy to compute in a deformed solid or a liquid. See the compute voronoi/atom command for one possible way to estimate a per-atom volume.

Thus, if the diagonal components of the per-atom stress tensor are summed for all atoms in the system and the sum is divided by dV, where d = dimension and V is the volume of the system, the result should be -P, where P is the total pressure of the system.

These lines in an input script for a 3d system should yield that result. I.e. the last 2 columns of thermo output will be the same:

 compute              peratom all stress/atom NULL
 compute              p all reduce sum c_peratom[1] c_peratom[2] c_peratom[3]
 variable     press equal -(c_p[1]+c_p[2]+c_p[3])/(3*vol)
 thermo_style        custom step temp etotal press v_press

Output info:

This compute calculates a per-atom array with 6 columns, which can be accessed by indices 1-6 by any command that uses per-atom values from -a compute as input. See Section_howto 15 for an overview of LAMMPS output +a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The per-atom array values will be in pressure*volume units as discussed above.

Restrictions

none
\ No newline at end of file diff --git a/doc/html/compute_temp_chunk.html b/doc/html/compute_temp_chunk.html index 88aba8404..54f3ec1be 100644 --- a/doc/html/compute_temp_chunk.html +++ b/doc/html/compute_temp_chunk.html @@ -1,397 +1,397 @@ compute temp/chunk command — LAMMPS documentation

compute temp/chunk command

Syntax

compute ID group-ID temp/chunk chunkID value1 value2 ... keyword value ...
  • ID, group-ID are documented in compute command
  • temp/chunk = style name of this compute command
  • chunkID = ID of compute chunk/atom command
  • zero or more values can be listed as value1,value2,etc
  • value = temp or kecom or internal
temp = temperature of each chunk
 kecom = kinetic energy of each chunk based on velocity of center of mass
 internal = internal kinetic energy of each chunk
  • zero or more keyword/value pairs may be appended
  • keyword = com or bias or adof or cdof
 com value = yes or no
   yes = subtract center-of-mass velocity from each chunk before calculating temperature
   no = do not subtract center-of-mass velocity
 bias value = bias-ID
   bias-ID = ID of a temperature compute that removes a velocity bias
 adof value = dof_per_atom
   dof_per_atom = define this many degrees-of-freedom per atom
 cdof value = dof_per_chunk
   dof_per_chunk = define this many degrees-of-freedom per chunk

Examples

compute 1 fluid temp/chunk molchunk
 compute 1 fluid temp/chunk molchunk temp internal
 compute 1 fluid temp/chunk molchunk bias tpartial adof 2.0

Description

Define a computation that calculates the temperature of a group of atoms that are also in chunks, after optionally subtracting out the center-of-mass velocity of each chunk. By specifying optional values, it can also calulate the per-chunk temperature or energies of the multiple chunks of atoms.

In LAMMPS, chunks are collections of atoms defined by a 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 compute chunk/atom doc page and “Section_howto 23 for details of how chunks can be +molecule or atoms in a spatial bin. See the compute chunk/atom doc page and Section 6.23 for details of how chunks can be defined and examples of how they can be used to measure properties of a system.

The temperature is calculated by the formula KE = DOF/2 k T, where KE = total kinetic energy of all atoms assigned to chunks (sum of 1/2 m v^2), DOF = the total number of degrees of freedom for those atoms, k = Boltzmann constant, and T = temperature.

The DOF is calculated as N*adof + Nchunk*cdof, where N = number of atoms contributing to the KE, adof = degrees of freedom per atom, and cdof = degrees of freedom per chunk. By default adof = 2 or 3 = dimensionality of system, as set via the dimension command, and cdof = 0.0. This gives the usual formula for temperature.

A kinetic energy tensor, stored as a 6-element vector, is also calculated by this compute for use in the computation of a pressure tensor. The formula for the components of the tensor is the same as the above formula, except that v^2 is replaced by vx*vy for the xy component, etc. The 6 components of the vector are ordered xx, yy, zz, xy, xz, yz.

Note that the number of atoms contributing to the temperature is calculated each time the temperature is evaluated since it is assumed the atoms may be dynamically assigned to chunks. Thus there is no need to use the dynamic option of the compute_modify command for this compute style.

If any optional values are specified, then per-chunk quantities are also calculated and stored in a global array, as described below.

The temp value calculates the temperature for each chunk by the formula KE = DOF/2 k T, where KE = total kinetic energy of the chunk of atoms (sum of 1/2 m v^2), DOF = the total number of degrees of freedom for all atoms in the chunk, k = Boltzmann constant, and T = temperature.

The DOF in this case is calculated as N*adof + cdof, where N = number of atoms in the chunk, adof = degrees of freedom per atom, and cdof = degrees of freedom per chunk. By default adof = 2 or 3 = dimensionality of system, as set via the dimension command, and cdof = 0.0. This gives the usual formula for temperature.

The kecom value calculates the kinetic energy of each chunk as if all its atoms were moving with the velocity of the center-of-mass of the chunk.

The internal value calculates the internal kinetic energy of each chunk. The interal KE is summed over the atoms in the chunk using an internal “thermal” velocity for each atom, which is its velocity minus the center-of-mass velocity of the chunk.

Note that currently the global and per-chunk temperatures calculated by this compute only include translational degrees of freedom for each atom. No rotational degrees of freedom are included for finite-size particles. Also no degrees of freedom are subtracted for any velocity bias or constraints that are applied, such as compute temp/partial, or fix shake or fix rigid. This is because those degrees of freedom (e.g. a constrained bond) could apply to sets of atoms that are both included and excluded from a specific chunk, and hence the concept is somewhat ill-defined. In some cases, you can use the adof and cdof keywords to adjust the calculated degress of freedom appropriately, as explained below.

Note that the per-chunk temperature calulated by this compute and the fix ave/chunk temp command can be different. This compute calculates the temperature for each chunk for a single snapshot. Fix ave/chunk can do that but can also time average those values over many snapshots, or it can compute a temperature as if the atoms in the chunk on different timesteps were collected together as one set of atoms to calculate their temperature. This compute allows the center-of-mass velocity of each chunk to be subtracted before calculating the temperature; fix ave/chunk does not.

Note

Only atoms in the specified group contribute to the calculations performed by this compute. The compute chunk/atom command defines its own group; atoms will have a chunk ID = 0 if they are not in that group, signifying they are not assigned to a chunk, and will thus also not contribute to this calculation. You can specify the “all” group for this command if you simply want to include atoms with non-zero chunk IDs.

The simplest way to output the per-chunk results of the compute temp/chunk calculation to a file is to use the fix ave/time command, for example:

 compute cc1 all chunk/atom molecule
 compute myChunk all temp/chunk cc1 temp
 fix 1 all ave/time 100 1 100 c_myChunk file tmp.out mode vector

The keyword/value option pairs are used in the following ways.

The com keyword can be used with a value of yes to subtract the velocity of the center-of-mass for each chunk from the velocity of the atoms in that chunk, before calculating either the global or per-chunk temperature. This can be useful if the atoms are streaming or otherwise moving collectively, and you wish to calculate only the thermal temperature.

For the bias keyword, bias-ID refers to the ID of a temperature compute that removes a “bias” velocity from each atom. This also allows calculation of the global or per-chunk temperature using only the thermal temperature of atoms in each chunk after the translational kinetic energy components have been altered in a prescribed way, e.g. to remove a velocity profile. It also applies to the calculation of the other per-chunk values, such as kecom or internal, which involve the center-of-mass velocity of each chunk, which is calculated after the velocity bias is removed from each atom. Note that the temperature compute will apply its bias globally to the entire system, not on a per-chunk basis.

The adof and cdof keywords define the values used in the degree of freedom (DOF) formulas used for the global or per-chunk temperature, as described above. They can be used to calculate a more appropriate temperature for some kinds of chunks. Here are 3 examples:

If spatially binned chunks contain some number of water molecules and fix shake is used to make each molecule rigid, then you could calculate a temperature with 6 degrees of freedom (DOF) (3 translational, 3 rotational) per molecule by setting adof to 2.0.

If compute temp/partial is used with the bias keyword to only allow the x component of velocity to contribute to the temperature, then adof = 1.0 would be appropriate.

If each chunk consists of a large molecule, with some number of its bonds constrained by fix shake or the entire molecule by fix rigid/small, adof = 0.0 and cdof could be set to the remaining degrees of freedom for the entire molecule (entire chunk in this case), e.g. 6 for 3d, or 3 for 2d, for a rigid molecule.

Output info:

This compute calculates a global scalar (the temperature) and a global vector of length 6 (KE tensor), which can be accessed by indices 1-6. These values can be used by any command that uses global scalar or vector values from a compute as input. See this section for an overview of LAMMPS output options.

This compute also optionally calculates a global array, if one or more of the optional values are specified. The number of rows in the array = the number of chunks Nchunk as calculated by the specified compute chunk/atom command. The number of columns is the number of specifed values (1 or more). These values can be accessed by any command that uses global array values from a -compute as input. Again, see Section_howto 15 for an overview of LAMMPS output +compute as input. Again, see Section 6.15 for an overview of LAMMPS output options.

The scalar value calculated by this compute is “intensive”. The vector values are “extensive”. The array values are “intensive”.

The scalar value will be in temperature units. The vector values will be in energy units. The array values will be in temperature units for the temp value, and in energy units for the kecom and internal values.

Restrictions

The com and bias keywords cannot be used together.

Default

The option defaults are com no, no bias, adof = dimensionality of the system (2 or 3), and cdof = 0.0.

\ No newline at end of file diff --git a/doc/html/compute_temp_cs.html b/doc/html/compute_temp_cs.html index cfa909d7f..7fcace42c 100644 --- a/doc/html/compute_temp_cs.html +++ b/doc/html/compute_temp_cs.html @@ -1,288 +1,288 @@ compute temp/cs command — LAMMPS documentation

compute temp/cs command

Syntax

compute ID group-ID temp/cs group1 group2
  • ID, group-ID are documented in compute command
  • temp/cs = style name of this compute command
  • group1 = group-ID of either cores or shells
  • group2 = group-ID of either shells or cores

Examples

 compute oxygen_c-s all temp/cs O_core O_shell
 compute core_shells all temp/cs cores shells

Description

Define a computation that calculates the temperature of a system based on the center-of-mass velocity of atom pairs that are bonded to each other. This compute is designed to be used with the adiabatic core/shell model of (Mitchell and Finchham). See Section 6.25 of the manual for an overview of the model as implemented in LAMMPS. Specifically, this compute enables correct temperature calculation and thermostatting of core/shell pairs where it is desirable for the internal degrees of freedom of the core/shell pairs to not be influenced by a thermostat. A compute of this style can be used by any command that computes a temperature via fix_modify e.g. fix temp/rescale, fix npt, etc.

Note that this compute does not require all ions to be polarized, hence defined as core/shell pairs. One can mix core/shell pairs and ions without a satellite particle if desired. The compute will consider the non-polarized ions according to the physical system.

For this compute, core and shell particles are specified by two respective group IDs, which can be defined using the group command. The number of atoms in the two groups must be the same and there should be one bond defined between a pair of atoms in the two groups. Non-polarized ions which might also be included in the treated system should not be included into either of these groups, they are taken into account by the group-ID (2nd argument) of the compute.

The temperature is calculated by the formula KE = dim/2 N k T, where KE = total kinetic energy of the group of atoms (sum of 1/2 m v^2), dim = 2 or 3 = dimensionality of the simulation, N = number of atoms in the group, k = Boltzmann constant, and T = temperature. Note that the velocity of each core or shell atom used in the KE calculation is the velocity of the center-of-mass (COM) of the core/shell pair the atom is part of.

A kinetic energy tensor, stored as a 6-element vector, is also calculated by this compute for use in the computation of a pressure tensor. The formula for the components of the tensor is the same as the above formula, except that v^2 is replaced by vx*vy for the xy component, etc. The 6 components of the vector are ordered xx, yy, zz, xy, xz, yz. In contrast to the temperature, the velocity of each core or shell atom is taken individually.

The change this fix makes to core/shell atom velocities is essentially computing the temperature after a “bias” has been removed from the velocity of the atoms. This “bias” is the velocity of the atom relative to the COM velocity of the core/shell pair. If this compute is used with a fix command that performs thermostatting then this bias will be subtracted from each atom, thermostatting of the remaining COM velocity will be performed, and the bias will be added back in. This means the thermostating will effectively be performed on the core/shell pairs, instead of on the individual core and shell atoms. Thermostatting fixes that work in this way include fix nvt, fix temp/rescale, fix temp/berendsen, and fix langevin.

The internal energy of core/shell pairs can be calculated by the compute temp/chunk command, if chunks are -defined as core/shell pairs. See Section_howto 25 for more discussion on how to do this.

+defined as core/shell pairs. See Section 6.25 for more discussion on how to do this.

Output info:

This compute calculates a global scalar (the temperature) and a global vector of length 6 (KE tensor), which can be accessed by indices 1-6. These values can be used by any command that uses global scalar or vector values from a compute as input.

The scalar value calculated by this compute is “intensive”. The vector values are “extensive”.

The scalar value will be in temperature units. The vector values will be in energy units.

Restrictions

The number of core/shell pairs contributing to the temperature is assumed to be constant for the duration of the run. No fixes should be used which generate new molecules or atoms during a simulation.

\ No newline at end of file diff --git a/doc/html/compute_ti.html b/doc/html/compute_ti.html index 8d6198637..c55e4a664 100644 --- a/doc/html/compute_ti.html +++ b/doc/html/compute_ti.html @@ -1,307 +1,307 @@ compute ti command — LAMMPS documentation

compute ti command

Syntax

compute ID group ti keyword args ...
  • ID, group-ID are documented in compute command
  • ti = style name of this compute command
  • one or more attribute/arg pairs may be appended
  • keyword = pair style (lj/cut, gauss, born, etc) or tail or kspace
 pair style args = atype v_name1 v_name2
   atype = atom type (see asterisk form below)
   v_name1 = variable with name1 that is energy scale factor and function of lambda
   v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda
 tail args = atype v_name1 v_name2
   atype = atom type (see asterisk form below)
   v_name1 = variable with name1 that is energy tail correction scale factor and function of lambda
   v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda
 kspace args = atype v_name1 v_name2
   atype = atom type (see asterisk form below)
   v_name1 = variable with name1 that is K-Space scale factor and function of lambda
   v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda

Examples

 compute 1 all ti lj/cut 1 v_lj v_dlj coul/long 2 v_c v_dc kspace 1 v_ks v_dks
 compute 1 all ti lj/cut 1*3 v_lj v_dlj coul/long * v_c v_dc kspace * v_ks v_dks

Description

Define a computation that calculates the derivative of the interaction potential with respect to lambda, the coupling parameter used in a thermodynamic integration. This derivative can be used to infer a free energy difference resulting from an alchemical simulation, as described in Eike.

Typically this compute will be used in conjunction with the fix adapt command which can perform alchemical transformations by adusting the strength of an interaction potential as a simulation runs, as defined by one or more pair_style or kspace_style commands. This scaling is done via a prefactor on the energy, forces, virial calculated by the pair or K-Space style. The prefactor is often a function of a lambda parameter which may be adjusted from 0 to 1 (or vice versa) over the course of a run. The time-dependent adjustment is what the fix adapt command does.

Assume that the unscaled energy of a pair_style or kspace_style is given by U. Then the scaled energy is

Us = f(lambda) U

where f() is some function of lambda. What this compute calculates is

dUs / d(lambda) = U df(lambda)/dlambda = Us / f(lambda) df(lambda)/dlambda

which is the derivative of the system’s scaled potential energy Us with respect to lambda.

To perform this calculation, you provide one or more atom types as atype. Atype can be specified in one of two ways. An explicit numeric values can be used, as in the 1st example above. Or a wildcard asterisk can be used in place of or in conjunction with the atype argument to select multiple 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).

You also specify two functions, as equal-style variables. The first is specified as v_name1, where name1 is the name of the variable, and is f(lambda) in the notation above. The second is specified as v_name2, where name2 is the name of the variable, and is df(lambda) / dlambda in the notation above. I.e. it is the analytic derivative of f() with respect to lambda. Note that the name1 variable is also typically given as an argument to the fix adapt command.

An alchemical simulation may use several pair potentials together, invoked via the pair_style hybrid or hybrid/overlay command. The total dUs/dlambda for the overall system is calculated as the sum of each contributing term as listed by the keywords in the compute ti command. Individual pair potentials can be listed, which will be sub-styles in the hybrid case. You can also include a K-space term via the kspace keyword. You can also include a pairwise long-range tail correction to the energy via the tail keyword.

For each term you can specify a different (or the same) scale factor by the two variables that you list. Again, these will typically correspond toe the scale factors applied to these various potentials and the K-Space contribution via the fix adapt command.

More details about the exact functional forms for the computation of du/dl can be found in the paper by Eike.

Output info:

This compute calculates a global scalar, namely dUs/dlambda. This value can be used by any command that uses a global scalar value from -a compute as input. See Section_howto 15 for an overview of LAMMPS output +a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The scalar value calculated by this compute is “extensive”.

The scalar value will be in energy units.

Restrictions

This compute is part of the MISC package. It is only enabled if LAMMPS was built with that package. See the Making LAMMPS section for more info.

\ No newline at end of file diff --git a/doc/html/compute_torque_chunk.html b/doc/html/compute_torque_chunk.html index 650ce622a..2c086faf0 100644 --- a/doc/html/compute_torque_chunk.html +++ b/doc/html/compute_torque_chunk.html @@ -1,269 +1,269 @@ compute torque/chunk command — LAMMPS documentation

compute torque/chunk command

Syntax

compute ID group-ID torque/chunk chunkID
  • ID, group-ID are documented in compute command
  • torque/chunk = style name of this compute command
  • chunkID = ID of compute chunk/atom command

Examples

compute 1 fluid torque/chunk molchunk

Description

Define a computation that calculates the torque on multiple chunks of atoms.

In LAMMPS, chunks are collections of atoms defined by a 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 compute chunk/atom doc page and “Section_howto 23 for details of how chunks can be +molecule or atoms in a spatial bin. See the compute chunk/atom doc page and Section 6.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 torque vector for eqch chunk, due to the forces on 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 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 torque in “unwrapped” form, by using the image flags associated with each atom. See the dump custom command for a discussion of “unwrapped” coordinates. See the Atoms section of the 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 set image command.

The simplest way to output the results of the compute torque/chunk calculation to a file is to use the fix ave/time command, for example:

 compute cc1 all chunk/atom molecule
 compute myChunk all torque/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 compute chunk/atom command. The number of columns = 3 for the 3 xyz components of the torque for each chunk. These values can be accessed by any command that uses global array values from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The array values are “intensive”. The array values will be in force-distance units.

Restrictions

none
\ No newline at end of file diff --git a/doc/html/compute_vcm_chunk.html b/doc/html/compute_vcm_chunk.html index c8574fa37..da7a8f04a 100644 --- a/doc/html/compute_vcm_chunk.html +++ b/doc/html/compute_vcm_chunk.html @@ -1,256 +1,256 @@ compute vcm/chunk command — LAMMPS documentation

compute vcm/chunk command

Syntax

compute ID group-ID vcm/chunk chunkID
  • ID, group-ID are documented in compute command
  • vcm/chunk = style name of this compute command
  • chunkID = ID of compute chunk/atom command

Examples

compute 1 fluid vcm/chunk molchunk

Description

Define a computation that calculates the center-of-mass velocity for multiple chunks of atoms.

In LAMMPS, chunks are collections of atoms defined by a 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 compute chunk/atom doc page and “Section_howto 23 for details of how chunks can be +molecule or atoms in a spatial bin. See the compute chunk/atom doc page and Section 6.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 components of the center-of-mass velocity for each chunk. This is done by summing mass*velocity for each atom in the chunk and dividing the sum by the total mass of the chunk.

Note that only atoms in the specified group contribute to the calculation. The compute chunk/atom command defines its own group; atoms will have a chunk ID = 0 if they are not in that group, signifying they are not assigned to a chunk, and will thus also not contribute to this calculation. You can specify the “all” group for this command if you simply want to include atoms with non-zero chunk IDs.

The simplest way to output the results of the compute vcm/chunk calculation to a file is to use the fix ave/time command, for example:

 compute cc1 all chunk/atom molecule
 compute myChunk all vcm/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 compute chunk/atom command. The number of columns = 3 for the x,y,z center-of-mass velocity coordinates of each chunk. These values can be accessed by any command that uses global array -values from a compute as input. See Section_howto 15 for an overview of LAMMPS output +values from a compute as input. See Section 6.15 for an overview of LAMMPS output options.

The array values are “intensive”. The array values will be in velocity units.

Restrictions

none

Related commands: none

Default: none

\ No newline at end of file diff --git a/doc/html/compute_voronoi_atom.html b/doc/html/compute_voronoi_atom.html index ed4cd612a..a9c8622eb 100644 --- a/doc/html/compute_voronoi_atom.html +++ b/doc/html/compute_voronoi_atom.html @@ -1,395 +1,395 @@ compute voronoi/atom command — LAMMPS documentation

compute voronoi/atom command

Syntax

compute ID group-ID voronoi/atom keyword arg ...
  • ID, group-ID are documented in compute command
  • voronoi/atom = style name of this compute command
  • zero or more keyword/value pairs may be appended
  • keyword = only_group or surface or radius or edge_histo or edge_threshold or face_threshold or neighbors or peratom
 only_group = no arg
 occupation = no arg
 surface arg = sgroup-ID
   sgroup-ID = compute the dividing surface between group-ID and sgroup-ID
     this keyword adds a third column to the compute output
 radius arg = v_r
   v_r = radius atom style variable for a poly-disperse Voronoi tessellation
 edge_histo arg = maxedge
   maxedge = maximum number of Voronoi cell edges to be accounted in the histogram
 edge_threshold arg = minlength
   minlength = minimum length for an edge to be counted
 face_threshold arg = minarea
   minarea = minimum area for a face to be counted
 neighbors value = yes or no = store list of all neighbors or no
 peratom value = yes or no = per-atom quantities accessible or no

Examples

 compute 1 all voronoi/atom
 compute 2 precipitate voronoi/atom surface matrix
 compute 3b precipitate voronoi/atom radius v_r
 compute 4 solute voronoi/atom only_group
 compute 5 defects voronoi/atom occupation
 compute 6 all voronoi/atom neighbors yes

Description

Define a computation that calculates the Voronoi tessellation of the atoms in the simulation box. The tessellation is calculated using all atoms in the simulation, but non-zero values are only stored for atoms in the group.

By default two per-atom quantities are calculated by this compute. The first is the volume of the Voronoi cell around each atom. Any point in an atom’s Voronoi cell is closer to that atom than any other. The second is the number of faces of the Voronoi cell. This is equal to the number of nearest neighbors of the central atom, plus any exterior faces (see note below). If the peratom keyword is set to “no”, the per-atom quantities are still calculated, but they are not accessible.

If the only_group keyword is specified the tessellation is performed only with respect to the atoms contained in the compute group. This is equivalent to deleting all atoms not contained in the group prior to evaluating the tessellation.

If the surface keyword is specified a third quantity per atom is computed: the Voronoi cell surface of the given atom. surface takes a group ID as an argument. If a group other than all is specified, only the Voronoi cell facets facing a neighbor atom from the specified group are counted towards the surface area.

In the example above, a precipitate embedded in a matrix, only atoms at the surface of the precipitate will have non-zero surface area, and only the outward facing facets of the Voronoi cells are counted (the hull of the precipitate). The total surface area of the precipitate can be obtained by running a “reduce sum” compute on c_2[3]

If the radius keyword is specified with an atom style variable as the argument, a poly-disperse Voronoi tessellation is performed. Examples for radius variables are

 variable r1 atom (type==1)*0.1+(type==2)*0.4
 compute radius all property/atom radius
 variable r2 atom c_radius

Here v_r1 specifies a per-type radius of 0.1 units for type 1 atoms and 0.4 units for type 2 atoms, and v_r2 accesses the radius property present in atom_style sphere for granular models.

The edge_histo keyword activates the compilation of a histogram of number of edges on the faces of the Voronoi cells in the compute group. The argument maxedge of the this keyword is the largest number of edges on a single Voronoi cell face expected to occur in the sample. This keyword adds the generation of a global vector with maxedge+1 entries. The last entry in the vector contains the number of faces with with more than maxedge edges. Since the polygon with the smallest amount of edges is a triangle, entries 1 and 2 of the vector will always be zero.

The edge_threshold and face_threshold keywords allow the suppression of edges below a given minimum length and faces below a given minimum area. Ultra short edges and ultra small faces can occur as artifacts of the Voronoi tessellation. These keywords will affect the neighbor count and edge histogram outputs.

If the occupation keyword is specified the tessellation is only performed for the first invocation of the compute and then stored. For all following invocations of the compute the number of atoms in each Voronoi cell in the stored tessellation is counted. In this mode the compute returns a per-atom array with 2 columns. The first column is the number of atoms currently in the Voronoi volume defined by this atom at the time of the first invocation of the compute (note that the atom may have moved significantly). The second column contains the total number of atoms sharing the Voronoi cell of the stored tessellation at the location of the current atom. Numbers in column one can be any positive integer including zero, while column two values will always be greater than zero. Column one data can be used to locate vacancies (the coordinates are given by the atom coordinates at the time step when the compute was first invoked), while column two data can be used to identify interstitial atoms.

If the neighbors value is set to yes, then this compute creates a local array with 3 columns. There is one row for each face of each Voronoi cell. The 3 columns are the atom ID of the atom that owns the cell, the atom ID of the atom in the neighboring cell (or zero if the face is external), and the area of the face. The array can be accessed by any command that uses local values from a compute as input. See this section for an overview of LAMMPS output options. More specifically, the array can be accessed by a dump local command to write a file containing all the Voronoi neighbors in a system:

 compute 6 all voronoi/atom neighbors yes
 dump d2 all local 1 dump.neighbors index c_6[1] c_6[2] c_6[3]

If the face_threshold keyword is used, then only faces with areas greater than the threshold are stored.

The Voronoi calculation is performed by the freely available Voro++ package, written by Chris Rycroft at UC Berkeley and LBL, which must be installed on your system when building LAMMPS for use with this compute. See instructions on obtaining and installing the Voro++ software in the src/VORONOI/README file.

Note

The calculation of Voronoi volumes is performed by each processor for the atoms it owns, and includes the effect of ghost atoms stored by the processor. This assumes that the Voronoi cells of owned atoms are not affected by atoms beyond the ghost atom cut-off distance. This is usually a good assumption for liquid and solid systems, but may lead to underestimation of Voronoi volumes in low density systems. By default, the set of ghost atoms stored by each processor is determined by the cutoff used for pair_style interactions. The cutoff can be set explicitly via the comm_modify cutoff command. The Voronoi cells for atoms adjacent to empty regions will extend into those regions up to the communication cutoff in x, y, or z. In that situation, an exterior face is created at the cutoff distance normal to the x, y, or z direction. For triclinic systems, the exterior face is parallel to the corresponding reciprocal lattice vector.

Note

The Voro++ package performs its calculation in 3d. This will still work for a 2d LAMMPS simulation, provided all the atoms have the same z coordinate. The Voronoi cell of each atom will be a columnar polyhedron with constant cross-sectional area along the z direction and two exterior faces at the top and bottom of the simulation box. If the atoms do not all have the same z coordinate, then the columnar cells will be accordingly distorted. The cross-sectional area of each Voronoi cell can be obtained by dividing its volume by the z extent of the simulation box. Note that you define the z extent of the simulation box for 2d simulations when using the create_box or read_data commands.

Output info:

By default, this compute calculates a per-atom array with 2 columns. In regular dynamic tessellation mode the first column is the Voronoi volume, the second is the neighbor count, as described above (read above for the output data in case the occupation keyword is specified). These values 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 +per-atom values from a compute as input. See Section 6.15 for an overview of LAMMPS output options. If the peratom keyword is set to “no”, the per-atom array is still created, but it is not accessible.

If the edge_histo keyword is used, then this compute generates a global vector of length maxedge+1, containing a histogram of the number of edges per face.

If the neighbors value is set to yes, then this compute calculates a local array with 3 columns. There is one row for each face of each Voronoi cell.

Note

Some LAMMPS commands such as the compute reduce command can accept either a per-atom or local quantity. If this compute produces both quantities, the command may access the per-atom quantity, even if you want to access the local quantity. This effect can be eliminated by using the peratom keyword to turn off the production of the per-atom quantities. For the default value yes both quantities are produced. For the value no, only the local array is produced.

The Voronoi cell volume will be in distance units cubed. The Voronoi face area will be in distance units squared.

Restrictions

This compute is part of the VORONOI package. It is only enabled if LAMMPS was built with that package. See the Making LAMMPS section for more info.

\ No newline at end of file diff --git a/doc/html/fix_ave_chunk.html b/doc/html/fix_ave_chunk.html index a6293fb62..53e07808c 100644 --- a/doc/html/fix_ave_chunk.html +++ b/doc/html/fix_ave_chunk.html @@ -1,608 +1,608 @@ fix ave/chunk command — LAMMPS documentation

fix ave/chunk command

Syntax

fix ID group-ID ave/chunk Nevery Nrepeat Nfreq chunkID value1 value2 ... keyword args ...
  • ID, group-ID are documented in fix command
  • ave/chunk = style name of this fix command
  • Nevery = use input values every this many timesteps
  • Nrepeat = # of times to use input values for calculating averages
  • Nfreq = calculate averages every this many timesteps
  • chunkID = ID of compute chunk/atom command
  • one or more input values can be listed
  • value = vx, vy, vz, fx, fy, fz, density/mass, density/number, temp, c_ID, c_ID[I], f_ID, f_ID[I], v_name
 vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component)
 density/number, density/mass = number or mass density
 temp = temperature
 c_ID = per-atom vector calculated by a compute with ID
 c_ID[I] = Ith column of per-atom array calculated by a compute with ID, I can include wildcard (see below)
 f_ID = per-atom vector calculated by a fix with ID
 f_ID[I] = Ith column of per-atom array calculated by a fix with ID, I can include wildcard (see below)
 v_name = per-atom vector calculated by an atom-style variable with name
  • zero or more keyword/arg pairs may be appended
  • keyword = norm or ave or bias or adof or cdof or file or overwrite or title1 or title2 or title3
 norm arg = all or sample or none = how output on Nfreq steps is normalized
   all = output is sum of atoms across all Nrepeat samples, divided by atom count
   sample = output is sum of Nrepeat sample averages, divided by Nrepeat
   none = output is sum of Nrepeat sample sums, divided by Nrepeat
 ave args = one or running or window M
   one = output new average value every Nfreq steps
   running = output cumulative average of all previous Nfreq steps
   window M = output average of M most recent Nfreq steps
 bias arg = bias-ID
   bias-ID = ID of a temperature compute that removes a velocity bias for temperature calculation
 adof value = dof_per_atom
   dof_per_atom = define this many degrees-of-freedom per atom for temperature calculation
 cdof value = dof_per_chunk
   dof_per_chunk = define this many degrees-of-freedom per chunk for temperature calculation
 file arg = filename
   filename = file to write results to
 overwrite arg = none = overwrite output file with only latest output
 format arg = string
   string = C-style format string
 title1 arg = string
   string = text to print as 1st line of output file
 title2 arg = string
   string = text to print as 2nd line of output file
 title3 arg = string
   string = text to print as 3rd line of output file

Examples

 fix 1 all ave/chunk 10000 1 10000 binchunk c_myCentro title1 "My output values"
 fix 1 flow ave/chunk 100 10 1000 molchunk vx vz norm sample file vel.profile
 fix 1 flow ave/chunk 100 5 1000 binchunk density/mass ave running
 fix 1 flow ave/chunk 100 5 1000 binchunk density/mass ave running

NOTE:

If you are trying to replace a deprectated fix ave/spatial command with the newer, more flexible fix ave/chunk and compute chunk/atom commands, you simply need to split the fix ave/spatial arguments across the two new commands. For example, this command:

fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile

could be replaced by:

compute cc1 flow chunk/atom bin/1d y 0.0 1.0
 fix 1 flow ave/chunk 100 10 1000 cc1 vx vz norm sample file vel.profile

Description

Use one or more per-atom vectors as inputs every few timesteps, sum the values over the atoms in each chunk at each timestep, then average the per-chunk values over longer timescales. The resulting chunk averages can be used by other output commands such as thermo_style custom, and can also be written to a file.

In LAMMPS, chunks are collections of atoms defined by a 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 compute chunk/atom doc page and “Section_howto 23 for details of how chunks can be +molecule or atoms in a spatial bin. See the compute chunk/atom doc page and Section 6.23 for details of how chunks can be defined and examples of how they can be used to measure properties of a system.

Note that only atoms in the specified group contribute to the summing and averaging calculations. The compute chunk/atom command defines its own group as well as an optional region. Atoms will have a chunk ID = 0, meaning they belong to no chunk, if they are not in that group or region. Thus you can specify the “all” group for this command if you simply want to use the chunk definitions provided by chunkID.

Each specified per-atom value can be an atom attribute (position, velocity, force component), a mass or number density, or the result of a compute or fix or the evaluation of an atom-style variable. In the latter cases, the compute, fix, or variable must produce a per-atom quantity, not a global quantity. Note that the compute property/atom command provides access to any attribute defined and stored by atoms. If you wish to time-average global quantities from a compute, fix, or variable, then see the fix ave/time command.

The per-atom values of each input vector are summed and averaged independently of the per-atom values in other input vectors.

Computes that produce per-atom quantities are those which have the word atom in their style name. See the doc pages for individual fixes to determine which ones produce per-atom quantities. Variables of style atom are the only ones that can be used with this fix since all other styles of variable produce global quantities.

Note that for values from a compute or fix, the bracketed index I can be specified using a wildcard asterisk with the index to effectively specify multiple values. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the size of the vector (for mode = scalar) or the number of columns in the array (for mode = vector), then an asterisk with no numeric values means all indices from 1 to N. A leading asterisk means all indices from 1 to n (inclusive). A trailing asterisk means all indices from n to N (inclusive). A middle asterisk means all indices from m to n (inclusive).

Using a wildcard is the same as if the individual columns of the array had been listed one by one. E.g. these 2 fix ave/chunk commands are equivalent, since the compute property/atom command creates, in this case, a per-atom array with 3 columns:

 compute myAng all property/atom angmomx angmomy angmomz
 fix 1 all ave/chunk 100 1 100 cc1 c_myAng[*] file tmp.angmom
 fix 2 all ave/chunk 100 1 100 cc1 c_myAng[1] c_myAng[2] c_myAng[3] file tmp.angmom

Note

This fix works by creating an array of size Nchunk by Nvalues on each processor. Nchunk is the number of chunks which is defined by the compute chunk/atom command. Nvalues is the number of input values specified. Each processor loops over its atoms, tallying its values to the appropriate chunk. Then the entire array is summed across all processors. This means that using a large number of chunks will incur an overhead in memory and computational cost (summing across processors), so be careful to define a reasonable number of chunks.

The Nevery, Nrepeat, and Nfreq arguments specify on what timesteps the input values will be accessed and contribute to the average. The final averaged quantities are generated on timesteps that are a multiples of Nfreq. The average is over Nrepeat quantities, computed in the preceding portion of the simulation every Nevery timesteps. Nfreq must be a multiple of Nevery and Nevery must be non-zero even if Nrepeat is 1. Also, the timesteps contributing to the average value cannot overlap, i.e. Nrepeat*Nevery can not exceed Nfreq.

For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on timesteps 90,92,94,96,98,100 will be used to compute the final average on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on timestep 200, etc. If Nrepeat=1 and Nfreq = 100, then no time averaging is done; values are simply generated on timesteps 100,200,etc.

Each input value can also be averaged over the atoms in each chunk. The way the averaging is done across the Nrepeat timesteps to produce output on the Nfreq timesteps, and across multiple Nfreq outputs, is determined by the norm and ave keyword settings, as discussed below.

Note

To perform per-chunk averaging within a Nfreq time window, the number of chunks Nchunk defined by the compute chunk/atom command must remain constant. If the ave keyword is set to running or window then Nchunk must remain constant for the duration of the simulation. This fix forces the chunk/atom compute specified by chunkID to hold Nchunk constant for the appropriate time windows, by not allowing it to re-calcualte Nchunk, which can also affect how it assigns chunk IDs to atoms. More details are given on the compute chunk/atom doc page.

The atom attribute values (vx,vy,vz,fx,fy,fz) are self-explanatory. As noted above, any other atom attributes can be used as input values to this fix by using the compute property/atom command and then specifying an input value from that compute.

The density/number value means the number density is computed for each chunk, i.e. number/volume. The density/mass value means the mass density is computed for each chunk, i.e. total-mass/volume. The output values are in units of 1/volume or density (mass/volume). See the units command doc page for the definition of density for each choice of units, e.g. gram/cm^3. If the chunks defined by the compute chunk/atom command are spatial bins, the volume is the bin volume. Otherwise it is the volume of the entire simulation box.

The temp value means the temperature is computed for each chunk, by the formula KE = DOF/2 k T, where KE = total kinetic energy of the chunk of atoms (sum of 1/2 m v^2), DOF = the total number of degrees of freedom for all atoms in the chunk, k = Boltzmann constant, and T = temperature.

The DOF is calculated as N*adof + cdof, where N = number of atoms in the chunk, adof = degrees of freedom per atom, and cdof = degrees of freedom per chunk. By default adof = 2 or 3 = dimensionality of system, as set via the dimension command, and cdof = 0.0. This gives the usual formula for temperature.

Note that currently this temperature only includes translational degrees of freedom for each atom. No rotational degrees of freedom are included for finite-size particles. Also no degrees of freedom are subtracted for any velocity bias or constraints that are applied, such as compute temp/partial, or fix shake or fix rigid. This is because those degrees of freedom (e.g. a constrained bond) could apply to sets of atoms that are both included and excluded from a specific chunk, and hence the concept is somewhat ill-defined. In some cases, you can use the adof and cdof keywords to adjust the calculated degress of freedom appropriately, as explained below.

Also note that a bias can be subtracted from atom velocities before they are used in the above formula for KE, by using the bias keyword. This allows, for example, a thermal temperature to be computed after removal of a flow velocity profile.

Note that the per-chunk temperature calculated by this fix and the compute temp/chunk command can be different. The compute calculates the temperature for each chunk for a single snapshot. This fix can do that but can also time average those values over many snapshots, or it can compute a temperature as if the atoms in the chunk on different timesteps were collected together as one set of atoms to calculate their temperature. The compute allows the center-of-mass velocity of each chunk to be subtracted before calculating the temperature; this fix does not.

If a value 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 add them to LAMMPS. See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values.

If a value begins with “f_”, a fix ID must follow which has been previously defined in the input script. If no bracketed 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 Nevery, else an error results. Users can also write code for their own fix styles and add them to LAMMPS. See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values.

If a value begins with “v_”, a variable name must follow which has been previously defined in the input script. 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 average within chunks.

Additional optional keywords also affect the operation of this fix and its outputs.

The norm keyword affects how averaging is done for the per-chunk values that are output every Nfreq timesteps.

It the norm setting is all, which is the default, a chunk value is summed over all atoms in all Nrepeat samples, as is the count of atoms in the chunk. The averaged output value for the chunk on the Nfreq timesteps is Total-sum / Total-count. In other words it is an average over atoms across the entire Nfreq timescale.

If the norm setting is sample, the chunk value is summed over atoms for each sample, as is the count, and an “average sample value” is computed for each sample, i.e. Sample-sum / Sample-count. The output value for the chunk on the Nfreq timesteps is the average of the Nrepeat “average sample values”, i.e. the sum of Nrepeat “average sample values” divided by Nrepeat. In other words it is an average of an average.

If the norm setting is none, a similar computation as for the sample seting is done, except the individual “average sample values” are “summed sample values”. A summed sample value is simply the chunk value summed over atoms in the sample, without dividing by the number of atoms in the sample. The output value for the chunk on the Nfreq timesteps is the average of the Nrepeat “summed sample values”, i.e. the sum of Nrepeat “summed sample values” divided by Nrepeat.

The ave keyword determines how the per-chunk values produced every Nfreq steps are averaged with values produced on previous steps that were multiples of Nfreq, before they are accessed by another output command or written to a file.

If the ave setting is one, which is the default, then the chunk values produced on timesteps that are multiples of Nfreq are independent of each other; they are output as-is without further averaging.

If the ave setting is running, then the chunk values produced on timesteps that are multiples of Nfreq are summed and averaged in a cumulative sense before being output. Each output chunk value is thus the average of the chunk value produced on that timestep with all preceding values for the same chunk. This running average begins when the fix is defined; it can only be restarted by deleting the fix via the unfix command, or re-defining the fix by re-specifying it.

If the ave setting is window, then the chunk values produced on timesteps that are multiples of Nfreq are summed and averaged within a moving “window” of time, so that the last M values for the same chunk are used to produce the output. E.g. if M = 3 and Nfreq = 1000, then the output on step 10000 will be the average of the individual chunk values on steps 8000,9000,10000. Outputs on early steps will average over less than M values if they are not available.

The bias keyword specifies the ID of a temperature compute that removes a “bias” velocity from each atom, specified as bias-ID. It is only used when the temp value is calculated, to compute the thermal temperature of each chunk after the translational kinetic energy components have been altered in a prescribed way, e.g. to remove a flow velocity profile. See the doc pages for individual computes that calculate a temperature to see which ones implement a bias.

The adof and cdof keywords define the values used in the degree of freedom (DOF) formula described above for for temperature calculation for each chunk. They are only used when the temp value is calculated. They can be used to calculate a more appropriate temperature for some kinds of chunks. Here are 3 examples:

If spatially binned chunks contain some number of water molecules and fix shake is used to make each molecule rigid, then you could calculate a temperature with 6 degrees of freedom (DOF) (3 translational, 3 rotational) per molecule by setting adof to 2.0.

If compute temp/partial is used with the bias keyword to only allow the x component of velocity to contribute to the temperature, then adof = 1.0 would be appropriate.

If each chunk consists of a large molecule, with some number of its bonds constrained by fix shake or the entire molecule by fix rigid/small, adof = 0.0 and cdof could be set to the remaining degrees of freedom for the entire molecule (entire chunk in this case), e.g. 6 for 3d, or 3 for 2d, for a rigid molecule.

The file keyword allows a filename to be specified. Every Nfreq timesteps, a section of chunk info will be written to a text file in the following format. A line with the timestep and number of chunks is written. Then one line per chunk is written, containing the chunk ID (1-Nchunk), an optional original ID value, optional coordinate values for chunks that represent spatial bins, the number of atoms in the chunk, and one or more calculated values. More explanation of the optional values is given below. The number of values in each line corresponds to the number of values specified in the fix ave/chunk command. The number of atoms and the value(s) are summed or average quantities, as explained above.

The overwrite keyword will continuously overwrite the output file with the latest output, so that it only contains one timestep worth of output. This option can only be used with the ave running setting.

The format keyword sets the numeric format of each value when it is printed to a file via the file keyword. Note that all values are floating point quantities. The default format is %g. You can specify a higher precision if desired, e.g. %20.16g.

The title1 and title2 and title3 keywords allow specification of the strings that will be printed as the first 3 lines of the output file, assuming the file keyword was used. LAMMPS uses default values for each of these, so they do not need to be specified.

By default, these header lines are as follows:

# Chunk-averaged data for fix ID and group name
 # Timestep Number-of-chunks
 # Chunk (OrigID) (Coord1) (Coord2) (Coord3) Ncount value1 value2 ...

In the first line, ID and name are replaced with the fix-ID and group name. The second line describes the two values that are printed at the first of each section of output. In the third line the values are replaced with the appropriate value names, e.g. fx or c_myCompute2.

The words in parenthesis only appear with corresponding columns if the chunk style specified for the compute chunk/atom command supports them. The OrigID column is only used if the compress keyword was set to yes for the compute chunk/atom command. This means that the original chunk IDs (e.g. molecule IDs) will have been compressed to remove chunk IDs with no atoms assigned to them. Thus a compresed chunk ID of 3 may correspond to an original chunk ID or molecule ID of 415. The OrigID column will list 415 for the 3rd chunk.

The CoordN columns only appear if a binning style was used in the compute chunk/atom command. For bin/1d, bin/2d, and bin/3d styles the column values are the center point of the bin in the corresponding dimension. Just Coord1 is used for bin/1d, Coord2 is added for bin/2d, Coord3 is added for bin/3d. For bin/sphere, just Coord1 is used, and it is the radial coordinate. For bin/cylinder, Coord1 and Coord2 are used. Coord1 is the radial coordinate (away from the cylinder axis), and coord2 is the coordinate along the cylinder axis.

Note that if the value of the units keyword used in the compute chunk/atom command is box or lattice, the coordinate values will be in distance units. If the value of the units keyword is reduced, the coordinate values will be in unitless reduced units (0-1). This is not true for the Coord1 value of style bin/sphere or bin/cylinder which both represent radial dimensions. Those values are always in distance units.

Restart, fix_modify, output, run start/stop, minimize info:

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.

This fix computes a global array of values which can be accessed by various output commands. The values can only be accessed on timesteps that are multiples of Nfreq since that is when averaging is performed. The global array has # of rows = the number of chunks Nchunk as calculated by the specified compute chunk/atom command. The # of columns = M+1+Nvalues, where M = 1 to 4, depending on whether the optional columns for OrigID and CoordN are used, as explained above. Following the optional columns, the next column contains the count of atoms in the chunk, and the remaining columns are the Nvalue quantities. When the array is accessed with a row I that exceeds the current number of chunks, than a 0.0 is returned by the fix instead of an error, since the number of chunks can vary as a simulation runs depending on how that value is computed by the compute chunk/atom command.

The array values calculated by this fix are treated as “intensive”, since they are typically already normalized by the count of atoms in each chunk.

No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

Restrictions

none

Default

The option defaults are norm = all, ave = one, bias = none, no file output, and title 1,2,3 = strings as described above.

\ No newline at end of file diff --git a/doc/html/fix_nve_body.html b/doc/html/fix_nve_body.html index 45816df75..6b6c04ad8 100644 --- a/doc/html/fix_nve_body.html +++ b/doc/html/fix_nve_body.html @@ -1,240 +1,240 @@ fix nve/body command — LAMMPS documentation

fix nve/body command

Syntax

fix ID group-ID nve/body
  • ID, group-ID are documented in fix command
  • nve/body = style name of this fix command

Examples

fix 1 all nve/body

Description

Perform constant NVE integration to update position, velocity, orientation, and angular velocity for body particles in the group each timestep. V is volume; E is energy. This creates a system trajectory -consistent with the microcanonical ensemble. See Section_howto 14 of the manual and the body +consistent with the microcanonical ensemble. See Section 6.14 of the manual and the body doc page for more details on using body particles.

This fix differs from the fix nve command, which assumes point particles and only updates their position and velocity.

Restart, fix_modify, output, run start/stop, minimize info:

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix. No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

Restrictions

This fix is part of the BODY package. It is only enabled if LAMMPS was built with that package. See the Making LAMMPS section for more info.

This fix requires that atoms store torque and angular momementum and a quaternion as defined by the atom_style body command.

All particles in the group must be body particles. They cannot be point particles.

\ No newline at end of file diff --git a/doc/html/fix_nve_manifold_rattle.html b/doc/html/fix_nve_manifold_rattle.html index de2190636..149e6de04 100644 --- a/doc/html/fix_nve_manifold_rattle.html +++ b/doc/html/fix_nve_manifold_rattle.html @@ -1,273 +1,273 @@ fix nve/manifold/rattle command — LAMMPS documentation

fix nve/manifold/rattle command

Syntax

fix ID group-ID nve/manifold/rattle tol maxit manifold manifold-args keyword value ...
  • ID, group-ID are documented in fix command
  • nve/manifold/rattle = style name of this fix command
  • tol = tolerance to which Newton iteration must converge
  • maxit = maximum number of iterations to perform
  • manifold = name of the manifold
  • manifold-args = parameters for the manifold
  • one or more keyword/value pairs may be appended
 keyword = every
   every values = N
     N = print info about iteration every N steps. N = 0 means no output

Examples

fix 1 all nve/manifold/rattle 1e-4 10 sphere 5.0
 fix step all nve/manifold/rattle 1e-8 100 ellipsoid 2.5 2.5 5.0 every 25

Description

Perform constant NVE integration to update position and velocity for atoms constrained to a curved surface (manifold) in the group each timestep. The constraint is handled by RATTLE (Andersen) written out for the special case of single-particle constraints as -explained in (Paquay). V is volume; E is energy. This way, +explained in (Paquay). V is volume; E is energy. This way, the dynamics of particles constrained to curved surfaces can be studied. If combined with fix langevin, this generates Brownian motion of particles constrained to a curved surface. For a list of currently supported manifolds and their parameters, see manifolds.

Note that the particles must initially be close to the manifold in question. If not, RATTLE will not be able to iterate until the constraint is satisfied, and an error is generated. For simple manifolds this can be achieved with region and create_atoms commands, but for more complex surfaces it might be more useful to write a script.

The manifold args may be equal-style variables, like so:

 variable R equal "ramp(5.0,3.0)"
 fix shrink_sphere all nve/manifold/rattle 1e-4 10 sphere v_R

In this case, the manifold parameter will change in time according to the variable. This is not a problem for the time integrator as long as the change of the manifold is slow with respect to the dynamics of the particles. Note that if the manifold has to exert work on the particles because of these changes, the total energy might not be conserved.

Restart, fix_modify, output, run start/stop, minimize info:

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix. No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

Restrictions

This fix is part of the USER-MANIFOLD package. It is only enabled if LAMMPS was built with that package. See the Making LAMMPS section for more info.

\ No newline at end of file diff --git a/doc/html/fix_viscosity.html b/doc/html/fix_viscosity.html index 16fa977a8..d3ec7d2bb 100644 --- a/doc/html/fix_viscosity.html +++ b/doc/html/fix_viscosity.html @@ -1,337 +1,337 @@ fix viscosity command — LAMMPS documentation

fix viscosity command

Syntax

fix ID group-ID viscosity N vdim pdim Nbin keyword value ...
  • ID, group-ID are documented in fix command
  • viscosity = style name of this fix command
  • N = perform momentum exchange every N steps
  • vdim = x or y or z = which momentum component to exchange
  • pdim = x or y or z = direction of momentum transfer
  • Nbin = # of layers in pdim direction (must be even number)
  • zero or more keyword/value pairs may be appended
  • keyword = swap or target
 swap value = Nswap = number of swaps to perform every N steps
 vtarget value = V or INF = target velocity of swap partners (velocity units)

Examples

fix 1 all viscosity 100 x z 20
 fix 1 all viscosity 50 x z 20 swap 2 vtarget 1.5

Description

Use the Muller-Plathe algorithm described in this paper to exchange momenta between two particles in different regions of the simulation box every N steps. This induces a shear velocity profile in the system. As described below this enables a viscosity of the fluid to be calculated. This algorithm is sometimes called a reverse non-equilibrium MD (reverse NEMD) approach to computing viscosity. This is because the usual NEMD approach is to impose a shear velocity profile on the system and measure the response via an off-diagonal component of the stress tensor, which is proportional to the momentum flux. In the Muller-Plathe method, the momentum flux is imposed, and the shear velocity profile is the system’s response.

The simulation box is divided into Nbin layers in the pdim direction, where the layer 1 is at the low end of that dimension and the layer Nbin is at the high end. Every N steps, Nswap pairs of atoms are chosen in the following manner. Only atoms in the fix group are considered. Nswap atoms in layer 1 with positive velocity components in the vdim direction closest to the target value V are selected. Similarly, Nswap atoms in the “middle” layer (see below) with negative velocity components in the vdim direction closest to the negative of the target value V are selected. The two sets of Nswap atoms are paired up and their vdim momenta components are swapped within each pair. This resets their velocities, typically in opposite directions. Over time, this induces a shear velocity profile in the system which can be measured using commands such as the following, which writes the profile to the file tmp.profile:

compute layers all chunk/atom bin/1d z lower 0.05 units reduced
 fix f1 all ave/chunk 100 10 1000 layers vx file tmp.profile

Note that by default, Nswap = 1 and vtarget = INF, though this can be changed by the optional swap and vtarget keywords. When vtarget = INF, one or more atoms with the most positive and negative velocity components are selected. Setting these parameters appropriately, in conjunction with the swap rate N, allows the momentum flux rate to be adjusted across a wide range of values, and the momenta to be exchanged in large chunks or more smoothly.

The “middle” layer for momenta swapping is defined as the Nbin/2 + 1 layer. Thus if Nbin = 20, the two swapping layers are 1 and 11. This should lead to a symmetric velocity profile since the two layers are separated by the same distance in both directions in a periodic sense. This is why Nbin is restricted to being an even number.

As described below, the total momentum transferred by these velocity swaps is computed by the fix and can be output. Dividing this quantity by time and the cross-sectional area of the simulation box yields a momentum flux. The ratio of momentum flux to the slope of the shear velocity profile is proportional to the viscosity of the fluid, in appropriate units. See the Muller-Plathe paper for details.

Note

If your system is periodic in the direction of the momentum flux, then the flux is going in 2 directions. This means the effective momentum flux in one direction is reduced by a factor of 2. You will see this in the equations for viscosity in the Muller-Plathe paper. LAMMPS is simply tallying momentum which does not account for whether or not your system is periodic; you must use the value appropriately to yield a viscosity for your system.

Note

After equilibration, if the velocity profile you observe is not linear, then you are likely swapping momentum too frequently and are not in a regime of linear response. In this case you cannot accurately infer a viscosity and should try increasing the Nevery parameter.

An alternative method for calculating a viscosity is to run a NEMD -simulation, as described in Section_howto 13 of the manual. NEMD simulations +simulation, as described in Section 6.13 of the manual. NEMD simulations deform the simmulation box via the fix deform command. Thus they cannot be run on a charged system using a PPPM solver since PPPM does not currently support non-orthogonal boxes. Using fix viscosity keeps the box orthogonal; thus it does not suffer from this limitation.

Restart, fix_modify, output, run start/stop, minimize info:

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.

This fix computes a global scalar which can be accessed by various output commands. The scalar is the cummulative momentum transferred between the bottom and middle of the simulation box (in the pdim direction) is stored as a scalar quantity by this fix. This quantity is zeroed when the fix is defined and accumlates thereafter, once every N steps. The units of the quantity are momentum = mass*velocity. The scalar value calculated by this fix is “intensive”.

No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

Restrictions

This fix is part of the MISC package. It is only enabled if LAMMPS was built with that package. See the Making LAMMPS section for more info.

Swaps conserve both momentum and kinetic energy, even if the masses of the swapped atoms are not equal. Thus you should not need to thermostat the system. If you do use a thermostat, you may want to apply it only to the non-swapped dimensions (other than vdim).

LAMMPS does not check, but you should not use this fix to swap velocities of atoms that are in constrained molecules, e.g. via fix shake or fix rigid. This is because application of the constraints will alter the amount of transferred momentum. You should, however, be able to use flexible molecules. See the Maginn paper for an example of using this algorithm in a computation of alcohol molecule properties.

When running a simulation with large, massive particles or molecules in a background solvent, you may want to only exchange momenta bewteen solvent particles.

Default

The option defaults are swap = 1 and vtarget = INF.

(Muller-Plathe) Muller-Plathe, Phys Rev E, 59, 4894-4898 (1999).

(Maginn) Kelkar, Rafferty, Maginn, Siepmann, Fluid Phase Equilibria, 260, 218-231 (2007).

\ No newline at end of file diff --git a/doc/html/pair_buck_long.html b/doc/html/pair_buck_long.html index 5d8371e46..edb597340 100644 --- a/doc/html/pair_buck_long.html +++ b/doc/html/pair_buck_long.html @@ -1,338 +1,338 @@ pair_style buck/long/coul/long command — LAMMPS documentation

pair_style buck/long/coul/long command

pair_style buck/long/coul/long/omp command

Syntax

 pair_style buck/long/coul/long flag_buck flag_coul cutoff (cutoff2)
  • flag_buck = long or cut
 long = use Kspace long-range summation for the dispersion term 1/r^6
 cut = use a cutoff
  • flag_coul = long or off
 long = use Kspace long-range summation for the Coulombic term 1/r
 off = omit the Coulombic term
  • cutoff = global cutoff for Buckingham (and Coulombic if only 1 cutoff) (distance units)
  • cutoff2 = global cutoff for Coulombic (optional) (distance units)

Examples

 pair_style buck/long/coul/long cut off 2.5
 pair_style buck/long/coul/long cut long 2.5 4.0
 pair_style buck/long/coul/long long long 4.0
 pair_coeff * * 1 1
 pair_coeff 1 1 1 3 4

Description

The buck/long/coul/long style computes a Buckingham potential (exp/6 instead of Lennard-Jones 12/6) and Coulombic potential, given by

_images/pair_buck.jpg _images/pair_coulomb.jpg

Rc is the cutoff. If one cutoff is specified in the pair_style command, it is used for both the Buckingham and Coulombic terms. If two cutoffs are specified, they are used as cutoffs for the Buckingham and Coulombic terms respectively.

The purpose of this pair style is to capture long-range interactions resulting from both attractive 1/r^6 Buckingham and Coulombic 1/r interactions. This is done by use of the flag_buck and flag_coul -settings. The “Ismail paper has more details on when it is +settings. The Ismail paper has more details on when it is appropriate to include long-range 1/r^6 interactions, using this potential.

If flag_buck is set to long, no cutoff is used on the Buckingham 1/r^6 dispersion term. The long-range portion can be calculated by using the kspace_style ewald/disp or pppm/disp commands. The specified Buckingham cutoff then determines which portion of the Buckingham interactions are computed directly by the pair potential versus which part is computed in reciprocal space via the Kspace style. If flag_buck is set to cut, the Buckingham interactions are simply cutoff, as with pair_style buck.

If flag_coul is set to long, no cutoff is used on the Coulombic interactions. The long-range portion can calculated by using any of several kspace_style command options such as pppm or ewald. Note that if flag_buck is also set to long, then the ewald/disp or pppm/disp Kspace style needs to be used to perform the long-range calculations for both the Buckingham and Coulombic interactions. If flag_coul is set to off, Coulombic interactions are not computed.

The following coefficients must be defined for each pair of atoms types via the pair_coeff command as in the examples above, or in the data file or restart files read by the read_data or read_restart commands:

  • A (energy units)
  • rho (distance units)
  • C (energy-distance^6 units)
  • cutoff (distance units)
  • cutoff2 (distance units)

The second coefficient, rho, must be greater than zero.

The latter 2 coefficients are optional. If not specified, the global Buckingham and Coulombic cutoffs specified in the pair_style command are used. If only one cutoff is specified, it is used as the cutoff for both Buckingham and Coulombic interactions for this type pair. If both coefficients are specified, they are used as the Buckingham and Coulombic cutoffs for this type pair. Note that if you are using flag_buck set to long, you cannot specify a Buckingham cutoff for an atom type pair, since only one global Buckingham cutoff is allowed. Similarly, if you are using flag_coul set to long, you cannot specify a Coulombic cutoff for an atom type pair, since only one global Coulombic cutoff is allowed.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix. They have been optimized to run faster, depending on your available hardware, as discussed in Section 5 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 GPU, USER-INTEL, KOKKOS, USER-OMP and OPT packages, respectively. They are only enabled if LAMMPS was built with those packages. See the Making LAMMPS section for more info.

You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.

See Section 5 of the manual for more instructions on how to use the accelerated styles effectively.

Mixing, shift, table, tail correction, restart, rRESPA info:

This pair styles does not support mixing. Thus, coefficients for all I,J pairs must be specified explicitly.

This pair style supports the pair_modify shift option for the energy of the exp() and 1/r^6 portion of the pair interaction, assuming flag_buck is cut.

This pair style does not support the pair_modify shift option for the energy of the Buckingham portion of the pair interaction.

This pair style supports the pair_modify table and table/disp options since they can tabulate the short-range portion of the long-range Coulombic and dispersion interactions.

This pair style write its information to binary restart files, so pair_style and pair_coeff commands do not need to be specified in an input script that reads a restart file.

This pair style supports the use of the inner, middle, and outer keywords of the run_style respa command, meaning the pairwise forces can be partitioned by distance at different levels of the rRESPA hierarchy. See the run_style command for details.

Restrictions

This style is part of the KSPACE package. It is only enabled if LAMMPS was built with that package. See the Making LAMMPS section for more info. Note that the KSPACE package is installed by default.

\ No newline at end of file diff --git a/doc/html/tad.html b/doc/html/tad.html index e4bab3f21..db9656cac 100644 --- a/doc/html/tad.html +++ b/doc/html/tad.html @@ -1,464 +1,464 @@ tad command — LAMMPS documentation

tad command

Syntax

 tad N t_event T_lo T_hi delta tmax compute-ID keyword value ...
  • N = # of timesteps to run (not including dephasing/quenching)
  • t_event = timestep interval between event checks
  • T_lo = temperature at which event times are desired
  • T_hi = temperature at which MD simulation is performed
  • delta = desired confidence level for stopping criterion
  • tmax = reciprocal of lowest expected preexponential factor (time units)
  • compute-ID = ID of the compute used for event detection
  • zero or more keyword/value pairs may be appended
  • keyword = min or neb or min_style or neb_style or neb_log
 min values = etol ftol maxiter maxeval
   etol = stopping tolerance for energy (energy units)
   ftol = stopping tolerance for force (force units)
   maxiter = max iterations of minimize
   maxeval = max number of force/energy evaluations
 neb values = ftol N1 N2 Nevery
   etol = stopping tolerance for energy (energy units)
   ftol = stopping tolerance for force (force units)
   N1 = max # of iterations (timesteps) to run initial NEB
   N2 = max # of iterations (timesteps) to run barrier-climbing NEB
   Nevery = print NEB statistics every this many timesteps
 neb_style value = quickmin or fire
 neb_step value = dtneb
   dtneb = timestep for NEB damped dynamics minimization
 neb_log value = file where NEB statistics are printed

Examples

 tad 2000 50 1800 2300 0.01 0.01 event
 tad 2000 50 1800 2300 0.01 0.01 event &
     min 1e-05 1e-05 100 100 &
     neb 0.0 0.01 200 200 20 &
     min_style cg &
     neb_style fire &
     neb_log log.neb

Description

Run a temperature accelerated dynamics (TAD) simulation. This method requires two or more partitions to perform NEB transition state searches.

TAD is described in this paper by Art Voter. It is a method that uses accelerated dynamics at an elevated temperature to generate results at a specified lower temperature. A good overview of accelerated dynamics methods for such systems is given in this review paper from the same group. In general, these methods assume that the long-time dynamics is dominated by infrequent events i.e. the system is is confined to low energy basins for long periods, punctuated by brief, randomly-occurring transitions to adjacent basins. TAD is suitable for infrequent-event systems, where in addition, the transition kinetics are well-approximated by harmonic transition state theory (hTST). In hTST, the temperature dependence of transition rates follows the Arrhenius relation. As a consequence a set of event times generated in a high-temperature simulation can be mapped to a set of much longer estimated times in the low-temperature system. However, because this mapping involves the energy barrier of the transition event, which is different for each event, the first event at the high temperature may not be the earliest event at the low temperature. TAD handles this by first generating a set of possible events from the current basin. After each event, the simulation is reflected backwards into the current basin. This is repeated until the stopping criterion is satisfied, at which point the event with the earliest low-temperature occurrence time is selected. The stopping criterion is that the confidence measure be greater than 1-delta. The confidence measure is the probability that no earlier low-temperature event will occur at some later time in the high-temperature simulation. hTST provides an lower bound for this probability, based on the user-specified minimum pre-exponential factor (reciprocal of tmax).

In order to estimate the energy barrier for each event, the TAD method invokes the NEB method. Each NEB replica runs on a partition of processors. The current NEB implementation in LAMMPS restricts you to having exactly one processor per replica. For more information, see the documentation for the neb command. In the current LAMMPS implementation of TAD, all the non-NEB TAD operations are performed on the first partition, while the other -partitions remain idle. See Section_howto 5 of the manual for further discussion of +partitions remain idle. See Section 6.5 of the manual for further discussion of multi-replica simulations.

A TAD run has several stages, which are repeated each time an event is performed. The logic for a TAD run is as follows:

 while (time remains):
   while (time < tstop):
     until (event occurs):
       run dynamics for t_event steps
       quench
     run neb calculation using all replicas
     compute tlo from energy barrier
     update earliest event
     update tstop
     reflect back into current basin
   execute earliest event

Before this outer loop begins, the initial potential energy basin is identified by quenching (an energy minimization, see below) the initial state and storing the resulting coordinates for reference.

Inside the inner loop, dynamics is run continuously according to whatever integrator has been specified by the user, stopping every t_event steps to check if a transition event has occurred. This check is performed by quenching the system and comparing the resulting atom coordinates to the coordinates from the previous basin.

A quench is an energy minimization and is performed by whichever algorithm has been defined by the min_style command; its default is the CG minimizer. The tolerances and limits for each quench can be set by the min keyword. Note that typically, you do not need to perform a highly-converged minimization to detect a transition event.

The event check is performed by a compute with the specified compute-ID. Currently there is only one compute that works with the TAD commmand, which is the compute event/displace command. Other event-checking computes may be added. Compute event/displace checks whether any atom in the compute group has moved further than a specified threshold distance. If so, an “event” has occurred.

The NEB calculation is similar to that invoked by the neb command, except that the final state is generated internally, instead of being read in from a file. The style of minimization performed by NEB is determined by the neb_style keyword and must be a damped dynamics minimizer. The tolerances and limits for each NEB calculation can be set by the neb keyword. As discussed on the neb, it is often advantageous to use a larger timestep for NEB than for normal dyanmics. Since the size of the timestep set by the timestep command is used by TAD for performing dynamics, there is a neb_step keyword which can be used to set a larger timestep for each NEB calculation if desired.

A key aspect of the TAD method is setting the stopping criterion appropriately. If this criterion is too conservative, then many events must be generated before one is finally executed. Conversely, if this criterion is too aggressive, high-entropy high-barrier events will be over-sampled, while low-entropy low-barrier events will be under-sampled. If the lowest pre-exponential factor is known fairly accurately, then it can be used to estimate tmax, and the value of delta can be set to the desired confidence level e.g. delta = 0.05 corresponds to 95% confidence. However, for systems where the dynamics are not well characterized (the most common case), it will be necessary to experiment with the values of delta and tmax to get a good trade-off between accuracy and performance.

A second key aspect is the choice of t_hi. A larger value greatly increases the rate at which new events are generated. However, too large a value introduces errors due to anharmonicity (not accounted for within hTST). Once again, for any given system, experimentation is necessary to determine the best value of t_hi.

Five kinds of output can be generated during a TAD run: event statistics, NEB statistics, thermodynamic output by each replica, dump files, and restart files.

Event statistics are printed to the screen and master log.lammps file each time an event is executed. The quantities are the timestep, CPU time, global event number N, local event number M, event status, energy barrier, time margin, t_lo and delt_lo. The timestep is the usual LAMMPS timestep, which corresponds to the high-temperature time at which the event was detected, in units of timestep. The CPU time is the total processor time since the start of the TAD run. The global event number N is a counter that increments with each executed event. The local event number M is a counter that resets to zero upon entering each new basin. The event status is E when an event is executed, and is D for an event that is detected, while DF is for a detected event that is also the earliest (first) event at the low temperature.

The time margin is the ratio of the high temperature time in the current basin to the stopping time. This last number can be used to judge whether the stopping time is too short or too long (see above).

t_lo is the low-temperature event time when the current basin was entered, in units of timestep. del*t_lo* is the time of each detected event, measured relative to t_lo. delt_lo is equal to the high-temperature time since entering the current basin, scaled by an exponential factor that depends on the hi/lo temperature ratio and the energy barrier for that event.

On lines for executed events, with status E, the global event number is incremented by one, the local event number and time margin are reset to zero, while the global event number, energy barrier, and delt_lo match the last event with status DF in the immediately preceding block of detected events. The low-temperature event time t_lo is incremented by delt_lo.

NEB statistics are written to the file specified by the neb_log keyword. If the keyword value is “none”, then no NEB statistics are printed out. The statistics are written every Nevery timesteps. See the neb command for a full description of the NEB statistics. When invoked from TAD, NEB statistics are never printed to the screen.

Because the NEB calculation must run on multiple partitions, LAMMPS produces additional screen and log files for each partition, e.g. log.lammps.0, log.lammps.1, etc. For the TAD command, these contain the thermodynamic output of each NEB replica. In addition, the log file for the first partition, log.lammps.0, will contain thermodynamic output from short runs and minimizations corresponding to the dynamics and quench operations, as well as a line for each new detected event, as described above.

After the TAD command completes, timing statistics for the TAD run are printed in each replica’s log file, giving a breakdown of how much CPU time was spent in each stage (NEB, dynamics, quenching, etc).

Any dump files defined in the input script will be written to during a TAD run at timesteps when an event is executed. This means the the requested dump frequency in the dump command is ignored. There will be one dump file (per dump command) created for all partitions. The atom coordinates of the dump snapshot are those of the minimum energy configuration resulting from quenching following the executed event. The timesteps written into the dump files correspond to the timestep at which the event occurred and NOT the clock. A dump snapshot corresponding to the initial minimum state used for event detection is written to the dump file at the beginning of each TAD run.

If the restart command is used, a single restart file for all the partitions is generated, which allows a TAD run to be continued by a new input script in the usual manner. The restart file is generated after an event is executed. The restart file contains a snapshot of the system in the new quenched state, including the event number and the low-temperature time. The restart frequency specified in the restart command is interpreted differently when performing a TAD run. It does not mean the timestep interval between restart files. Instead it means an event interval for executed events. Thus a frequency of 1 means write a restart file every time an event is executed. A frequency of 10 means write a restart file every 10th executed event. When an input script reads a restart file from a previous TAD run, the new script can be run on a different number of replicas or processors.

Note that within a single state, the dynamics will typically temporarily continue beyond the event that is ultimately chosen, until the stopping criterionis satisfied. When the event is eventually executed, the timestep counter is reset to the value when the event was detected. Similarly, after each quench and NEB minimization, the timestep counter is reset to the value at the start of the minimization. This means that the timesteps listed in the replica log files do not always increase monotonically. However, the timestep values printed to the master log file, dump files, and restart files are always monotonically increasing.

Restrictions

This command can only be used if LAMMPS was built with the REPLICA package. See the Making LAMMPS section for more info on packages.

N setting must be integer multiple of t_event.

Runs restarted from restart files written during a TAD run will only produce identical results if the user-specified integrator supports exact restarts. So fix nvt will produce an exact restart, but fix langevin will not.

This command cannot be used when any fixes are defined that keep track of elapsed time to perform time-dependent operations. Examples include the “ave” fixes such as fix ave/chunk. Also fix dt/reset and fix deposit.

Default

The option defaults are min = 0.1 0.1 40 50, neb = 0.01 100 100 10, neb_style = quickmin, neb_step = the same timestep set by the timestep command, and neb_log = “none”.

(Voter) Sorensen and Voter, J Chem Phys, 112, 9599 (2000)

(Voter2) Voter, Montalenti, Germann, Annual Review of Materials Research 32, 321 (2002).

\ No newline at end of file diff --git a/doc/src/Section_python.txt b/doc/src/Section_python.txt index 0cda354dd..1475daa94 100644 --- a/doc/src/Section_python.txt +++ b/doc/src/Section_python.txt @@ -1,819 +1,819 @@ "Previous Section"_Section_modify.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_errors.html :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line 11. Python interface to LAMMPS :h3 LAMMPS can work together with Python in two ways. First, Python can wrap LAMMPS through the "LAMMPS library interface"_Section_howto.html#howto_19, so that a Python script can create one or more instances of LAMMPS and launch one or more simulations. In Python lingo, this is "extending" Python with LAMMPS. Second, LAMMPS can use the Python interpreter, so that a LAMMPS input script can invoke Python code, and pass information back-and-forth between the input script and Python functions you write. The Python code can also callback to LAMMPS to query or change its attributes. In Python lingo, this is "embedding" Python in LAMMPS. This section describes how to do both. 11.1 "Overview of running LAMMPS from Python"_#py_1 11.2 "Overview of using Python from a LAMMPS script"_#py_2 11.3 "Building LAMMPS as a shared library"_#py_3 11.4 "Installing the Python wrapper into Python"_#py_4 11.5 "Extending Python with MPI to run in parallel"_#py_5 11.6 "Testing the Python-LAMMPS interface"_#py_6 11.7 "Using LAMMPS from Python"_#py_7 11.8 "Example Python scripts that use LAMMPS"_#py_8 :ul If you are not familiar with it, "Python"_http://www.python.org is a powerful scripting and programming language which can essentially do anything that faster, lower-level languages like C or C++ can do, but typically with much fewer lines of code. When used in embedded mode, Python can perform operations that the simplistic LAMMPS input script syntax cannot. Python can be also be used as a "glue" language to drive a program through its library interface, or to hook multiple pieces of software together, such as a simulation package plus a visualization package, or to run a coupled multiscale or multiphysics model. See "Section 6.10"_Section_howto.html#howto_10 of the manual and the couple directory of the distribution for more ideas about coupling -LAMMPS to other codes. See "Section_howto -19"_Section_howto.html#howto_19 for a description of the LAMMPS +LAMMPS to other codes. See "Section +6.19"_Section_howto.html#howto_19 for a description of the LAMMPS library interface provided in src/library.cpp and src/library.h, and how to extend it for your needs. As described below, that interface is what is exposed to Python either when calling LAMMPS from Python or when calling Python from a LAMMPS input script and then calling back to LAMMPS from Python code. The library interface is designed to be easy to add functions to. Thus the Python interface to LAMMPS is also easy to extend as well. If you create interesting Python scripts that run LAMMPS or interesting Python functions that can be called from a LAMMPS input script, that you think would be useful to other users, please "email them to the developers"_http://lammps.sandia.gov/authors.html. We can include them in the LAMMPS distribution. :line :line 11.1 Overview of running LAMMPS from Python :link(py_1),h4 The LAMMPS distribution includes a python directory with all you need to run LAMMPS from Python. The python/lammps.py file wraps the LAMMPS library interface, with one wrapper function per LAMMPS library function. This file makes it is possible to do the following either from a Python script, or interactively from a Python prompt: create one or more instances of LAMMPS, invoke LAMMPS commands or give it an input script, run LAMMPS incrementally, extract LAMMPS results, an modify internal LAMMPS variables. From a Python script you can do this in serial or parallel. Running Python interactively in parallel does not generally work, unless you have a version of Python that extends standard Python to enable multiple instances of Python to read what you type. To do all of this, you must first build LAMMPS as a shared library, then insure that your Python can find the python/lammps.py file and the shared library. These steps are explained in subsequent sections 11.3 and 11.4. Sections 11.5 and 11.6 discuss using MPI from a parallel Python program and how to test that you are ready to use LAMMPS from Python. Section 11.7 lists all the functions in the current LAMMPS library interface and how to call them from Python. Section 11.8 gives some examples of coupling LAMMPS to other tools via Python. For example, LAMMPS can easily be coupled to a GUI or other visualization tools that display graphs or animations in real time as LAMMPS runs. Examples of such scripts are inlcluded in the python directory. Two advantages of using Python to run LAMMPS are how concise the language is, and that it can be run interactively, enabling rapid development and debugging of programs. If you use it to mostly invoke costly operations within LAMMPS, such as running a simulation for a reasonable number of timesteps, then the overhead cost of invoking LAMMPS thru Python will be negligible. The Python wrapper for LAMMPS uses the amazing and magical (to me) "ctypes" package in Python, which auto-generates the interface code needed between Python and a set of C interface routines for a library. Ctypes is part of standard Python for versions 2.5 and later. You can check which version of Python you have installed, by simply typing "python" at a shell prompt. :line 11.2 Overview of using Python from a LAMMPS script :link(py_2),h4 NOTE: It is not currently possible to use the "python"_python.html command described in this section with Python 3, only with Python 2. The C API changed from Python 2 to 3 and the LAMMPS code is not compatible with both. LAMMPS has a "python"_python.html command which can be used in an input script to define and execute a Python function that you write the code for. The Python function can also be assigned to a LAMMPS python-style variable via the "variable"_variable.html command. Each time the variable is evaluated, either in the LAMMPS input script itself, or by another LAMMPS command that uses the variable, this will trigger the Python function to be invoked. The Python code for the function can be included directly in the input script or in an auxiliary file. The function can have arguments which are mapped to LAMMPS variables (also defined in the input script) and it can return a value to a LAMMPS variable. This is thus a mechanism for your input script to pass information to a piece of Python code, ask Python to execute the code, and return information to your input script. Note that a Python function can be arbitrarily complex. It can import other Python modules, instantiate Python classes, call other Python functions, etc. The Python code that you provide can contain more code than the single function. It can contain other functions or Python classes, as well as global variables or other mechanisms for storing state between calls from LAMMPS to the function. The Python function you provide can consist of "pure" Python code that only performs operations provided by standard Python. However, the Python function can also "call back" to LAMMPS through its Python-wrapped library interface, in the manner described in the previous section 11.1. This means it can issue LAMMPS input script commands or query and set internal LAMMPS state. As an example, this can be useful in an input script to create a more complex loop with branching logic, than can be created using the simple looping and branching logic enabled by the "next"_next.html and "if"_if.html commands. See the "python"_python.html doc page and the "variable"_variable.html doc page for its python-style variables for more info, including examples of Python code you can write for both pure Python operations and callbacks to LAMMPS. To run pure Python code from LAMMPS, you only need to build LAMMPS with the PYTHON package installed: make yes-python make machine :pre Note that this will link LAMMPS with the Python library on your system, which typically requires several auxiliary system libraries to also be linked. The list of these libraries and the paths to find them are specified in the lib/python/Makefile.lammps file. You need to insure that file contains the correct information for your version of Python and your machine to successfully build LAMMPS. See the lib/python/README file for more info. If you want to write Python code with callbacks to LAMMPS, then you must also follow the steps overviewed in the preceeding section (11.1) for running LAMMPS from Python. I.e. you must build LAMMPS as a shared library and insure that Python can find the python/lammps.py file and the shared library. :line 11.3 Building LAMMPS as a shared library :link(py_3),h4 Instructions on how to build LAMMPS as a shared library are given in "Section 2.5"_Section_start.html#start_5. A shared library is one that is dynamically loadable, which is what Python requires to wrap LAMMPS. On Linux this is a library file that ends in ".so", not ".a". From the src directory, type make foo mode=shlib :pre where foo is the machine target name, such as linux or g++ or serial. This should create the file liblammps_foo.so in the src directory, as well as a soft link liblammps.so, which is what the Python wrapper will load by default. Note that if you are building multiple machine versions of the shared library, the soft link is always set to the most recently built version. NOTE: If you are building LAMMPS with an MPI or FFT library or other auxiliary libraries (used by various packages), then all of these extra libraries must also be shared libraries. If the LAMMPS shared-library build fails with an error complaining about this, see "Section 2.5"_Section_start.html#start_5 for more details. :line 11.4 Installing the Python wrapper into Python :link(py_4),h4 For Python to invoke LAMMPS, there are 2 files it needs to know about: python/lammps.py src/liblammps.so :ul Lammps.py is the Python wrapper on the LAMMPS library interface. Liblammps.so is the shared LAMMPS library that Python loads, as described above. You can insure Python can find these files in one of two ways: set two environment variables run the python/install.py script :ul If you set the paths to these files as environment variables, you only have to do it once. For the csh or tcsh shells, add something like this to your ~/.cshrc file, one line for each of the two files: setenv PYTHONPATH $\{PYTHONPATH\}:/home/sjplimp/lammps/python setenv LD_LIBRARY_PATH $\{LD_LIBRARY_PATH\}:/home/sjplimp/lammps/src :pre If you use the python/install.py script, you need to invoke it every time you rebuild LAMMPS (as a shared library) or make changes to the python/lammps.py file. You can invoke install.py from the python directory as % python install.py \[libdir\] \[pydir\] :pre The optional libdir is where to copy the LAMMPS shared library to; the default is /usr/local/lib. The optional pydir is where to copy the lammps.py file to; the default is the site-packages directory of the version of Python that is running the install script. Note that libdir must be a location that is in your default LD_LIBRARY_PATH, like /usr/local/lib or /usr/lib. And pydir must be a location that Python looks in by default for imported modules, like its site-packages dir. If you want to copy these files to non-standard locations, such as within your own user space, you will need to set your PYTHONPATH and LD_LIBRARY_PATH environment variables accordingly, as above. If the install.py script does not allow you to copy files into system directories, prefix the python command with "sudo". If you do this, make sure that the Python that root runs is the same as the Python you run. E.g. you may need to do something like % sudo /usr/local/bin/python install.py \[libdir\] \[pydir\] :pre You can also invoke install.py from the make command in the src directory as % make install-python :pre In this mode you cannot append optional arguments. Again, you may need to prefix this with "sudo". In this mode you cannot control which Python is invoked by root. Note that if you want Python to be able to load different versions of the LAMMPS shared library (see "this section"_#py_5 below), you will need to manually copy files like liblammps_g++.so into the appropriate system directory. This is not needed if you set the LD_LIBRARY_PATH environment variable as described above. :line 11.5 Extending Python with MPI to run in parallel :link(py_5),h4 If you wish to run LAMMPS in parallel from Python, you need to extend your Python with an interface to MPI. This also allows you to make MPI calls directly from Python in your script, if you desire. There are several Python packages available that purport to wrap MPI as a library and allow MPI functions to be called from Python. However, development on most of them seems to be halted except on: "mpi4py"_https://bitbucket.org/mpi4py/mpi4py "PyPar"_https://github.com/daleroberts/pypar :ul Both packages, PyPar and mpi4py have been successfully tested with LAMMPS. PyPar is simpler and easy to set up and use, but supports only a subset of MPI. Mpi4py is more MPI-feature complete, but also a bit more complex to use. As of version 2.0.0, mpi4py is the only python MPI wrapper that allows passing a custom MPI communicator to the LAMMPS constructor, which means one can easily run one or more LAMMPS instances on subsets of the total MPI ranks. :line PyPar requires the ubiquitous "Numpy package"_http://numpy.scipy.org be installed in your Python. After launching Python, type import numpy :pre to see if it is installed. If not, here is how to install it (version 1.3.0b1 as of April 2009). Unpack the numpy tarball and from its top-level directory, type python setup.py build sudo python setup.py install :pre The "sudo" is only needed if required to copy Numpy files into your Python distribution's site-packages directory. To install PyPar (version pypar-2.1.4_94 as of Aug 2012), unpack it and from its "source" directory, type python setup.py build sudo python setup.py install :pre Again, the "sudo" is only needed if required to copy PyPar files into your Python distribution's site-packages directory. If you have successully installed PyPar, you should be able to run Python and type import pypar :pre without error. You should also be able to run python in parallel on a simple test script % mpirun -np 4 python test.py :pre where test.py contains the lines import pypar print "Proc %d out of %d procs" % (pypar.rank(),pypar.size()) :pre and see one line of output for each processor you run on. NOTE: To use PyPar and LAMMPS in parallel from Python, you must insure both are using the same version of MPI. If you only have one MPI installed on your system, this is not an issue, but it can be if you have multiple MPIs. Your LAMMPS build is explicit about which MPI it is using, since you specify the details in your lo-level src/MAKE/Makefile.foo file. PyPar uses the "mpicc" command to find information about the MPI it uses to build against. And it tries to load "libmpi.so" from the LD_LIBRARY_PATH. This may or may not find the MPI library that LAMMPS is using. If you have problems running both PyPar and LAMMPS together, this is an issue you may need to address, e.g. by moving other MPI installations so that PyPar finds the right one. :line To install mpi4py (version mpi4py-2.0.0 as of Oct 2015), unpack it and from its main directory, type python setup.py build sudo python setup.py install :pre Again, the "sudo" is only needed if required to copy mpi4py files into your Python distribution's site-packages directory. To install with user privilege into the user local directory type python setup.py install --user :pre If you have successully installed mpi4py, you should be able to run Python and type from mpi4py import MPI :pre without error. You should also be able to run python in parallel on a simple test script % mpirun -np 4 python test.py :pre where test.py contains the lines from mpi4py import MPI comm = MPI.COMM_WORLD print "Proc %d out of %d procs" % (comm.Get_rank(),comm.Get_size()) :pre and see one line of output for each processor you run on. NOTE: To use mpi4py and LAMMPS in parallel from Python, you must insure both are using the same version of MPI. If you only have one MPI installed on your system, this is not an issue, but it can be if you have multiple MPIs. Your LAMMPS build is explicit about which MPI it is using, since you specify the details in your lo-level src/MAKE/Makefile.foo file. Mpi4py uses the "mpicc" command to find information about the MPI it uses to build against. And it tries to load "libmpi.so" from the LD_LIBRARY_PATH. This may or may not find the MPI library that LAMMPS is using. If you have problems running both mpi4py and LAMMPS together, this is an issue you may need to address, e.g. by moving other MPI installations so that mpi4py finds the right one. :line 11.6 Testing the Python-LAMMPS interface :link(py_6),h4 To test if LAMMPS is callable from Python, launch Python interactively and type: >>> from lammps import lammps >>> lmp = lammps() :pre If you get no errors, you're ready to use LAMMPS from Python. If the 2nd command fails, the most common error to see is OSError: Could not load LAMMPS dynamic library :pre which means Python was unable to load the LAMMPS shared library. This typically occurs if the system can't find the LAMMPS shared library or one of the auxiliary shared libraries it depends on, or if something about the library is incompatible with your Python. The error message should give you an indication of what went wrong. You can also test the load directly in Python as follows, without first importing from the lammps.py file: >>> from ctypes import CDLL >>> CDLL("liblammps.so") :pre If an error occurs, carefully go thru the steps in "Section 2.5"_Section_start.html#start_5 and above about building a shared library and about insuring Python can find the necessary two files it needs. [Test LAMMPS and Python in serial:] :h5 To run a LAMMPS test in serial, type these lines into Python interactively from the bench directory: >>> from lammps import lammps >>> lmp = lammps() >>> lmp.file("in.lj") :pre Or put the same lines in the file test.py and run it as % python test.py :pre Either way, you should see the results of running the in.lj benchmark on a single processor appear on the screen, the same as if you had typed something like: lmp_g++ -in in.lj :pre [Test LAMMPS and Python in parallel:] :h5 To run LAMMPS in parallel, assuming you have installed the "PyPar"_https://github.com/daleroberts/pypar package as discussed above, create a test.py file containing these lines: import pypar from lammps import lammps lmp = lammps() lmp.file("in.lj") print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()),lmp pypar.finalize() :pre To run LAMMPS in parallel, assuming you have installed the "mpi4py"_https://bitbucket.org/mpi4py/mpi4py package as discussed above, create a test.py file containing these lines: from mpi4py import MPI from lammps import lammps lmp = lammps() lmp.file("in.lj") me = MPI.COMM_WORLD.Get_rank() nprocs = MPI.COMM_WORLD.Get_size() print "Proc %d out of %d procs has" % (me,nprocs),lmp MPI.Finalize() :pre You can either script in parallel as: % mpirun -np 4 python test.py :pre and you should see the same output as if you had typed % mpirun -np 4 lmp_g++ -in in.lj :pre Note that if you leave out the 3 lines from test.py that specify PyPar commands you will instantiate and run LAMMPS independently on each of the P processors specified in the mpirun command. In this case you should get 4 sets of output, each showing that a LAMMPS run was made on a single processor, instead of one set of output showing that LAMMPS ran on 4 processors. If the 1-processor outputs occur, it means that PyPar is not working correctly. Also note that once you import the PyPar module, PyPar initializes MPI for you, and you can use MPI calls directly in your Python script, as described in the PyPar documentation. The last line of your Python script should be pypar.finalize(), to insure MPI is shut down correctly. [Running Python scripts:] :h5 Note that any Python script (not just for LAMMPS) can be invoked in one of several ways: % python foo.script % python -i foo.script % foo.script :pre The last command requires that the first line of the script be something like this: #!/usr/local/bin/python #!/usr/local/bin/python -i :pre where the path points to where you have Python installed, and that you have made the script file executable: % chmod +x foo.script :pre Without the "-i" flag, Python will exit when the script finishes. With the "-i" flag, you will be left in the Python interpreter when the script finishes, so you can type subsequent commands. As mentioned above, you can only run Python interactively when running Python on a single processor, not in parallel. :line :line 11.7 Using LAMMPS from Python :link(py_7),h4 As described above, the Python interface to LAMMPS consists of a Python "lammps" module, the source code for which is in python/lammps.py, which creates a "lammps" object, with a set of methods that can be invoked on that object. The sample Python code below assumes you have first imported the "lammps" module in your Python script, as follows: from lammps import lammps :pre These are the methods defined by the lammps module. If you look at the files src/library.cpp and src/library.h you will see that they correspond one-to-one with calls you can make to the LAMMPS library from a C++ or C or Fortran program. lmp = lammps() # create a LAMMPS object using the default liblammps.so library 4 optional args are allowed: name, cmdargs, ptr, comm lmp = lammps(ptr=lmpptr) # use lmpptr as previously created LAMMPS object lmp = lammps(comm=split) # create a LAMMPS object with a custom communicator, requires mpi4py 2.0.0 or later lmp = lammps(name="g++") # create a LAMMPS object using the liblammps_g++.so library lmp = lammps(name="g++",cmdargs=list) # add LAMMPS command-line args, e.g. list = \["-echo","screen"\] :pre lmp.close() # destroy a LAMMPS object :pre version = lmp.version() # return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902 lmp.file(file) # run an entire input script, file = "in.lj" lmp.command(cmd) # invoke a single LAMMPS command, cmd = "run 100" :pre xlo = lmp.extract_global(name,type) # extract a global quantity # name = "boxxlo", "nlocal", etc # type = 0 = int # 1 = double :pre coords = lmp.extract_atom(name,type) # extract a per-atom quantity # name = "x", "type", etc # type = 0 = vector of ints # 1 = array of ints # 2 = vector of doubles # 3 = array of doubles :pre eng = lmp.extract_compute(id,style,type) # extract value(s) from a compute v3 = lmp.extract_fix(id,style,type,i,j) # extract value(s) from a fix # id = ID of compute or fix # style = 0 = global data # 1 = per-atom data # 2 = local data # type = 0 = scalar # 1 = vector # 2 = array # i,j = indices of value in global vector or array :pre var = lmp.extract_variable(name,group,flag) # extract value(s) from a variable # name = name of variable # group = group ID (ignored for equal-style variables) # flag = 0 = equal-style variable # 1 = atom-style variable :pre flag = lmp.set_variable(name,value) # set existing named string-style variable to value, flag = 0 if successful natoms = lmp.get_natoms() # total # of atoms as int data = lmp.gather_atoms(name,type,count) # return atom attribute of all atoms gathered into data, ordered by atom ID # name = "x", "charge", "type", etc # count = # of per-atom values, 1 or 3, etc lmp.scatter_atoms(name,type,count,data) # scatter atom attribute of all atoms from data, ordered by atom ID # name = "x", "charge", "type", etc # count = # of per-atom values, 1 or 3, etc :pre :line The lines from lammps import lammps lmp = lammps() :pre create an instance of LAMMPS, wrapped in a Python class by the lammps Python module, and return an instance of the Python class as lmp. It is used to make all subequent calls to the LAMMPS library. Additional arguments can be used to tell Python the name of the shared library to load or to pass arguments to the LAMMPS instance, the same as if LAMMPS were launched from a command-line prompt. If the ptr argument is set like this: lmp = lammps(ptr=lmpptr) :pre then lmpptr must be an argument passed to Python via the LAMMPS "python"_python.html command, when it is used to define a Python function that is invoked by the LAMMPS input script. This mode of using Python with LAMMPS is described above in 11.2. The variable lmpptr refers to the instance of LAMMPS that called the embedded Python interpreter. Using it as an argument to lammps() allows the returned Python class instance "lmp" to make calls to that instance of LAMMPS. See the "python"_python.html command doc page for examples using this syntax. Note that you can create multiple LAMMPS objects in your Python script, and coordinate and run multiple simulations, e.g. from lammps import lammps lmp1 = lammps() lmp2 = lammps() lmp1.file("in.file1") lmp2.file("in.file2") :pre The file() and command() methods allow an input script or single commands to be invoked. The extract_global(), extract_atom(), extract_compute(), extract_fix(), and extract_variable() methods return values or pointers to data structures internal to LAMMPS. For extract_global() see the src/library.cpp file for the list of valid names. New names could easily be added. A double or integer is returned. You need to specify the appropriate data type via the type argument. For extract_atom(), a pointer to internal LAMMPS atom-based data is returned, which you can use via normal Python subscripting. See the extract() method in the src/atom.cpp file for a list of valid names. Again, new names could easily be added. A pointer to a vector of doubles or integers, or a pointer to an array of doubles (double **) or integers (int **) is returned. You need to specify the appropriate data type via the type argument. For extract_compute() and extract_fix(), the global, per-atom, or local data calulated by the compute or fix can be accessed. What is returned depends on whether the compute or fix calculates a scalar or vector or array. For a scalar, a single double value is returned. If the compute or fix calculates a vector or array, a pointer to the internal LAMMPS data is returned, which you can use via normal Python subscripting. The one exception is that for a fix that calculates a global vector or array, a single double value from the vector or array is returned, indexed by I (vector) or I and J (array). I,J are zero-based indices. The I,J arguments can be left out if not needed. See "Section 6.15"_Section_howto.html#howto_15 of the manual for a discussion of global, per-atom, and local data, and of scalar, vector, and array data types. See the doc pages for individual "computes"_compute.html and "fixes"_fix.html for a description of what they calculate and store. For extract_variable(), an "equal-style or atom-style variable"_variable.html is evaluated and its result returned. For equal-style variables a single double value is returned and the group argument is ignored. For atom-style variables, a vector of doubles is returned, one value per atom, which you can use via normal Python subscripting. The values will be zero for atoms not in the specified group. The get_natoms() method returns the total number of atoms in the simulation, as an int. The gather_atoms() method returns a ctypes vector of ints or doubles as specified by type, of length count*natoms, for the property of all the atoms in the simulation specified by name, ordered by count and then by atom ID. The vector can be used via normal Python subscripting. If atom IDs are not consecutively ordered within LAMMPS, a None is returned as indication of an error. Note that the data structure gather_atoms("x") returns is different from the data structure returned by extract_atom("x") in four ways. (1) Gather_atoms() returns a vector which you index as x\[i\]; extract_atom() returns an array which you index as x\[i\]\[j\]. (2) Gather_atoms() orders the atoms by atom ID while extract_atom() does not. (3) Gathert_atoms() returns a list of all atoms in the simulation; extract_atoms() returns just the atoms local to each processor. (4) Finally, the gather_atoms() data structure is a copy of the atom coords stored internally in LAMMPS, whereas extract_atom() returns an array that effectively points directly to the internal data. This means you can change values inside LAMMPS from Python by assigning a new values to the extract_atom() array. To do this with the gather_atoms() vector, you need to change values in the vector, then invoke the scatter_atoms() method. The scatter_atoms() method takes a vector of ints or doubles as specified by type, of length count*natoms, for the property of all the atoms in the simulation specified by name, ordered by bount and then by atom ID. It uses the vector of data to overwrite the corresponding properties for each atom inside LAMMPS. This requires LAMMPS to have its "map" option enabled; see the "atom_modify"_atom_modify.html command for details. If it is not, or if atom IDs are not consecutively ordered, no coordinates are reset. The array of coordinates passed to scatter_atoms() must be a ctypes vector of ints or doubles, allocated and initialized something like this: from ctypes import * natoms = lmp.get_natoms() n3 = 3*natoms x = (n3*c_double)() x\[0\] = x coord of atom with ID 1 x\[1\] = y coord of atom with ID 1 x\[2\] = z coord of atom with ID 1 x\[3\] = x coord of atom with ID 2 ... x\[n3-1\] = z coord of atom with ID natoms lmp.scatter_coords("x",1,3,x) :pre Alternatively, you can just change values in the vector returned by gather_atoms("x",1,3), since it is a ctypes vector of doubles. :line As noted above, these Python class methods correspond one-to-one with the functions in the LAMMPS library interface in src/library.cpp and library.h. This means you can extend the Python wrapper via the following steps: Add a new interface function to src/library.cpp and src/library.h. :ulb,l Rebuild LAMMPS as a shared library. :l Add a wrapper method to python/lammps.py for this interface function. :l You should now be able to invoke the new interface function from a Python script. Isn't ctypes amazing? :l :ule :line :line 11.8 Example Python scripts that use LAMMPS :link(py_8),h4 These are the Python scripts included as demos in the python/examples directory of the LAMMPS distribution, to illustrate the kinds of things that are possible when Python wraps LAMMPS. If you create your own scripts, send them to us and we can include them in the LAMMPS distribution. trivial.py, read/run a LAMMPS input script thru Python, demo.py, invoke various LAMMPS library interface routines, simple.py, run in parallel, similar to examples/COUPLE/simple/simple.cpp, split.py, same as simple.py but running in parallel on a subset of procs, gui.py, GUI go/stop/temperature-slider to control LAMMPS, plot.py, real-time temeperature plot with GnuPlot via Pizza.py, viz_tool.py, real-time viz via some viz package, vizplotgui_tool.py, combination of viz_tool.py and plot.py and gui.py :tb(c=2) :line For the viz_tool.py and vizplotgui_tool.py commands, replace "tool" with "gl" or "atomeye" or "pymol" or "vmd", depending on what visualization package you have installed. Note that for GL, you need to be able to run the Pizza.py GL tool, which is included in the pizza sub-directory. See the "Pizza.py doc pages"_pizza for more info: :link(pizza,http://www.sandia.gov/~sjplimp/pizza.html) Note that for AtomEye, you need version 3, and there is a line in the scripts that specifies the path and name of the executable. See the AtomEye WWW pages "here"_atomeye or "here"_atomeye3 for more details: http://mt.seas.upenn.edu/Archive/Graphics/A http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html :pre :link(atomeye,http://mt.seas.upenn.edu/Archive/Graphics/A) :link(atomeye3,http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html) The latter link is to AtomEye 3 which has the scriping capability needed by these Python scripts. Note that for PyMol, you need to have built and installed the open-source version of PyMol in your Python, so that you can import it from a Python script. See the PyMol WWW pages "here"_pymolhome or "here"_pymolopen for more details: http://www.pymol.org http://sourceforge.net/scm/?type=svn&group_id=4546 :pre :link(pymolhome,http://www.pymol.org) :link(pymolopen,http://sourceforge.net/scm/?type=svn&group_id=4546) The latter link is to the open-source version. Note that for VMD, you need a fairly current version (1.8.7 works for me) and there are some lines in the pizza/vmd.py script for 4 PIZZA variables that have to match the VMD installation on your system. :line See the python/README file for instructions on how to run them and the source code for individual scripts for comments about what they do. Here are screenshots of the vizplotgui_tool.py script in action for different visualization package options. Click to see larger images: :image(JPG/screenshot_gl_small.jpg,JPG/screenshot_gl.jpg) :image(JPG/screenshot_atomeye_small.jpg,JPG/screenshot_atomeye.jpg) :image(JPG/screenshot_pymol_small.jpg,JPG/screenshot_pymol.jpg) :image(JPG/screenshot_vmd_small.jpg,JPG/screenshot_vmd.jpg) diff --git a/doc/src/Section_start.txt b/doc/src/Section_start.txt index 8a73a0dfe..d2202679c 100644 --- a/doc/src/Section_start.txt +++ b/doc/src/Section_start.txt @@ -1,1909 +1,1909 @@ "Previous Section"_Section_intro.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_commands.html :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line 2. Getting Started :h3 This section describes how to build and run LAMMPS, for both new and experienced users. 2.1 "What's in the LAMMPS distribution"_#start_1 2.2 "Making LAMMPS"_#start_2 2.3 "Making LAMMPS with optional packages"_#start_3 2.4 "Building LAMMPS via the Make.py script"_#start_4 2.5 "Building LAMMPS as a library"_#start_5 2.6 "Running LAMMPS"_#start_6 2.7 "Command-line options"_#start_7 2.8 "Screen output"_#start_8 2.9 "Tips for users of previous versions"_#start_9 :all(b) :line :line 2.1 What's in the LAMMPS distribution :h4,link(start_1) When you download a LAMMPS tarball you will need to unzip and untar the downloaded file with the following commands, after placing the tarball in an appropriate directory. tar -xzvf lammps*.tar.gz :pre This will create a LAMMPS directory containing two files and several sub-directories: README: text file LICENSE: the GNU General Public License (GPL) bench: benchmark problems doc: documentation examples: simple test problems potentials: embedded atom method (EAM) potential files src: source files tools: pre- and post-processing tools :tb(s=:) Note that the "download page"_download also has links to download pre-build Windows installers, as well as pre-built packages for several widely used Linux distributions. It also has instructions for how to download/install LAMMPS for Macs (via Homebrew), and to download and update LAMMPS from SVN and Git repositories, which gives you access to the up-to-date sources that are used by the LAMMPS core developers. :link(download,http://lammps.sandia.gov/download.html) The Windows and Linux packages for serial or parallel include only selected packages and bug-fixes/upgrades listed on "this page"_http://lammps.sandia.gov/bug.html up to a certain date, as stated on the download page. If you want an executable with non-included packages or that is more current, then you'll need to build LAMMPS yourself, as discussed in the next section. Skip to the "Running LAMMPS"_#start_6 sections for info on how to launch a LAMMPS Windows executable on a Windows box. :line 2.2 Making LAMMPS :h4,link(start_2) This section has the following sub-sections: "Read this first"_#start_2_1 "Steps to build a LAMMPS executable"_#start_2_2 "Common errors that can occur when making LAMMPS"_#start_2_3 "Additional build tips"_#start_2_4 "Building for a Mac"_#start_2_5 "Building for Windows"_#start_2_6 :ul :line Read this first :h5,link(start_2_1) If you want to avoid building LAMMPS yourself, read the preceeding section about options available for downloading and installing executables. Details are discussed on the "download"_download page. Building LAMMPS can be simple or not-so-simple. If all you need are the default packages installed in LAMMPS, and MPI is already installed on your machine, or you just want to run LAMMPS in serial, then you can typically use the Makefile.mpi or Makefile.serial files in src/MAKE by typing one of these lines (from the src dir): make mpi make serial :pre Note that on a facility supercomputer, there are often "modules" loaded in your environment that provide the compilers and MPI you should use. In this case, the "mpicxx" compile/link command in Makefile.mpi should just work by accessing those modules. It may be the case that one of the other Makefile.machine files in the src/MAKE sub-directories is a better match to your system (type "make" to see a list), you can use it as-is by typing (for example): make stampede :pre If any of these builds (with an existing Makefile.machine) works on your system, then you're done! If you want to do one of the following: use optional LAMMPS features that require additional libraries use optional packages that require additional libraries use optional accelerator packages that require special compiler/linker settings run on a specialized platform that has its own compilers, settings, or other libs to use :ul then building LAMMPS is more complicated. You may need to find where auxiliary libraries exist on your machine or install them if they don't. You may need to build additional libraries that are part of the LAMMPS package, before building LAMMPS. You may need to edit a Makefile.machine file to make it compatible with your system. Note that there is a Make.py tool in the src directory that automates several of these steps, but you still have to know what you are doing. "Section 2.4"_#start_4 below describes the tool. It is a convenient way to work with installing/un-installing various packages, the Makefile.machine changes required by some packages, and the auxiliary libraries some of them use. Please read the following sections carefully. If you are not comfortable with makefiles, or building codes on a Unix platform, or running an MPI job on your machine, please find a local expert to help you. Many compilation, linking, and run problems that users have are often not really LAMMPS issues - they are peculiar to the user's system, compilers, libraries, etc. Such questions are better answered by a local expert. If you have a build problem that you are convinced is a LAMMPS issue (e.g. the compiler complains about a line of LAMMPS source code), then please post the issue to the "LAMMPS mail list"_http://lammps.sandia.gov/mail.html. If you succeed in building LAMMPS on a new kind of machine, for which there isn't a similar machine Makefile included in the src/MAKE/MACHINES directory, then send it to the developers and we can include it in the LAMMPS distribution. :line Steps to build a LAMMPS executable :h5,link(start_2_2) Step 0 :h6 The src directory contains the C++ source and header files for LAMMPS. It also contains a top-level Makefile and a MAKE sub-directory with low-level Makefile.* files for many systems and machines. See the src/MAKE/README file for a quick overview of what files are available and what sub-directories they are in. The src/MAKE dir has a few files that should work as-is on many platforms. The src/MAKE/OPTIONS dir has more that invoke additional compiler, MPI, and other setting options commonly used by LAMMPS, to illustrate their syntax. The src/MAKE/MACHINES dir has many more that have been tweaked or optimized for specific machines. These files are all good starting points if you find you need to change them for your machine. Put any file you edit into the src/MAKE/MINE directory and it will be never be touched by any LAMMPS updates. >From within the src directory, type "make" or "gmake". You should see a list of available choices from src/MAKE and all of its sub-directories. If one of those has the options you want or is the machine you want, you can type a command like: make mpi :pre or make serial :pre or gmake mac :pre Note that the corresponding Makefile.machine can exist in src/MAKE or any of its sub-directories. If a file with the same name appears in multiple places (not a good idea), the order they are used is as follows: src/MAKE/MINE, src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives preference to a file you have created/edited and put in src/MAKE/MINE. Note that on a multi-processor or multi-core platform you can launch a parallel make, by using the "-j" switch with the make command, which will build LAMMPS more quickly. If you get no errors and an executable like [lmp_mpi] or [lmp_serial] or [lmp_mac] is produced, then you're done; it's your lucky day. Note that by default only a few of LAMMPS optional packages are installed. To build LAMMPS with optional packages, see "this section"_#start_3 below. Step 1 :h6 If Step 0 did not work, you will need to create a low-level Makefile for your machine, like Makefile.foo. You should make a copy of an existing Makefile.* in src/MAKE or one of its sub-directories as a starting point. The only portions of the file you need to edit are the first line, the "compiler/linker settings" section, and the "LAMMPS-specific settings" section. When it works, put the edited file in src/MAKE/MINE and it will not be altered by any future LAMMPS updates. Step 2 :h6 Change the first line of Makefile.foo to list the word "foo" after the "#", and whatever other options it will set. This is the line you will see if you just type "make". Step 3 :h6 The "compiler/linker settings" section lists compiler and linker settings for your C++ compiler, including optimization flags. You can use g++, the open-source GNU compiler, which is available on all Unix systems. You can also use mpicxx which will typically be available if MPI is installed on your system, though you should check which actual compiler it wraps. Vendor compilers often produce faster code. On boxes with Intel CPUs, we suggest using the Intel icc compiler, which can be downloaded from "Intel's compiler site"_intel. :link(intel,http://www.intel.com/software/products/noncom) If building a C++ code on your machine requires additional libraries, then you should list them as part of the LIB variable. You should not need to do this if you use mpicxx. The DEPFLAGS setting is what triggers the C++ compiler to create a dependency list for a source file. This speeds re-compilation when source (*.cpp) or header (*.h) files are edited. Some compilers do not support dependency file creation, or may use a different switch than -D. GNU g++ and Intel icc works with -D. If your compiler can't create dependency files, then you'll need to create a Makefile.foo patterned after Makefile.storm, which uses different rules that do not involve dependency files. Note that when you build LAMMPS for the first time on a new platform, a long list of *.d files will be printed out rapidly. This is not an error; it is the Makefile doing its normal creation of dependencies. Step 4 :h6 The "system-specific settings" section has several parts. Note that if you change any -D setting in this section, you should do a full re-compile, after typing "make clean" (which will describe different clean options). The LMP_INC variable is used to include options that turn on ifdefs within the LAMMPS code. The options that are currently recogized are: -DLAMMPS_GZIP -DLAMMPS_JPEG -DLAMMPS_PNG -DLAMMPS_FFMPEG -DLAMMPS_MEMALIGN -DLAMMPS_XDR -DLAMMPS_SMALLBIG -DLAMMPS_BIGBIG -DLAMMPS_SMALLSMALL -DLAMMPS_LONGLONG_TO_LONG -DLAMMPS_EXCEPTIONS -DPACK_ARRAY -DPACK_POINTER -DPACK_MEMCPY :ul The read_data and dump commands will read/write gzipped files if you compile with -DLAMMPS_GZIP. It requires that your machine supports the "popen()" function in the standard runtime library and that a gzip executable can be found by LAMMPS during a run. NOTE: on some clusters with high-speed networks, using the fork() library calls (required by popen()) can interfere with the fast communication library and lead to simulations using compressed output or input to hang or crash. For selected operations, compressed file I/O is also available using a compression library instead, which are provided in the COMPRESS package. From more details about compiling LAMMPS with packages, please see below. If you use -DLAMMPS_JPEG, the "dump image"_dump_image.html command will be able to write out JPEG image files. For JPEG files, you must also link LAMMPS with a JPEG library, as described below. If you use -DLAMMPS_PNG, the "dump image"_dump.html command will be able to write out PNG image files. For PNG files, you must also link LAMMPS with a PNG library, as described below. If neither of those two defines are used, LAMMPS will only be able to write out uncompressed PPM image files. If you use -DLAMMPS_FFMPEG, the "dump movie"_dump_image.html command will be available to support on-the-fly generation of rendered movies the need to store intermediate image files. It requires that your machines supports the "popen" function in the standard runtime library and that an FFmpeg executable can be found by LAMMPS during the run. NOTE: Similar to the note above, this option can conflict with high-speed networks, because it uses popen(). Using -DLAMMPS_MEMALIGN= enables the use of the posix_memalign() call instead of malloc() when large chunks or memory are allocated by LAMMPS. This can help to make more efficient use of vector instructions of modern CPUS, since dynamically allocated memory has to be aligned on larger than default byte boundaries (e.g. 16 bytes instead of 8 bytes on x86 type platforms) for optimal performance. If you use -DLAMMPS_XDR, the build will include XDR compatibility files for doing particle dumps in XTC format. This is only necessary if your platform does have its own XDR files available. See the Restrictions section of the "dump"_dump.html command for details. Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG, -DLAMMPS_SMALLSMALL settings. The default is -DLAMMPS_SMALLBIG. These settings refer to use of 4-byte (small) vs 8-byte (big) integers within LAMMPS, as specified in src/lmptype.h. The only reason to use the BIGBIG setting is to enable simulation of huge molecular systems (which store bond topology info) with more than 2 billion atoms, or to track the image flags of moving atoms that wrap around a periodic box more than 512 times. Normally, the only reason to use SMALLSMALL is if your machine does not support 64-bit integers, though you can use SMALLSMALL setting if you are running in serial or on a desktop machine or small cluster where you will never run large systems or for long time (more than 2 billion atoms, more than 2 billion timesteps). See the "Additional build tips"_#start_2_4 section below for more details on these settings. Note that the USER-ATC package is not currently compatible with -DLAMMPS_BIGBIG. Also the GPU package requires the lib/gpu library to be compiled with the same setting, or the link will fail. The -DLAMMPS_LONGLONG_TO_LONG setting may be needed if your system or MPI version does not recognize "long long" data types. In this case a "long" data type is likely already 64-bits, in which case this setting will convert to that data type. The -DLAMMPS_EXCEPTIONS setting can be used to activate alternative versions of error handling inside of LAMMPS. This is useful when external codes drive LAMMPS as a library. Using this option, LAMMPS errors do not kill the caller. Instead, the call stack is unwound and control returns to the caller. The library interface provides the lammps_has_error() and lammps_get_last_error_message() functions to detect and find out more about a LAMMPS error. Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY options can make for faster parallel FFTs (in the PPPM solver) on some platforms. The -DPACK_ARRAY setting is the default. See the "kspace_style"_kspace_style.html command for info about PPPM. See Step 6 below for info about building LAMMPS with an FFT library. Step 5 :h6 The 3 MPI variables are used to specify an MPI library to build LAMMPS with. Note that you do not need to set these if you use the MPI compiler mpicxx for your CC and LINK setting in the section above. The MPI wrapper knows where to find the needed files. If you want LAMMPS to run in parallel, you must have an MPI library installed on your platform. If MPI is installed on your system in the usual place (under /usr/local), you also may not need to specify these 3 variables, assuming /usr/local is in your path. On some large parallel machines which use "modules" for their compile/link environements, you may simply need to include the correct module in your build environment, before building LAMMPS. Or the parallel machine may have a vendor-provided MPI which the compiler has no trouble finding. Failing this, these 3 variables can be used to specify where the mpi.h file (MPI_INC) and the MPI library file (MPI_PATH) are found and the name of the library file (MPI_LIB). If you are installing MPI yourself, we recommend Argonne's MPICH2 or OpenMPI. MPICH can be downloaded from the "Argonne MPI site"_http://www.mcs.anl.gov/research/projects/mpich2/. OpenMPI can be downloaded from the "OpenMPI site"_http://www.open-mpi.org. Other MPI packages should also work. If you are running on a big parallel platform, your system people or the vendor should have already installed a version of MPI, which is likely to be faster than a self-installed MPICH or OpenMPI, so find out how to build and link with it. If you use MPICH or OpenMPI, you will have to configure and build it for your platform. The MPI configure script should have compiler options to enable you to use the same compiler you are using for the LAMMPS build, which can avoid problems that can arise when linking LAMMPS to the MPI library. If you just want to run LAMMPS on a single processor, you can use the dummy MPI library provided in src/STUBS, since you don't need a true MPI library installed on your system. See src/MAKE/Makefile.serial for how to specify the 3 MPI variables in this case. You will also need to build the STUBS library for your platform before making LAMMPS itself. Note that if you are building with src/MAKE/Makefile.serial, e.g. by typing "make serial", then the STUBS library is built for you. To build the STUBS library from the src directory, type "make mpi-stubs", or from the src/STUBS dir, type "make". This should create a libmpi_stubs.a file suitable for linking to LAMMPS. If the build fails, you will need to edit the STUBS/Makefile for your platform. The file STUBS/mpi.c provides a CPU timer function called MPI_Wtime() that calls gettimeofday() . If your system doesn't support gettimeofday() , you'll need to insert code to call another timer. Note that the ANSI-standard function clock() rolls over after an hour or so, and is therefore insufficient for timing long LAMMPS simulations. Step 6 :h6 The 3 FFT variables allow you to specify an FFT library which LAMMPS uses (for performing 1d FFTs) when running the particle-particle particle-mesh (PPPM) option for long-range Coulombics via the "kspace_style"_kspace_style.html command. LAMMPS supports various open-source or vendor-supplied FFT libraries for this purpose. If you leave these 3 variables blank, LAMMPS will use the open-source "KISS FFT library"_http://kissfft.sf.net, which is included in the LAMMPS distribution. This library is portable to all platforms and for typical LAMMPS simulations is almost as fast as FFTW or vendor optimized libraries. If you are not including the KSPACE package in your build, you can also leave the 3 variables blank. Otherwise, select which kinds of FFTs to use as part of the FFT_INC setting by a switch of the form -DFFT_XXX. Recommended values for XXX are: MKL, SCSL, FFTW2, and FFTW3. Legacy options are: INTEL, SGI, ACML, and T3E. For backward compatability, using -DFFT_FFTW will use the FFTW2 library. Using -DFFT_NONE will use the KISS library described above. You may also need to set the FFT_INC, FFT_PATH, and FFT_LIB variables, so the compiler and linker can find the needed FFT header and library files. Note that on some large parallel machines which use "modules" for their compile/link environements, you may simply need to include the correct module in your build environment. Or the parallel machine may have a vendor-provided FFT library which the compiler has no trouble finding. FFTW is a fast, portable library that should also work on any platform. You can download it from "www.fftw.org"_http://www.fftw.org. Both the legacy version 2.1.X and the newer 3.X versions are supported as -DFFT_FFTW2 or -DFFT_FFTW3. Building FFTW for your box should be as simple as ./configure; make. Note that on some platforms FFTW2 has been pre-installed, and uses renamed files indicating the precision it was compiled with, e.g. sfftw.h, or dfftw.h instead of fftw.h. In this case, you can specify an additional define variable for FFT_INC called -DFFTW_SIZE, which will select the correct include file. In this case, for FFT_LIB you must also manually specify the correct library, namely -lsfftw or -ldfftw. The FFT_INC variable also allows for a -DFFT_SINGLE setting that will use single-precision FFTs with PPPM, which can speed-up long-range calulations, particularly in parallel or on GPUs. Fourier transform and related PPPM operations are somewhat insensitive to floating point truncation errors and thus do not always need to be performed in double precision. Using the -DFFT_SINGLE setting trades off a little accuracy for reduced memory use and parallel communication costs for transposing 3d FFT data. Note that single precision FFTs have only been tested with the FFTW3, FFTW2, MKL, and KISS FFT options. Step 7 :h6 The 3 JPG variables allow you to specify a JPEG and/or PNG library which LAMMPS uses when writing out JPEG or PNG files via the "dump image"_dump_image.html command. These can be left blank if you do not use the -DLAMMPS_JPEG or -DLAMMPS_PNG switches discussed above in Step 4, since in that case JPEG/PNG output will be disabled. A standard JPEG library usually goes by the name libjpeg.a or libjpeg.so and has an associated header file jpeglib.h. Whichever JPEG library you have on your platform, you'll need to set the appropriate JPG_INC, JPG_PATH, and JPG_LIB variables, so that the compiler and linker can find it. A standard PNG library usually goes by the name libpng.a or libpng.so and has an associated header file png.h. Whichever PNG library you have on your platform, you'll need to set the appropriate JPG_INC, JPG_PATH, and JPG_LIB variables, so that the compiler and linker can find it. As before, if these header and library files are in the usual place on your machine, you may not need to set these variables. Step 8 :h6 Note that by default only a few of LAMMPS optional packages are installed. To build LAMMPS with optional packages, see "this section"_#start_3 below, before proceeding to Step 9. Step 9 :h6 That's it. Once you have a correct Makefile.foo, and you have pre-built any other needed libraries (e.g. MPI, FFT, etc) all you need to do from the src directory is type something like this: make foo make -j N foo gmake foo gmake -j N foo :pre The -j or -j N switches perform a parallel build which can be much faster, depending on how many cores your compilation machine has. N is the number of cores the build runs on. You should get the executable lmp_foo when the build is complete. :line Errors that can occur when making LAMMPS: h5 :link(start_2_3) NOTE: If an error occurs when building LAMMPS, the compiler or linker will state very explicitly what the problem is. The error message should give you a hint as to which of the steps above has failed, and what you need to do in order to fix it. Building a code with a Makefile is a very logical process. The compiler and linker need to find the appropriate files and those files need to be compatible with LAMMPS source files. When a make fails, there is usually a very simple reason, which you or a local expert will need to fix. Here are two non-obvious errors that can occur: (1) If the make command breaks immediately with errors that indicate it can't find files with a "*" in their names, this can be because your machine's native make doesn't support wildcard expansion in a makefile. Try gmake instead of make. If that doesn't work, try using a -f switch with your make command to use a pre-generated Makefile.list which explicitly lists all the needed files, e.g. make makelist make -f Makefile.list linux gmake -f Makefile.list mac :pre The first "make" command will create a current Makefile.list with all the file names in your src dir. The 2nd "make" command (make or gmake) will use it to build LAMMPS. Note that you should include/exclude any desired optional packages before using the "make makelist" command. (2) If you get an error that says something like 'identifier "atoll" is undefined', then your machine does not support "long long" integers. Try using the -DLAMMPS_LONGLONG_TO_LONG setting described above in Step 4. :line Additional build tips :h5,link(start_2_4) Building LAMMPS for multiple platforms. :h6 You can make LAMMPS for multiple platforms from the same src directory. Each target creates its own object sub-directory called Obj_target where it stores the system-specific *.o files. Cleaning up. :h6 Typing "make clean-all" or "make clean-machine" will delete *.o object files created when LAMMPS is built, for either all builds or for a particular machine. Changing the LAMMPS size limits via -DLAMMPS_SMALLBIG or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL :h6 As explained above, any of these 3 settings can be specified on the LMP_INC line in your low-level src/MAKE/Makefile.foo. The default is -DLAMMPS_SMALLBIG which allows for systems with up to 2^63 atoms and 2^63 timesteps (about 9e18). The atom limit is for atomic systems which do not store bond topology info and thus do not require atom IDs. If you use atom IDs for atomic systems (which is the default) or if you use a molecular model, which stores bond topology info and thus requires atom IDs, the limit is 2^31 atoms (about 2 billion). This is because the IDs are stored in 32-bit integers. Likewise, with this setting, the 3 image flags for each atom (see the "dump"_dump.html doc page for a discussion) are stored in a 32-bit integer, which means the atoms can only wrap around a periodic box (in each dimension) at most 512 times. If atoms move through the periodic box more than this many times, the image flags will "roll over", e.g. from 511 to -512, which can cause diagnostics like the mean-squared displacement, as calculated by the "compute msd"_compute_msd.html command, to be faulty. To allow for larger atomic systems with atom IDs or larger molecular systems or larger image flags, compile with -DLAMMPS_BIGBIG. This stores atom IDs and image flags in 64-bit integers. This enables atomic or molecular systems with atom IDS of up to 2^63 atoms (about 9e18). And image flags will not "roll over" until they reach 2^20 = 1048576. If your system does not support 8-byte integers, you will need to compile with the -DLAMMPS_SMALLSMALL setting. This will restrict the total number of atoms (for atomic or molecular systems) and timesteps to 2^31 (about 2 billion). Image flags will roll over at 2^9 = 512. Note that in src/lmptype.h there are definitions of all these data types as well as the MPI data types associated with them. The MPI types need to be consistent with the associated C data types, or else LAMMPS will generate a run-time error. As far as we know, the settings defined in src/lmptype.h are portable and work on every current system. In all cases, the size of problem that can be run on a per-processor basis is limited by 4-byte integer storage to 2^31 atoms per processor (about 2 billion). This should not normally be a limitation since such a problem would have a huge per-processor memory footprint due to neighbor lists and would run very slowly in terms of CPU secs/timestep. :line Building for a Mac :h5,link(start_2_5) OS X is BSD Unix, so it should just work. See the src/MAKE/MACHINES/Makefile.mac and Makefile.mac_mpi files. :line Building for Windows :h5,link(start_2_6) If you want to build a Windows version of LAMMPS, you can build it yourself, but it may require some effort. LAMMPS expects a Unix-like build environment for the default build procedure. This can be done using either Cygwin or MinGW; the latter also exists as a ready-to-use Linux-to-Windows cross-compiler in several Linux distributions. In these cases, you can do the installation after installing several unix-style commands like make, grep, sed and bash with some shell utilities. For Cygwin and the MinGW cross-compilers, suitable makefiles are provided in src/MAKE/MACHINES. When using other compilers, like Visual C++ or Intel compilers for Windows, you may have to implement your own build system. Since none of the current LAMMPS core developers has significant experience building executables on Windows, we are happy to distribute contributed instructions and modifications, but we cannot provide support for those. With the so-called "Anniversary Update" to Windows 10, there is a Ubuntu subsystem available for Windows, that can be installed and then it can be used to compile/install LAMMPS as if you are running on a Ubuntu Linux system. As an alternative, you can download "daily builds" (and some older versions) of the installer packages from "rpm.lammps.org/windows.html"_http://rpm.lammps.org/windows.html. These executables are built with most optional packages and the download includes documentation, potential files, some tools and many examples, but no source code. :line 2.3 Making LAMMPS with optional packages :h4,link(start_3) This section has the following sub-sections: "Package basics"_#start_3_1 "Including/excluding packages"_#start_3_2 "Packages that require extra libraries"_#start_3_3 "Packages that require Makefile.machine settings"_#start_3_4 :ul Note that the following "Section 2.4"_#start_4 describes the Make.py tool which can be used to install/un-install packages and build the auxiliary libraries which some of them use. It can also auto-edit a Makefile.machine to add settings needed by some packages. :line Package basics: :h5,link(start_3_1) The source code for LAMMPS is structured as a set of core files which are always included, plus optional packages. Packages are groups of files that enable a specific set of features. For example, force fields for molecular systems or granular systems are in packages. "Section packages"_Section_packages.html in the manual has details about all the packages, including specific instructions for building LAMMPS with each package, which are covered in a more general manner below. You can see the list of all packages by typing "make package" from within the src directory of the LAMMPS distribution. This also lists various make commands that can be used to manipulate packages. If you use a command in a LAMMPS input script that is part of a package, you must have built LAMMPS with that package, else you will get an error that the style is invalid or the command is unknown. Every command's doc page specfies if it is part of a package. You can also type lmp_machine -h :pre to run your executable with the optional "-h command-line switch"_#start_7 for "help", which will simply list the styles and commands known to your executable, and immediately exit. There are two kinds of packages in LAMMPS, standard and user packages. More information about the contents of standard and user packages is given in "Section 4"_Section_packages.html of the manual. The difference between standard and user packages is as follows: Standard packages, such as molecule or kspace, are supported by the LAMMPS developers and are written in a syntax and style consistent with the rest of LAMMPS. This means we will answer questions about them, debug and fix them if necessary, and keep them compatible with future changes to LAMMPS. User packages, such as user-atc or user-omp, have been contributed by users, and always begin with the user prefix. If they are a single command (single file), they are typically in the user-misc package. Otherwise, they are a a set of files grouped together which add a specific functionality to the code. User packages don't necessarily meet the requirements of the standard packages. If you have problems using a feature provided in a user package, you may need to contact the contributor directly to get help. Information on how to submit additions you make to LAMMPS as single files or either a standard or user-contributed package are given in "this section"_Section_modify.html#mod_15 of the documentation. :line Including/excluding packages :h5,link(start_3_2) To use (or not use) a package you must include it (or exclude it) before building LAMMPS. From the src directory, this is typically as simple as: make yes-colloid make g++ :pre or make no-manybody make g++ :pre NOTE: You should NOT include/exclude packages and build LAMMPS in a single make command using multiple targets, e.g. make yes-colloid g++. This is because the make procedure creates a list of source files that will be out-of-date for the build if the package configuration changes within the same command. Some packages have individual files that depend on other packages being included. LAMMPS checks for this and does the right thing. I.e. individual files are only included if their dependencies are already included. Likewise, if a package is excluded, other files dependent on that package are also excluded. If you will never run simulations that use the features in a particular packages, there is no reason to include it in your build. For some packages, this will keep you from having to build auxiliary libraries (see below), and will also produce a smaller executable which may run a bit faster. When you download a LAMMPS tarball, these packages are pre-installed in the src directory: KSPACE, MANYBODY,MOLECULE, because they are so commonly used. When you download LAMMPS source files from the SVN or Git repositories, no packages are pre-installed. Packages are included or excluded by typing "make yes-name" or "make no-name", where "name" is the name of the package in lower-case, e.g. name = kspace for the KSPACE package or name = user-atc for the USER-ATC package. You can also type "make yes-standard", "make no-standard", "make yes-std", "make no-std", "make yes-user", "make no-user", "make yes-lib", "make no-lib", "make yes-all", or "make no-all" to include/exclude various sets of packages. Type "make package" to see all of the package-related make options. NOTE: Inclusion/exclusion of a package works by simply moving files back and forth between the main src directory and sub-directories with the package name (e.g. src/KSPACE, src/USER-ATC), so that the files are seen or not seen when LAMMPS is built. After you have included or excluded a package, you must re-build LAMMPS. Additional package-related make options exist to help manage LAMMPS files that exist in both the src directory and in package sub-directories. You do not normally need to use these commands unless you are editing LAMMPS files or have downloaded a patch from the LAMMPS WWW site. Typing "make package-update" or "make pu" will overwrite src files with files from the package sub-directories if the package has been included. It should be used after a patch is installed, since patches only update the files in the package sub-directory, but not the src files. Typing "make package-overwrite" will overwrite files in the package sub-directories with src files. Typing "make package-status" or "make ps" will show which packages are currently included. For those that are included, it will list any files that are different in the src directory and package sub-directory. Typing "make package-diff" lists all differences between these files. Again, type "make package" to see all of the package-related make options. :line Packages that require extra libraries :h5,link(start_3_3) A few of the standard and user packages require additional auxiliary libraries. Many of them are provided with LAMMPS, in which case they must be compiled first, before LAMMPS is built, if you wish to include that package. If you get a LAMMPS build error about a missing library, this is likely the reason. See the "Section 4"_Section_packages.html doc page for a list of packages that have these kinds of auxiliary libraries. The lib directory in the distribution has sub-directories with package names that correspond to the needed auxiliary libs, e.g. lib/gpu. Each sub-directory has a README file that gives more details. Code for most of the auxiliary libraries is included in that directory. Examples are the USER-ATC and MEAM packages. A few of the lib sub-directories do not include code, but do include instructions (and sometimes scripts) that automate the process of downloading the auxiliary library and installing it so LAMMPS can link to it. Examples are the KIM, VORONOI, USER-MOLFILE, and USER-SMD packages. The lib/python directory (for the PYTHON package) contains only a choice of Makefile.lammps.* files. This is because no auxiliary code or libraries are needed, only the Python library and other system libs that should already available on your system. However, the Makefile.lammps file is needed to tell LAMMPS which libs to use and where to find them. For libraries with provided code, the sub-directory README file (e.g. lib/atc/README) has instructions on how to build that library. This information is also summarized in "Section packages"_Section_packages.html. Typically this is done by typing something like: make -f Makefile.g++ :pre If one of the provided Makefiles is not appropriate for your system you will need to edit or add one. Note that all the Makefiles have a setting for EXTRAMAKE at the top that specifies a Makefile.lammps.* file. If the library build is successful, it will produce 2 files in the lib directory: libpackage.a Makefile.lammps :pre The Makefile.lammps file will typically be a copy of one of the Makefile.lammps.* files in the library directory. Note that you must insure that the settings in Makefile.lammps are appropriate for your system. If they are not, the LAMMPS build may fail. To fix this, you can edit or create a new Makefile.lammps.* file for your system, and copy it to Makefile.lammps. As explained in the lib/package/README files, the settings in Makefile.lammps are used to specify additional system libraries and their locations so that LAMMPS can build with the auxiliary library. For example, if the MEAM package is used, the auxiliary library consists of F90 code, built with a Fortran complier. To link that library with LAMMPS (a C++ code) via whatever C++ compiler LAMMPS is built with, typically requires additional Fortran-to-C libraries be included in the link. Another example are the BLAS and LAPACK libraries needed to use the USER-ATC or USER-AWPMD packages. For libraries without provided code, the sub-directory README file has information on where to download the library and how to build it, e.g. lib/voronoi/README and lib/smd/README. The README files also describe how you must either (a) create soft links, via the "ln" command, in those directories to point to where you built or installed the packages, or (b) check or edit the Makefile.lammps file in the same directory to provide that information. Some of the sub-directories, e.g. lib/voronoi, also have an install.py script which can be used to automate the process of downloading/building/installing the auxiliary library, and setting the needed soft links. Type "python install.py" for further instructions. As with the sub-directories containing library code, if the soft links or settings in the lib/package/Makefile.lammps files are not correct, the LAMMPS build will typically fail. :line Packages that require Makefile.machine settings :h5,link(start_3_4) A few packages require specific settings in Makefile.machine, to either build or use the package effectively. These are the USER-INTEL, KOKKOS, USER-OMP, and OPT packages, used for accelerating code performance on CPUs or other hardware, as discussed in "Section acclerate"_Section_accelerate.html. A summary of what Makefile.machine changes are needed for each of these packages is given in "Section packages"_Section_packages.html. The details are given on the doc pages that describe each of these accelerator packages in detail: "USER-INTEL package"_accelerate_intel.html "KOKKOS package"_accelerate_kokkos.html "USER-OMP package"_accelerate_omp.html "OPT package"_accelerate_opt.html :ul You can also look at the following machine Makefiles in src/MAKE/OPTIONS, which include the changes. Note that the USER-INTEL and KOKKOS packages allow for settings that build LAMMPS for different hardware. The USER-INTEL package builds for CPU and the Xeon Phi, the KOKKOS package builds for OpenMP, GPUs (Cuda), and the Xeon Phi. Makefile.intel_cpu Makefile.intel_phi Makefile.kokkos_omp Makefile.kokkos_cuda Makefile.kokkos_phi Makefile.omp Makefile.opt :ul Also note that the Make.py tool, described in the next "Section 2.4"_#start_4 can automatically add the needed info to an existing machine Makefile, using simple command-line arguments. :line 2.4 Building LAMMPS via the Make.py tool :h4,link(start_4) The src directory includes a Make.py script, written in Python, which can be used to automate various steps of the build process. It is particularly useful for working with the accelerator packages, as well as other packages which require auxiliary libraries to be built. The goal of the Make.py tool is to allow any complex multi-step LAMMPS build to be performed as a single Make.py command. And you can archive the commands, so they can be re-invoked later via the -r (redo) switch. If you find some LAMMPS build procedure that can't be done in a single Make.py command, let the developers know, and we'll see if we can augment the tool. You can run Make.py from the src directory by typing either: Make.py -h python Make.py -h :pre which will give you help info about the tool. For the former to work, you may need to edit the first line of Make.py to point to your local Python. And you may need to insure the script is executable: chmod +x Make.py :pre Here are examples of build tasks you can perform with Make.py: Install/uninstall packages: Make.py -p no-lib kokkos omp intel Build specific auxiliary libs: Make.py -a lib-atc lib-meam Build libs for all installed packages: Make.py -p cuda gpu -gpu mode=double arch=31 -a lib-all Create a Makefile from scratch with compiler and MPI settings: Make.py -m none -cc g++ -mpi mpich -a file Augment Makefile.serial with settings for installed packages: Make.py -p intel -intel cpu -m serial -a file Add JPG and FFTW support to Makefile.mpi: Make.py -m mpi -jpg -fft fftw -a file Build LAMMPS with a parallel make using Makefile.mpi: Make.py -j 16 -m mpi -a exe Build LAMMPS and libs it needs using Makefile.serial with accelerator settings: Make.py -p gpu intel -intel cpu -a lib-all file serial :tb(s=:) The bench and examples directories give Make.py commands that can be used to build LAMMPS with the various packages and options needed to run all the benchmark and example input scripts. See these files for more details: bench/README bench/FERMI/README bench/KEPLER/README bench/PHI/README examples/README examples/accelerate/README examples/accelerate/make.list :ul All of the Make.py options and syntax help can be accessed by using the "-h" switch. E.g. typing "Make.py -h" gives Syntax: Make.py switch args ... switches can be listed in any order help switch: -h prints help and syntax for all other specified switches switch for actions: -a lib-all, lib-dir, clean, file, exe or machine list one or more actions, in any order machine is a Makefile.machine suffix, must be last if used one-letter switches: -d (dir), -j (jmake), -m (makefile), -o (output), -p (packages), -r (redo), -s (settings), -v (verbose) switches for libs: -atc, -awpmd, -colvars, -cuda -gpu, -meam, -poems, -qmmm, -reax switches for build and makefile options: -intel, -kokkos, -cc, -mpi, -fft, -jpg, -png :pre Using the "-h" switch with other switches and actions gives additional info on all the other specified switches or actions. The "-h" can be anywhere in the command-line and the other switches do not need their arguments. E.g. type "Make.py -h -d -atc -intel" will print: -d dir dir = LAMMPS home dir if -d not specified, working dir must be lammps/src :pre -atc make=suffix lammps=suffix2 all args are optional and can be in any order make = use Makefile.suffix (def = g++) lammps = use Makefile.lammps.suffix2 (def = EXTRAMAKE in makefile) :pre -intel mode mode = cpu or phi (def = cpu) build Intel package for CPU or Xeon Phi :pre Note that Make.py never overwrites an existing Makefile.machine. Instead, it creates src/MAKE/MINE/Makefile.auto, which you can save or rename if desired. Likewise it creates an executable named src/lmp_auto, which you can rename using the -o switch if desired. The most recently executed Make.py commmand is saved in src/Make.py.last. You can use the "-r" switch (for redo) to re-invoke the last command, or you can save a sequence of one or more Make.py commands to a file and invoke the file of commands using "-r". You can also label the commands in the file and invoke one or more of them by name. A typical use of Make.py is to start with a valid Makefile.machine for your system, that works for a vanilla LAMMPS build, i.e. when optional packages are not installed. You can then use Make.py to add various settings (FFT, JPG, PNG) to the Makefile.machine as well as change its compiler and MPI options. You can also add additional packages to the build, as well as build the needed supporting libraries. You can also use Make.py to create a new Makefile.machine from scratch, using the "-m none" switch, if you also specify what compiler and MPI options to use, via the "-cc" and "-mpi" switches. :line 2.5 Building LAMMPS as a library :h4,link(start_5) LAMMPS can be built as either a static or shared library, which can then be called from another application or a scripting language. See "this section"_Section_howto.html#howto_10 for more info on coupling LAMMPS to other codes. See "this section"_Section_python.html for more info on wrapping and running LAMMPS from Python. Static library :h5 To build LAMMPS as a static library (*.a file on Linux), type make foo mode=lib :pre where foo is the machine name. This kind of library is typically used to statically link a driver application to LAMMPS, so that you can insure all dependencies are satisfied at compile time. This will use the ARCHIVE and ARFLAGS settings in src/MAKE/Makefile.foo. The build will create the file liblammps_foo.a which another application can link to. It will also create a soft link liblammps.a, which will point to the most recently built static library. Shared library :h5 To build LAMMPS as a shared library (*.so file on Linux), which can be dynamically loaded, e.g. from Python, type make foo mode=shlib :pre where foo is the machine name. This kind of library is required when wrapping LAMMPS with Python; see "Section 11"_Section_python.html for details. This will use the SHFLAGS and SHLIBFLAGS settings in src/MAKE/Makefile.foo and perform the build in the directory Obj_shared_foo. This is so that each file can be compiled with the -fPIC flag which is required for inclusion in a shared library. The build will create the file liblammps_foo.so which another application can link to dyamically. It will also create a soft link liblammps.so, which will point to the most recently built shared library. This is the file the Python wrapper loads by default. Note that for a shared library to be usable by a calling program, all the auxiliary libraries it depends on must also exist as shared libraries. This will be the case for libraries included with LAMMPS, such as the dummy MPI library in src/STUBS or any package libraries in lib/packages, since they are always built as shared libraries using the -fPIC switch. However, if a library like MPI or FFTW does not exist as a shared library, the shared library build will generate an error. This means you will need to install a shared library version of the auxiliary library. The build instructions for the library should tell you how to do this. Here is an example of such errors when the system FFTW or provided lib/colvars library have not been built as shared libraries: /usr/bin/ld: /usr/local/lib/libfftw3.a(mapflags.o): relocation R_X86_64_32 against '.rodata' can not be used when making a shared object; recompile with -fPIC /usr/local/lib/libfftw3.a: could not read symbols: Bad value :pre /usr/bin/ld: ../../lib/colvars/libcolvars.a(colvarmodule.o): relocation R_X86_64_32 against '__pthread_key_create' can not be used when making a shared object; recompile with -fPIC ../../lib/colvars/libcolvars.a: error adding symbols: Bad value :pre As an example, here is how to build and install the "MPICH library"_mpich, a popular open-source version of MPI, distributed by Argonne National Labs, as a shared library in the default /usr/local/lib location: :link(mpich,http://www-unix.mcs.anl.gov/mpi) ./configure --enable-shared make make install :pre You may need to use "sudo make install" in place of the last line if you do not have write privileges for /usr/local/lib. The end result should be the file /usr/local/lib/libmpich.so. [Additional requirement for using a shared library:] :h5 The operating system finds shared libraries to load at run-time using the environment variable LD_LIBRARY_PATH. So you may wish to copy the file src/liblammps.so or src/liblammps_g++.so (for example) to a place the system can find it by default, such as /usr/local/lib, or you may wish to add the LAMMPS src directory to LD_LIBRARY_PATH, so that the current version of the shared library is always available to programs that use it. For the csh or tcsh shells, you would add something like this to your ~/.cshrc file: setenv LD_LIBRARY_PATH $\{LD_LIBRARY_PATH\}:/home/sjplimp/lammps/src :pre Calling the LAMMPS library :h5 Either flavor of library (static or shared) allows one or more LAMMPS objects to be instantiated from the calling program. When used from a C++ program, all of LAMMPS is wrapped in a LAMMPS_NS namespace; you can safely use any of its classes and methods from within the calling code, as needed. When used from a C or Fortran program or a scripting language like Python, the library has a simple function-style interface, provided in src/library.cpp and src/library.h. See the sample codes in examples/COUPLE/simple for examples of C++ and C and Fortran codes that invoke LAMMPS thru its library interface. There are other examples as well in the COUPLE directory which are discussed in "Section 6.10"_Section_howto.html#howto_10 of the manual. See "Section 11"_Section_python.html of the manual for a description of the Python wrapper provided with LAMMPS that operates through the LAMMPS library interface. The files src/library.cpp and library.h define the C-style API for -using LAMMPS as a library. See "Section_howto -19"_Section_howto.html#howto_19 of the manual for a description of the +using LAMMPS as a library. See "Section +6.19"_Section_howto.html#howto_19 of the manual for a description of the interface and how to extend it for your needs. :line 2.6 Running LAMMPS :h4,link(start_6) By default, LAMMPS runs by reading commands from standard input. Thus if you run the LAMMPS executable by itself, e.g. lmp_linux :pre it will simply wait, expecting commands from the keyboard. Typically you should put commands in an input script and use I/O redirection, e.g. lmp_linux < in.file :pre For parallel environments this should also work. If it does not, use the '-in' command-line switch, e.g. lmp_linux -in in.file :pre "This section"_Section_commands.html describes how input scripts are structured and what commands they contain. You can test LAMMPS on any of the sample inputs provided in the examples or bench directory. Input scripts are named in.* and sample outputs are named log.*.name.P where name is a machine and P is the number of processors it was run on. Here is how you might run a standard Lennard-Jones benchmark on a Linux box, using mpirun to launch a parallel job: cd src make linux cp lmp_linux ../bench cd ../bench mpirun -np 4 lmp_linux -in in.lj :pre See "this page"_bench for timings for this and the other benchmarks on various platforms. Note that some of the example scripts require LAMMPS to be built with one or more of its optional packages. :link(bench,http://lammps.sandia.gov/bench.html) :line On a Windows box, you can skip making LAMMPS and simply download an installer package from "here"_http://rpm.lammps.org/windows.html For running the non-MPI executable, follow these steps: Get a command prompt by going to Start->Run... , then typing "cmd". :ulb,l Move to the directory where you have your input, e.g. a copy of the [in.lj] input from the bench folder. (e.g. by typing: cd "Documents"). :l At the command prompt, type "lmp_serial -in in.lj", replacing [in.lj] with the name of your LAMMPS input script. :l :ule For the MPI version, which allows you to run LAMMPS under Windows on multiple processors, follow these steps: Download and install "MPICH2"_http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads for Windows. :ulb,l The LAMMPS Windows installer packages will automatically adjust your path for the default location of this MPI package. After the installation of the MPICH software, it needs to be integrated into the system. For this you need to start a Command Prompt in {Administrator Mode} (right click on the icon and select it). Change into the MPICH2 installation directory, then into the subdirectory [bin] and execute [smpd.exe -install]. Exit the command window. Get a new, regular command prompt by going to Start->Run... , then typing "cmd". :l Move to the directory where you have your input file (e.g. by typing: cd "Documents"). :l Then type something like this: mpiexec -localonly 4 lmp_mpi -in in.lj :pre or mpiexec -np 4 lmp_mpi -in in.lj :pre replacing in.lj with the name of your LAMMPS input script. For the latter case, you may be prompted to enter your password. :l In this mode, output may not immediately show up on the screen, so if your input script takes a long time to execute, you may need to be patient before the output shows up. :l The parallel executable can also run on a single processor by typing something like: lmp_mpi -in in.lj :pre :ule :line The screen output from LAMMPS is described in a section below. As it runs, LAMMPS also writes a log.lammps file with the same information. Note that this sequence of commands copies the LAMMPS executable (lmp_linux) to the directory with the input files. This may not be necessary, but some versions of MPI reset the working directory to where the executable is, rather than leave it as the directory where you launch mpirun from (if you launch lmp_linux on its own and not under mpirun). If that happens, LAMMPS will look for additional input files and write its output files to the executable directory, rather than your working directory, which is probably not what you want. If LAMMPS encounters errors in the input script or while running a simulation it will print an ERROR message and stop or a WARNING message and continue. See "Section 12"_Section_errors.html for a discussion of the various kinds of errors LAMMPS can or can't detect, a list of all ERROR and WARNING messages, and what to do about them. LAMMPS can run a problem on any number of processors, including a single processor. In theory you should get identical answers on any number of processors and on any machine. In practice, numerical round-off can cause slight differences and eventual divergence of molecular dynamics phase space trajectories. LAMMPS can run as large a problem as will fit in the physical memory of one or more processors. If you run out of memory, you must run on more processors or setup a smaller problem. :line 2.7 Command-line options :h4,link(start_7) At run time, LAMMPS recognizes several optional command-line switches which may be used in any order. Either the full word or a one-or-two letter abbreviation can be used: -e or -echo -h or -help -i or -in -k or -kokkos -l or -log -nc or -nocite -pk or -package -p or -partition -pl or -plog -ps or -pscreen -r or -restart -ro or -reorder -sc or -screen -sf or -suffix -v or -var :ul For example, lmp_ibm might be launched as follows: mpirun -np 16 lmp_ibm -v f tmp.out -l my.log -sc none -in in.alloy mpirun -np 16 lmp_ibm -var f tmp.out -log my.log -screen none -in in.alloy :pre Here are the details on the options: -echo style :pre Set the style of command echoing. The style can be {none} or {screen} or {log} or {both}. Depending on the style, each command read from the input script will be echoed to the screen and/or logfile. This can be useful to figure out which line of your script is causing an input error. The default value is {log}. The echo style can also be set by using the "echo"_echo.html command in the input script itself. -help :pre Print a brief help summary and a list of options compiled into this executable for each LAMMPS style (atom_style, fix, compute, pair_style, bond_style, etc). This can tell you if the command you want to use was included via the appropriate package at compile time. LAMMPS will print the info and immediately exit if this switch is used. -in file :pre Specify a file to use as an input script. This is an optional switch when running LAMMPS in one-partition mode. If it is not specified, LAMMPS reads its script from standard input, typically from a script via I/O redirection; e.g. lmp_linux < in.run. I/O redirection should also work in parallel, but if it does not (in the unlikely case that an MPI implementation does not support it), then use the -in flag. Note that this is a required switch when running LAMMPS in multi-partition mode, since multiple processors cannot all read from stdin. -kokkos on/off keyword/value ... :pre Explicitly enable or disable KOKKOS support, as provided by the KOKKOS package. Even if LAMMPS is built with this package, as described above in "Section 2.3"_#start_3, this switch must be set to enable running with the KOKKOS-enabled styles the package provides. If the switch is not set (the default), LAMMPS will operate as if the KOKKOS package were not installed; i.e. you can run standard LAMMPS or with the GPU or USER-OMP packages, for testing or benchmarking purposes. Additional optional keyword/value pairs can be specified which determine how Kokkos will use the underlying hardware on your platform. These settings apply to each MPI task you launch via the "mpirun" or "mpiexec" command. You may choose to run one or more MPI tasks per physical node. Note that if you are running on a desktop machine, you typically have one physical node. On a cluster or supercomputer there may be dozens or 1000s of physical nodes. Either the full word or an abbreviation can be used for the keywords. Note that the keywords do not use a leading minus sign. I.e. the keyword is "t", not "-t". Also note that each of the keywords has a default setting. Example of when to use these options and what settings to use on different platforms is given in "Section 5.8"_Section_accelerate.html#acc_3. d or device g or gpus t or threads n or numa :ul device Nd :pre This option is only relevant if you built LAMMPS with CUDA=yes, you have more than one GPU per node, and if you are running with only one MPI task per node. The Nd setting is the ID of the GPU on the node to run on. By default Nd = 0. If you have multiple GPUs per node, they have consecutive IDs numbered as 0,1,2,etc. This setting allows you to launch multiple independent jobs on the node, each with a single MPI task per node, and assign each job to run on a different GPU. gpus Ng Ns :pre This option is only relevant if you built LAMMPS with CUDA=yes, you have more than one GPU per node, and you are running with multiple MPI tasks per node (up to one per GPU). The Ng setting is how many GPUs you will use. The Ns setting is optional. If set, it is the ID of a GPU to skip when assigning MPI tasks to GPUs. This may be useful if your desktop system reserves one GPU to drive the screen and the rest are intended for computational work like running LAMMPS. By default Ng = 1 and Ns is not set. Depending on which flavor of MPI you are running, LAMMPS will look for one of these 3 environment variables SLURM_LOCALID (various MPI variants compiled with SLURM support) MV2_COMM_WORLD_LOCAL_RANK (Mvapich) OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI) :pre which are initialized by the "srun", "mpirun" or "mpiexec" commands. The environment variable setting for each MPI rank is used to assign a unique GPU ID to the MPI task. threads Nt :pre This option assigns Nt number of threads to each MPI task for performing work when Kokkos is executing in OpenMP or pthreads mode. The default is Nt = 1, which essentially runs in MPI-only mode. If there are Np MPI tasks per physical node, you generally want Np*Nt = the number of physical cores per node, to use your available hardware optimally. This also sets the number of threads used by the host when LAMMPS is compiled with CUDA=yes. numa Nm :pre This option is only relevant when using pthreads with hwloc support. In this case Nm defines the number of NUMA regions (typicaly sockets) on a node which will be utilizied by a single MPI rank. By default Nm = 1. If this option is used the total number of worker-threads per MPI rank is threads*numa. Currently it is always almost better to assign at least one MPI rank per NUMA region, and leave numa set to its default value of 1. This is because letting a single process span multiple NUMA regions induces a significant amount of cross NUMA data traffic which is slow. -log file :pre Specify a log file for LAMMPS to write status information to. In one-partition mode, if the switch is not used, LAMMPS writes to the file log.lammps. If this switch is used, LAMMPS writes to the specified file. In multi-partition mode, if the switch is not used, a log.lammps file is created with hi-level status information. Each partition also writes to a log.lammps.N file where N is the partition ID. If the switch is specified in multi-partition mode, the hi-level logfile is named "file" and each partition also logs information to a file.N. For both one-partition and multi-partition mode, if the specified file is "none", then no log files are created. Using a "log"_log.html command in the input script will override this setting. Option -plog will override the name of the partition log files file.N. -nocite :pre Disable writing the log.cite file which is normally written to list references for specific cite-able features used during a LAMMPS run. See the "citation page"_http://lammps.sandia.gov/cite.html for more details. -package style args .... :pre Invoke the "package"_package.html command with style and args. The syntax is the same as if the command appeared at the top of the input script. For example "-package gpu 2" or "-pk gpu 2" is the same as "package gpu 2"_package.html in the input script. The possible styles and args are documented on the "package"_package.html doc page. This switch can be used multiple times, e.g. to set options for the USER-INTEL and USER-OMP packages which can be used together. Along with the "-suffix" command-line switch, this is a convenient mechanism for invoking accelerator packages and their options without having to edit an input script. -partition 8x2 4 5 ... :pre Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P processors and this switch is not used, LAMMPS runs in one partition, i.e. all P processors run a single simulation. If this switch is used, the P processors are split into separate partitions and each partition runs its own simulation. The arguments to the switch specify the number of processors in each partition. Arguments of the form MxN mean M partitions, each with N processors. Arguments of the form N mean a single partition with N processors. The sum of processors in all partitions must equal P. Thus the command "-partition 8x2 4 5" has 10 partitions and runs on a total of 25 processors. Running with multiple partitions can e useful for running "multi-replica simulations"_Section_howto.html#howto_5, where each replica runs on on one or a few processors. Note that with MPI installed on a machine (e.g. your desktop), you can run on more (virtual) processors than you have physical processors. To run multiple independent simulatoins from one input script, using multiple partitions, see "Section 6.4"_Section_howto.html#howto_4 of the manual. World- and universe-style "variables"_variable.html are useful in this context. -plog file :pre Specify the base name for the partition log files, so partition N writes log information to file.N. If file is none, then no partition log files are created. This overrides the filename specified in the -log command-line option. This option is useful when working with large numbers of partitions, allowing the partition log files to be suppressed (-plog none) or placed in a sub-directory (-plog replica_files/log.lammps) If this option is not used the log file for partition N is log.lammps.N or whatever is specified by the -log command-line option. -pscreen file :pre Specify the base name for the partition screen file, so partition N writes screen information to file.N. If file is none, then no partition screen files are created. This overrides the filename specified in the -screen command-line option. This option is useful when working with large numbers of partitions, allowing the partition screen files to be suppressed (-pscreen none) or placed in a sub-directory (-pscreen replica_files/screen). If this option is not used the screen file for partition N is screen.N or whatever is specified by the -screen command-line option. -restart restartfile {remap} datafile keyword value ... :pre Convert the restart file into a data file and immediately exit. This is the same operation as if the following 2-line input script were run: read_restart restartfile {remap} write_data datafile keyword value ... :pre Note that the specified restartfile and datafile can have wild-card characters ("*",%") as described by the "read_restart"_read_restart.html and "write_data"_write_data.html commands. But a filename such as file.* will need to be enclosed in quotes to avoid shell expansion of the "*" character. Note that following restartfile, the optional flag {remap} can be used. This has the same effect as adding it to the "read_restart"_read_restart.html command, as explained on its doc page. This is only useful if the reading of the restart file triggers an error that atoms have been lost. In that case, use of the remap flag should allow the data file to still be produced. Also note that following datafile, the same optional keyword/value pairs can be listed as used by the "write_data"_write_data.html command. -reorder nth N -reorder custom filename :pre Reorder the processors in the MPI communicator used to instantiate LAMMPS, in one of several ways. The original MPI communicator ranks all P processors from 0 to P-1. The mapping of these ranks to physical processors is done by MPI before LAMMPS begins. It may be useful in some cases to alter the rank order. E.g. to insure that cores within each node are ranked in a desired order. Or when using the "run_style verlet/split"_run_style.html command with 2 partitions to insure that a specific Kspace processor (in the 2nd partition) is matched up with a specific set of processors in the 1st partition. See the "Section 5"_Section_accelerate.html doc pages for more details. If the keyword {nth} is used with a setting {N}, then it means every Nth processor will be moved to the end of the ranking. This is useful when using the "run_style verlet/split"_run_style.html command with 2 partitions via the -partition command-line switch. The first set of processors will be in the first partition, the 2nd set in the 2nd partition. The -reorder command-line switch can alter this so that the 1st N procs in the 1st partition and one proc in the 2nd partition will be ordered consecutively, e.g. as the cores on one physical node. This can boost performance. For example, if you use "-reorder nth 4" and "-partition 9 3" and you are running on 12 processors, the processors will be reordered from 0 1 2 3 4 5 6 7 8 9 10 11 :pre to 0 1 2 4 5 6 8 9 10 3 7 11 :pre so that the processors in each partition will be 0 1 2 4 5 6 8 9 10 3 7 11 :pre See the "processors" command for how to insure processors from each partition could then be grouped optimally for quad-core nodes. If the keyword is {custom}, then a file that specifies a permutation of the processor ranks is also specified. The format of the reorder file is as follows. Any number of initial blank or comment lines (starting with a "#" character) can be present. These should be followed by P lines of the form: I J :pre where P is the number of processors LAMMPS was launched with. Note that if running in multi-partition mode (see the -partition switch above) P is the total number of processors in all partitions. The I and J values describe a permutation of the P processors. Every I and J should be values from 0 to P-1 inclusive. In the set of P I values, every proc ID should appear exactly once. Ditto for the set of P J values. A single I,J pairing means that the physical processor with rank I in the original MPI communicator will have rank J in the reordered communicator. Note that rank ordering can also be specified by many MPI implementations, either by environment variables that specify how to order physical processors, or by config files that specify what physical processors to assign to each MPI rank. The -reorder switch simply gives you a portable way to do this without relying on MPI itself. See the "processors out"_processors command for how to output info on the final assignment of physical processors to the LAMMPS simulation domain. -screen file :pre Specify a file for LAMMPS to write its screen information to. In one-partition mode, if the switch is not used, LAMMPS writes to the screen. If this switch is used, LAMMPS writes to the specified file instead and you will see no screen output. In multi-partition mode, if the switch is not used, hi-level status information is written to the screen. Each partition also writes to a screen.N file where N is the partition ID. If the switch is specified in multi-partition mode, the hi-level screen dump is named "file" and each partition also writes screen information to a file.N. For both one-partition and multi-partition mode, if the specified file is "none", then no screen output is performed. Option -pscreen will override the name of the partition screen files file.N. -suffix style args :pre Use variants of various styles if they exist. The specified style can be {cuda}, {gpu}, {intel}, {kk}, {omp}, {opt}, or {hybrid}. These refer to optional packages that LAMMPS can be built with, as described above in "Section 2.3"_#start_3. The "gpu" style corresponds to the GPU package, the "intel" style to the USER-INTEL package, the "kk" style to the KOKKOS package, the "opt" style to the OPT package, and the "omp" style to the USER-OMP package. The hybrid style is the only style that accepts arguments. It allows for two packages to be specified. The first package specified is the default and will be used if it is available. If no style is available for the first package, the style for the second package will be used if available. For example, "-suffix hybrid intel omp" will use styles from the USER-INTEL package if they are installed and available, but styles for the USER-OMP package otherwise. Along with the "-package" command-line switch, this is a convenient mechanism for invoking accelerator packages and their options without having to edit an input script. As an example, all of the packages provide a "pair_style lj/cut"_pair_lj.html variant, with style names lj/cut/gpu, lj/cut/intel, lj/cut/kk, lj/cut/omp, and lj/cut/opt. A variant style can be specified explicitly in your input script, e.g. pair_style lj/cut/gpu. If the -suffix switch is used the specified suffix (gpu,intel,kk,omp,opt) is automatically appended whenever your input script command creates a new "atom"_atom_style.html, "pair"_pair_style.html, "fix"_fix.html, "compute"_compute.html, or "run"_run_style.html style. If the variant version does not exist, the standard version is created. For the GPU package, using this command-line switch also invokes the default GPU settings, as if the command "package gpu 1" were used at the top of your input script. These settings can be changed by using the "-package gpu" command-line switch or the "package gpu"_package.html command in your script. For the USER-INTEL package, using this command-line switch also invokes the default USER-INTEL settings, as if the command "package intel 1" were used at the top of your input script. These settings can be changed by using the "-package intel" command-line switch or the "package intel"_package.html command in your script. If the USER-OMP package is also installed, the hybrid style with "intel omp" arguments can be used to make the omp suffix a second choice, if a requested style is not available in the USER-INTEL package. It will also invoke the default USER-OMP settings, as if the command "package omp 0" were used at the top of your input script. These settings can be changed by using the "-package omp" command-line switch or the "package omp"_package.html command in your script. For the KOKKOS package, using this command-line switch also invokes the default KOKKOS settings, as if the command "package kokkos" were used at the top of your input script. These settings can be changed by using the "-package kokkos" command-line switch or the "package kokkos"_package.html command in your script. For the OMP package, using this command-line switch also invokes the default OMP settings, as if the command "package omp 0" were used at the top of your input script. These settings can be changed by using the "-package omp" command-line switch or the "package omp"_package.html command in your script. The "suffix"_suffix.html command can also be used within an input script to set a suffix, or to turn off or back on any suffix setting made via the command line. -var name value1 value2 ... :pre Specify a variable that will be defined for substitution purposes when the input script is read. This switch can be used multiple times to define multiple variables. "Name" is the variable name which can be a single character (referenced as $x in the input script) or a full string (referenced as $\{abc\}). An "index-style variable"_variable.html will be created and populated with the subsequent values, e.g. a set of filenames. Using this command-line option is equivalent to putting the line "variable name index value1 value2 ..." at the beginning of the input script. Defining an index variable as a command-line argument overrides any setting for the same index variable in the input script, since index variables cannot be re-defined. See the "variable"_variable.html command for more info on defining index and other kinds of variables and "this section"_Section_commands.html#cmd_2 for more info on using variables in input scripts. NOTE: Currently, the command-line parser looks for arguments that start with "-" to indicate new switches. Thus you cannot specify multiple variable values if any of they start with a "-", e.g. a negative numeric value. It is OK if the first value1 starts with a "-", since it is automatically skipped. :line 2.8 LAMMPS screen output :h4,link(start_8) As LAMMPS reads an input script, it prints information to both the screen and a log file about significant actions it takes to setup a simulation. When the simulation is ready to begin, LAMMPS performs various initializations and prints the amount of memory (in MBytes per processor) that the simulation requires. It also prints details of the initial thermodynamic state of the system. During the run itself, thermodynamic information is printed periodically, every few timesteps. When the run concludes, LAMMPS prints the final thermodynamic state and a total run time for the simulation. It then appends statistics about the CPU time and storage requirements for the simulation. An example set of statistics is shown here: Loop time of 2.81192 on 4 procs for 300 steps with 2004 atoms Performance: 18.436 ns/day 1.302 hours/ns 106.689 timesteps/s 97.0% CPU use with 4 MPI tasks x no OpenMP threads :pre MPI task timings breakdown: Section | min time | avg time | max time |%varavg| %total --------------------------------------------------------------- Pair | 1.9808 | 2.0134 | 2.0318 | 1.4 | 71.60 Bond | 0.0021894 | 0.0060319 | 0.010058 | 4.7 | 0.21 Kspace | 0.3207 | 0.3366 | 0.36616 | 3.1 | 11.97 Neigh | 0.28411 | 0.28464 | 0.28516 | 0.1 | 10.12 Comm | 0.075732 | 0.077018 | 0.07883 | 0.4 | 2.74 Output | 0.00030518 | 0.00042665 | 0.00078821 | 1.0 | 0.02 Modify | 0.086606 | 0.086631 | 0.086668 | 0.0 | 3.08 Other | | 0.007178 | | | 0.26 :pre Nlocal: 501 ave 508 max 490 min Histogram: 1 0 0 0 0 0 1 1 0 1 Nghost: 6586.25 ave 6628 max 6548 min Histogram: 1 0 1 0 0 0 1 0 0 1 Neighs: 177007 ave 180562 max 170212 min Histogram: 1 0 0 0 0 0 0 1 1 1 :pre Total # of neighbors = 708028 Ave neighs/atom = 353.307 Ave special neighs/atom = 2.34032 Neighbor list builds = 26 Dangerous builds = 0 :pre The first section provides a global loop timing summary. The loop time is the total wall time for the section. The {Performance} line is provided for convenience to help predicting the number of loop continuations required and for comparing performance with other similar MD codes. The CPU use line provides the CPU utilzation per MPI task; it should be close to 100% times the number of OpenMP threads (or 1). Lower numbers correspond to delays due to file I/O or insufficient thread utilization. The MPI task section gives the breakdown of the CPU run time (in seconds) into major categories: {Pair} stands for all non-bonded force computation {Bond} stands for bonded interactions: bonds, angles, dihedrals, impropers {Kspace} stands for reciprocal space interactions: Ewald, PPPM, MSM {Neigh} stands for neighbor list construction {Comm} stands for communicating atoms and their properties {Output} stands for writing dumps and thermo output {Modify} stands for fixes and computes called by them {Other} is the remaining time :ul For each category, there is a breakdown of the least, average and most amount of wall time a processor spent on this section. Also you have the variation from the average time. Together these numbers allow to gauge the amount of load imbalance in this segment of the calculation. Ideally the difference between minimum, maximum and average is small and thus the variation from the average close to zero. The final column shows the percentage of the total loop time is spent in this section. When using the "timer full"_timer.html setting, an additional column is present that also prints the CPU utilization in percent. In addition, when using {timer full} and the "package omp"_package.html command are active, a similar timing summary of time spent in threaded regions to monitor thread utilization and load balance is provided. A new entry is the {Reduce} section, which lists the time spend in reducing the per-thread data elements to the storage for non-threaded computation. These thread timings are taking from the first MPI rank only and and thus, as the breakdown for MPI tasks can change from MPI rank to MPI rank, this breakdown can be very different for individual ranks. Here is an example output for this section: Thread timings breakdown (MPI rank 0): Total threaded time 0.6846 / 90.6% Section | min time | avg time | max time |%varavg| %total --------------------------------------------------------------- Pair | 0.5127 | 0.5147 | 0.5167 | 0.3 | 75.18 Bond | 0.0043139 | 0.0046779 | 0.0050418 | 0.5 | 0.68 Kspace | 0.070572 | 0.074541 | 0.07851 | 1.5 | 10.89 Neigh | 0.084778 | 0.086969 | 0.089161 | 0.7 | 12.70 Reduce | 0.0036485 | 0.003737 | 0.0038254 | 0.1 | 0.55 :pre The third section lists the number of owned atoms (Nlocal), ghost atoms (Nghost), and pair-wise neighbors stored per processor. The max and min values give the spread of these values across processors with a 10-bin histogram showing the distribution. The total number of histogram counts is equal to the number of processors. The last section gives aggregate statistics for pair-wise neighbors and special neighbors that LAMMPS keeps track of (see the "special_bonds"_special_bonds.html command). The number of times neighbor lists were rebuilt during the run is given as well as the number of potentially "dangerous" rebuilds. If atom movement triggered neighbor list rebuilding (see the "neigh_modify"_neigh_modify.html command), then dangerous reneighborings are those that were triggered on the first timestep atom movement was checked for. If this count is non-zero you may wish to reduce the delay factor to insure no force interactions are missed by atoms moving beyond the neighbor skin distance before a rebuild takes place. If an energy minimization was performed via the "minimize"_minimize.html command, additional information is printed, e.g. Minimization stats: Stopping criterion = linesearch alpha is zero Energy initial, next-to-last, final = -6372.3765206 -8328.46998942 -8328.46998942 Force two-norm initial, final = 1059.36 5.36874 Force max component initial, final = 58.6026 1.46872 Final line search alpha, max atom move = 2.7842e-10 4.0892e-10 Iterations, force evaluations = 701 1516 :pre The first line prints the criterion that determined the minimization to be completed. The third line lists the initial and final energy, as well as the energy on the next-to-last iteration. The next 2 lines give a measure of the gradient of the energy (force on all atoms). The 2-norm is the "length" of this force vector; the inf-norm is the largest component. Then some information about the line search and statistics on how many iterations and force-evaluations the minimizer required. Multiple force evaluations are typically done at each iteration to perform a 1d line minimization in the search direction. If a "kspace_style"_kspace_style.html long-range Coulombics solve was performed during the run (PPPM, Ewald), then additional information is printed, e.g. FFT time (% of Kspce) = 0.200313 (8.34477) FFT Gflps 3d 1d-only = 2.31074 9.19989 :pre The first line gives the time spent doing 3d FFTs (4 per timestep) and the fraction it represents of the total KSpace time (listed above). Each 3d FFT requires computation (3 sets of 1d FFTs) and communication (transposes). The total flops performed is 5Nlog_2(N), where N is the number of points in the 3d grid. The FFTs are timed with and without the communication and a Gflop rate is computed. The 3d rate is with communication; the 1d rate is without (just the 1d FFTs). Thus you can estimate what fraction of your FFT time was spent in communication, roughly 75% in the example above. :line 2.9 Tips for users of previous LAMMPS versions :h4,link(start_9) The current C++ began with a complete rewrite of LAMMPS 2001, which was written in F90. Features of earlier versions of LAMMPS are listed in "Section 13"_Section_history.html. The F90 and F77 versions (2001 and 99) are also freely distributed as open-source codes; check the "LAMMPS WWW Site"_lws for distribution information if you prefer those versions. The 99 and 2001 versions are no longer under active development; they do not have all the features of C++ LAMMPS. If you are a previous user of LAMMPS 2001, these are the most significant changes you will notice in C++ LAMMPS: (1) The names and arguments of many input script commands have changed. All commands are now a single word (e.g. read_data instead of read data). (2) All the functionality of LAMMPS 2001 is included in C++ LAMMPS, but you may need to specify the relevant commands in different ways. (3) The format of the data file can be streamlined for some problems. See the "read_data"_read_data.html command for details. The data file section "Nonbond Coeff" has been renamed to "Pair Coeff" in C++ LAMMPS. (4) Binary restart files written by LAMMPS 2001 cannot be read by C++ LAMMPS with a "read_restart"_read_restart.html command. This is because they were output by F90 which writes in a different binary format than C or C++ writes or reads. Use the {restart2data} tool provided with LAMMPS 2001 to convert the 2001 restart file to a text data file. Then edit the data file as necessary before using the C++ LAMMPS "read_data"_read_data.html command to read it in. (5) There are numerous small numerical changes in C++ LAMMPS that mean you will not get identical answers when comparing to a 2001 run. However, your initial thermodynamic energy and MD trajectory should be close if you have setup the problem for both codes the same. diff --git a/doc/src/atom_style.txt b/doc/src/atom_style.txt index 74b5f0b15..7e2803abd 100644 --- a/doc/src/atom_style.txt +++ b/doc/src/atom_style.txt @@ -1,301 +1,301 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line atom_style command :h3 [Syntax:] atom_style style args :pre style = {angle} or {atomic} or {body} or {bond} or {charge} or {dipole} or \ {dpd} or {electron} or {ellipsoid} or {full} or {line} or {meso} or \ {molecular} or {peri} or {smd} or {sphere} or {tri} or \ {template} or {hybrid} :ulb,l args = none for any style except the following {body} args = bstyle bstyle-args bstyle = style of body particles bstyle-args = additional arguments specific to the bstyle see the "body"_body.html doc page for details {template} args = template-ID template-ID = ID of molecule template specified in a separate "molecule"_molecule.html command {hybrid} args = list of one or more sub-styles, each with their args :pre accelerated styles (with same args) = {angle/kk} or {atomic/kk} or {bond/kk} or {charge/kk} or {full/kk} or {molecular/kk} :l :ule [Examples:] atom_style atomic atom_style bond atom_style full atom_style body nparticle 2 10 atom_style hybrid charge bond atom_style hybrid charge body nparticle 2 5 atom_style template myMols :pre [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 "read_data"_read_data.html, "read_restart"_read_restart.html, or "create_box"_create_box.html command. NOTE: Many of the atom styles discussed here are only enabled if LAMMPS was built with a specific package, as listed below in the Restrictions section. 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 "read_data"_read_data.html 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 "read_data"_read_data.html, "create_atoms"_create_atoms.html, and "set"_set.html 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 | {dpd} | internal temperature and internal energies | DPD 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 :tb(c=3,s=|) NOTE: It is possible to add some attributes, such as a molecule ID, to atom styles that do not have them via the "fix property/atom"_fix_property_atom.html command. This command also allows new custom attributes consisting of extra integer or floating-point values to be added to atoms. See the "fix property/atom"_fix_property_atom.html 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 "Section_howto -14"_Section_howto.html#howto_14 for an overview of using finite-size +{body} styles, which define finite-size particles. See "Section +6.14"_Section_howto.html#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 "mass"_mass.html 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 {dpd} style is for dissipative particle dynamics (DPD) particles. Note that it is part of the USER-DPD package, and is not for use with the "pair_style dpd or dpd/stat"_pair_dpd.html commands, which can simply use atom_style atomic. Atom_style dpd extends DPD particle properties with internal temperature (dpdTheta), internal conductive energy (uCond), internal mechanical energy (uMech), and internal chemical energy (uChem). 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 "(Grime)"_#Grime, for examples of how this can be advantageous for large-scale coarse-grained systems. NOTE: When using the {template} style with a "molecule template"_molecule.html 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 "read_data"_read_data.html 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 "body"_body.html 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 "body"_body.html doc page. :line 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 "this section"_Section_modify.html. :line Styles with a {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 "Section 5"_Section_accelerate.html 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 KOKKOS package. They are only enabled if LAMMPS was built with those packages. See the "Making LAMMPS"_Section_start.html#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 "-suffix command-line switch"_Section_start.html#start_7 when you invoke LAMMPS, or you can use the "suffix"_suffix.html command in your input script. See "Section 5"_Section_accelerate.html 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 "read_data"_read_data.html or "create_box"_create_box.html command. Many of the styles listed above are only enabled if LAMMPS was built with a specific package, as listed below. See the "Making LAMMPS"_Section_start.html#start_3 section for more info. The {angle}, {bond}, {full}, {molecular}, and {template} styles are part of the MOLECULE package. The {line} and {tri} styles are part of the ASPHERE package. 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 "electronic force fields"_pair_eff.html. The {dpd} style is part of the USER-DPD package for dissipative particle dynamics (DPD). 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 "antisymmetrized wave packet MD method"_pair_awpmd.html. [Related commands:] "read_data"_read_data.html, "pair_style"_pair_style.html [Default:] atom_style atomic :line :link(Grime) [(Grime)] Grime and Voth, to appear in J Chem Theory & Computation (2014). diff --git a/doc/src/compute_angmom_chunk.txt b/doc/src/compute_angmom_chunk.txt index 97722c935..439ff5192 100644 --- a/doc/src/compute_angmom_chunk.txt +++ b/doc/src/compute_angmom_chunk.txt @@ -1,89 +1,89 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute angmom/chunk command :h3 [Syntax:] compute ID group-ID angmom/chunk chunkID :pre ID, group-ID are documented in "compute"_compute.html command angmom/chunk = style name of this compute command chunkID = ID of "compute chunk/atom"_compute_chunk_atom.html command :ul [Examples:] compute 1 fluid angmom/chunk molchunk :pre [Description:] Define a computation that calculates the angular momemtum of multiple chunks of atoms. In LAMMPS, chunks are collections of atoms defined by a "compute chunk/atom"_compute_chunk_atom.html 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 "compute -chunk/atom"_compute_chunk_atom.html doc page and ""Section_howto -23"_Section_howto.html#howto_23 for details of how chunks can be +chunk/atom"_compute_chunk_atom.html doc page and "Section +6.23"_Section_howto.html#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 "compute chunk/atom"_compute_chunk_atom.html 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 "dump custom"_dump.html command for a discussion of "unwrapped" coordinates. See the Atoms section of the "read_data"_read_data.html 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 "set image"_set.html command. The simplest way to output the results of the compute angmom/chunk calculation to a file is to use the "fix ave/time"_fix_ave_time.html command, for example: 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 :pre [Output info:] This compute calculates a global array where the number of rows = the number of chunks {Nchunk} as calculated by the specified "compute chunk/atom"_compute_chunk_atom.html 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 "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +values from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The array values are "intensive". The array values will be in mass-velocity-distance "units"_units.html. [Restrictions:] none [Related commands:] "variable angmom() function"_variable.html [Default:] none diff --git a/doc/src/compute_basal_atom.txt b/doc/src/compute_basal_atom.txt index af0185e37..b59a3fd4c 100644 --- a/doc/src/compute_basal_atom.txt +++ b/doc/src/compute_basal_atom.txt @@ -1,76 +1,76 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute basal/atom command :h3 [Syntax:] compute ID group-ID basal/atom :pre ID, group-ID are documented in "compute"_compute.html command basal/atom = style name of this compute command :ul [Examples:] compute 1 all basal/atom :pre [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 "(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 "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +a compute as input. See "Section +6.15"_Section_howto.html#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 "Making LAMMPS"_Section_start.html#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:] "compute centro/atom"_compute_centro_atom.html, "compute ackland/atom"_compute_ackland_atom.html [Default:] none :line :link(Barrett) [(Barrett)] Barrett, Tschopp, El Kadiri, Scripta Mat. 66, p.666 (2012). diff --git a/doc/src/compute_centro_atom.txt b/doc/src/compute_centro_atom.txt index 17403d71e..2a3ae15aa 100644 --- a/doc/src/compute_centro_atom.txt +++ b/doc/src/compute_centro_atom.txt @@ -1,151 +1,151 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute centro/atom command :h3 [Syntax:] compute ID group-ID centro/atom lattice keyword value ... :pre ID, group-ID are documented in "compute"_compute.html command centro/atom = style name of this compute command lattice = {fcc} or {bcc} or N = # of neighbors per atom to include :l zero or more keyword/value pairs may be appended :l keyword = {axes} :l {axes} value = {no} or {yes} {no} = do not calulate 3 symmetry axes {yes} = calulate 3 symmetry axes :pre :ule [Examples:] compute 1 all centro/atom fcc :pre compute 1 all centro/atom 8 :pre [Description:] Define a computation that calculates the centro-symmetry parameter for each atom in the group, for either FCC or BCC lattices, depending on the choice of the {lattice} argument. 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 "(Kelchner)"_#Kelchner :c,image(Eqs/centro_symmetry.jpg) where the {N} nearest neighbors of 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. If the keyword {axes} has the setting {yes}, then this compute also estimates three symmetry axes for each atom's local neighborhood. The first two of these are the vectors joining the two pairs of neighbor atoms with smallest contributions to the centrosymmetry parameter, i.e. the two most symmetric pairs of atoms. The third vector is normal to the first two by the right-hand rule. All three vectors are normalized to unit length. For FCC crystals, the first two vectors will lie along a <110> direction, while the third vector will lie along either a <100> or <111> direction. For HCP crystals, the first two vectors will lie along <1000> directions, while the third vector will lie along <0001>. This provides a simple way to measure local orientation in HCP structures. In general, the {axes} keyword can be used to estimate the orientation of symmetry axes in the neighborhood of any atom. 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:] By default, this compute calculates the centrosymmetry value for each atom as 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"_Section_howto.html#howto_15 for an overview of LAMMPS output +uses per-atom values from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. If the {axes} keyword setting is {yes}, then a per-atom array is calculated. The first column is the centrosymmetry parameter. The next three columns are the x, y, and z components of the first symmetry axis, followed by the second, and third symmetry axes in columns 5-7 and 8-10. The centrosymmetry 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. For the {axes yes} case, the vector components are also unitless, since they represent spatial directions. Here are typical centro-symmetry values, from a a nanoindentation simulation into gold (FCC). These were provided by Jon Zimmerman (Sandia): 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 :pre These values are *not* normalized by the square of the lattice parameter. If they were, normalized values would be: 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 :pre 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:] "compute cna/atom"_compute_cna_atom.html [Default:] The default value for the optional keyword is axes = no. :line :link(Kelchner) [(Kelchner)] Kelchner, Plimpton, Hamilton, Phys Rev B, 58, 11085 (1998). diff --git a/doc/src/compute_chunk_atom.txt b/doc/src/compute_chunk_atom.txt index 82d33c003..2778be4f6 100644 --- a/doc/src/compute_chunk_atom.txt +++ b/doc/src/compute_chunk_atom.txt @@ -1,665 +1,665 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute chunk/atom command :h3 [Syntax:] compute ID group-ID chunk/atom style args keyword values ... :pre ID, group-ID are documented in "compute"_compute.html command :ulb,l chunk/atom = style name of this compute command :l 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 :pre zero or more keyword/values pairs may be appended :l keyword = {region} or {nchunk} or {static} or {compress} or {bound} or {discard} or {pbc} or {units} :l {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 "fix ave/chunk"_fix_ave_chunk.html 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} :pre :ule [Examples:] 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 :pre [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 "compute"_compute.html, "fix"_fix.html, or "atom-style variable"_variable.html. Per-atom chunk IDs can be used by other computes with "chunk" in their style name, such as "compute com/chunk"_compute_com_chunk.html or "compute msd/chunk"_compute_msd_chunk.html. Or they can be used by the "fix ave/chunk"_fix_ave_chunk.html 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 "Section_howto -15"_Section_howto.html#howto_15. +compute as input, as discussed in "Section +6.15"_Section_howto.html#howto_15. See "Section 6.23"_Section_howto.html#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 "fix ave/chunk"_fix_ave_chunk.html 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. :line :line 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. :line 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 "this section"_Section_howto.html#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. :line 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 "create_box"_create_box.html or "read_data"_read_data.html commands. :line 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. :line 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 "add them to LAMMPS"_Section_modify.html. 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 "add them to LAMMPS"_Section_modify.html. If a value begins with "v_", a variable name for an {atom} or {atomfile} style "variable"_variable.html 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. :line :line 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 "fix ave/chunk"_fix_ave_chunk.html 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 "fix ave/chunk"_fix_ave_chunk.html 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 "fix ave/chunk"_fix_ave_chunk.html command invokes this compute. Note that multiple "fix ave/chunk"_fix_ave_chunk.html 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. :line :line 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 "region"_region.html to be assigned to a chunk. :line 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 "fix ave/chunk"_fix_ave_chunk.html 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. :line 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}. :line 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 "fix ave/chunk"_fix_ave_chunk.html 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 "restart file"_read_restart.html, 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. :line 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 "compute cluster/atom"_compute_cluster_atom.html 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 "compute property/chunk"_compute_property_chunk.html command and its {id} keyword, or by the "fix ave/chunk"_fix_ave_chunk.html 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 "fix ave/chunk"_fix_ave_chunk.html command, or by using the "fix ave/time"_fix_ave_time.html command in conjunction with the "compute property/chunk"_compute_property_chunk.html 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. :line 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. :line 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 "units"_units.html command, e.g. Angstroms for units = real or metal. A {lattice} value means the distance units are in lattice spacings. The "lattice"_lattice.html 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. :line [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 6.15"_Section_howto.html#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:] "fix ave/chunk"_fix_ave_chunk.html [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 :ul diff --git a/doc/src/compute_com_chunk.txt b/doc/src/compute_com_chunk.txt index b7b367e01..d497585cb 100644 --- a/doc/src/compute_com_chunk.txt +++ b/doc/src/compute_com_chunk.txt @@ -1,87 +1,87 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute com/chunk command :h3 [Syntax:] compute ID group-ID com/chunk chunkID :pre ID, group-ID are documented in "compute"_compute.html command com/chunk = style name of this compute command chunkID = ID of "compute chunk/atom"_compute_chunk_atom.html command :ul [Examples:] compute 1 fluid com/chunk molchunk :pre [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 "compute chunk/atom"_compute_chunk_atom.html 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 "compute -chunk/atom"_compute_chunk_atom.html doc page and ""Section_howto -23"_Section_howto.html#howto_23 for details of how chunks can be +chunk/atom"_compute_chunk_atom.html doc page and "Section +6.23"_Section_howto.html#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 "compute chunk/atom"_compute_chunk_atom.html 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 "dump custom"_dump.html command for a discussion of "unwrapped" coordinates. See the Atoms section of the "read_data"_read_data.html 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 "set image"_set.html command. The simplest way to output the results of the compute com/chunk calculation to a file is to use the "fix ave/time"_fix_ave_time.html command, for example: 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 :pre [Output info:] This compute calculates a global array where the number of rows = the number of chunks {Nchunk} as calculated by the specified "compute chunk/atom"_compute_chunk_atom.html 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 "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The array values are "intensive". The array values will be in distance "units"_units.html. [Restrictions:] none [Related commands:] "compute com"_compute_com.html [Default:] none diff --git a/doc/src/compute_coord_atom.txt b/doc/src/compute_coord_atom.txt index 123feaf7d..012a87a9a 100644 --- a/doc/src/compute_coord_atom.txt +++ b/doc/src/compute_coord_atom.txt @@ -1,92 +1,92 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute coord/atom command :h3 [Syntax:] compute ID group-ID coord/atom cutoff type1 type2 ... :pre ID, group-ID are documented in "compute"_compute.html 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) :ul [Examples:] 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 * :pre [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 "special_bonds"_special_bonds.html command can remove pairwise interactions between atoms in the same bond, angle, or dihedral. This is the default setting for the "special_bonds"_special_bonds.html 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 "rerun"_rerun.html command to compute the coordination for snapshots in the dump file. The rerun script can use a "special_bonds"_special_bonds.html 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 "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +per-atom values from a compute as input. See "Section +6.15"_Section_howto.html#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:] "compute cluster/atom"_compute_cluster_atom.html [Default:] none diff --git a/doc/src/compute_dipole_chunk.txt b/doc/src/compute_dipole_chunk.txt index 0d2a8011e..7dfddfd6a 100644 --- a/doc/src/compute_dipole_chunk.txt +++ b/doc/src/compute_dipole_chunk.txt @@ -1,92 +1,92 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute dipole/chunk command :h3 [Syntax:] compute ID group-ID dipole/chunk chunkID charge-correction :pre ID, group-ID are documented in "compute"_compute.html command dipole/chunk = style name of this compute command chunkID = ID of "compute chunk/atom"_compute_chunk_atom.html command charge-correction = {mass} or {geometry}, use COM or geometric center for charged chunk correction (optional) :ul [Examples:] compute 1 fluid dipole/chunk molchunk compute dw water dipole/chunk 1 geometry :pre [Description:] Define a computation that calculates the dipole vector and total dipole for multiple chunks of atoms. In LAMMPS, chunks are collections of atoms defined by a "compute chunk/atom"_compute_chunk_atom.html 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 "compute -chunk/atom"_compute_chunk_atom.html doc page and ""Section_howto -23"_Section_howto.html#howto_23 for details of how chunks can be +chunk/atom"_compute_chunk_atom.html doc page and "Section +6.23"_Section_howto.html#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 dipole vector and the total dipole moment for each chunk, which includes all effects due to atoms passing thru periodic boundaries. For chunks with a net charge the resulting dipole is made position independent by subtracting the position vector of the center of mass or geometric center times the net charge from the computed dipole vector. Note that only atoms in the specified group contribute to the calculation. The "compute chunk/atom"_compute_chunk_atom.html 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 dipole in "unwrapped" form, by using the image flags associated with each atom. See the "dump custom"_dump.html command for a discussion of "unwrapped" coordinates. See the Atoms section of the "read_data"_read_data.html 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 "set image"_set.html command. The simplest way to output the results of the compute com/chunk calculation to a file is to use the "fix ave/time"_fix_ave_time.html command, for example: compute cc1 all chunk/atom molecule compute myChunk all dipole/chunk cc1 fix 1 all ave/time 100 1 100 c_myChunk\[*\] file tmp.out mode vector :pre [Output info:] This compute calculates a global array where the number of rows = the number of chunks {Nchunk} as calculated by the specified "compute chunk/atom"_compute_chunk_atom.html command. The number of columns = 4 for the x,y,z dipole vector components and the total dipole of each chunk. These values can be accessed by any command that uses global -array values from a compute as input. See "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +array values from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The array values are "intensive". The array values will be in dipole units, i.e. charge units times distance "units"_units.html. [Restrictions:] none [Related commands:] "compute com/chunk"_compute_com_chunk.html [Default:] none diff --git a/doc/src/compute_displace_atom.txt b/doc/src/compute_displace_atom.txt index 7420dffef..566dcfc0a 100644 --- a/doc/src/compute_displace_atom.txt +++ b/doc/src/compute_displace_atom.txt @@ -1,69 +1,69 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute displace/atom command :h3 [Syntax:] compute ID group-ID displace/atom :pre ID, group-ID are documented in "compute"_compute.html command displace/atom = style name of this compute command :ul [Examples:] compute 1 all displace/atom :pre [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 "dump custom"_dump.html command for a discussion of "unwrapped" coordinates. See the Atoms section of the "read_data"_read_data.html 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 "set image"_set.html command. NOTE: If you want the quantities calculated by this compute to be continuous when running from a "restart file"_read_restart.html, 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 "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The per-atom array values will be in distance "units"_units.html. [Restrictions:] none [Related commands:] "compute msd"_compute_msd.html, "dump custom"_dump.html, "fix store/state"_fix_store_state.html [Default:] none diff --git a/doc/src/compute_dpd_atom.txt b/doc/src/compute_dpd_atom.txt index 0ce40f66f..f586e0f09 100644 --- a/doc/src/compute_dpd_atom.txt +++ b/doc/src/compute_dpd_atom.txt @@ -1,66 +1,66 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute dpd/atom command :h3 [Syntax:] compute ID group-ID dpd/atom :pre ID, group-ID are documented in "compute"_compute.html command dpd/atom = style name of this compute command :ul [Examples:] compute 1 all dpd/atom [Description:] Define a computation that accesses the per-particle internal conductive energy (u_cond), internal mechanical energy (u_mech), internal chemical energy (u_chem) and internal temperatures (dpdTheta) for each particle in a group. See the "compute dpd"_compute_dpd.html command if you want the total internal conductive energy, the total internal mechanical energy, the total chemical energy and average internal temperature of the entire system or group of dpd particles. [Output info:] This compute calculates a per-particle array with 4 columns (u_cond, u_mech, u_chem, dpdTheta), which can be accessed by indices 1-4 by any command that uses per-particle values from a compute as input. See -"Section_howto15"_Section_howto.html#howto_15 for an overview of +"Section 6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The per-particle array values will be in energy (u_cond, u_mech, u_chem) and temperature (dpdTheta) "units"_units.html. [Restrictions:] This command is part of the USER-DPD package. It is only enabled if LAMMPS was built with that package. See the "Making LAMMPS"_Section_start.html#start_3 section for more info. This command also requires use of the "atom_style dpd"_atom_style.html command. [Related commands:] "dump custom"_dump.html, "compute dpd"_compute_dpd.html [Default:] none :line :link(Larentzos) [(Larentzos)] J.P. Larentzos, J.K. Brennan, J.D. Moore, and W.D. Mattson, "LAMMPS Implementation of Constant Energy Dissipative Particle Dynamics (DPD-E)", ARL-TR-6863, U.S. Army Research Laboratory, Aberdeen Proving Ground, MD (2014). diff --git a/doc/src/compute_fep.txt b/doc/src/compute_fep.txt index c5fb2f0b7..f4325f620 100644 --- a/doc/src/compute_fep.txt +++ b/doc/src/compute_fep.txt @@ -1,263 +1,263 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute fep command :h3 [Syntax:] compute ID group-ID fep temp attribute args ... keyword value ... :pre ID, group-ID are documented in the "compute"_compute.html command :ulb,l fep = name of this compute command :l temp = external temperature (as specified for constant-temperature run) :l one or more attributes with args may be appended :l attribute = {pair} or {atom} :l {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) :pre zero or more keyword/value pairs may be appended :l keyword = {tail} or {volume} :l {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) :pre :ule [Examples:] 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 :pre [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_0\) corresponding to the initial interactions of the atoms that will undergo perturbation, and a term \(U_1\) corresponding to the final interactions of these atoms: :c,image(Eqs/compute_fep_u.jpg) A coupling parameter \(\lambda\) varying from 0 to 1 connects the reference and perturbed systems: :c,image(Eqs/compute_fep_lambda.jpg) 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 "fix adapt"_fix_adapt.html to perform multistage free-energy perturbation calculations along stepwise alchemical transformations during a simulation run: :c,image(Eqs/compute_fep_fep.jpg) This compute is suitable for the finite-difference thermodynamic integration (FDTI) method "(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\): :c,image(Eqs/compute_fep_fdti.jpg) where \(w_i\) are weights of a numerical quadrature. The "fix adapt"_fix_adapt.html 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_1 -U_0\). 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\): :c,image(Eqs/compute_fep_ti.jpg) Another technique to calculate free energy differences is the acceptance ratio method "(Bennet)"_#Bennet, which can be implemented by calculating the potential energy differences with \(\delta\) = 1.0 on both the forward and reverse routes: :c,image(Eqs/compute_fep_bar.jpg) 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 "(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 "(Boresch, Karplus)"_#BoreschKarplus. :line The {pair} attribute enables various parameters of potentials defined by the "pair_style"_pair_style.html and "pair_coeff"_pair_coeff.html 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: "lj/cut"_pair_lj.html: epsilon,sigma: type pairs: "lj/cut/coul/cut"_pair_lj.html: epsilon,sigma: type pairs: "lj/cut/coul/long"_pair_lj.html: epsilon,sigma: type pairs: "lj/cut/soft"_pair_lj_soft.html: epsilon,sigma,lambda: type pairs: "coul/cut/soft"_pair_lj_soft.html: lambda: type pairs: "coul/long/soft"_pair_lj_soft.html: lambda: type pairs: "lj/cut/coul/cut/soft"_pair_lj_soft.html: epsilon,sigma,lambda: type pairs: "lj/cut/coul/long/soft"_pair_lj_soft.html: epsilon,sigma,lambda: type pairs: "lj/cut/tip4p/long/soft"_pair_lj_soft.html: epsilon,sigma,lambda: type pairs: "tip4p/long/soft"_pair_lj_soft.html: lambda: type pairs: "lj/charmm/coul/long/soft"_pair_lj_soft.html: epsilon,sigma,lambda: type pairs: "born"_pair_born.html: a,b,c: type pairs: "buck"_pair_buck.html: a,c : type pairs :tb(c=3,s=:) 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 "pair_coeff"_pair_coeff.html 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 "pair_style hybrid or hybrid/overlay"_pair_hybrid.html 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 "pair_coeff"_pair_coeff.html command) for that sub-style. The {v_name} argument for keyword {pair} is the name of an "equal-style variable"_variable.html which will be evaluated each time this compute is invoked. It should be specified as v_name, where name is the variable name. :line 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 :ul The {v_name} argument for keyword {pair} is the name of an "equal-style variable"_variable.html which will be evaluated each time this compute is invoked. It should be specified as v_name, where name is the variable name. :line 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 "pair_modify"_pair_modify.html 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 "(Allen and Tildesley)"_#AllenTildesley: :c,image(Eqs/compute_fep_vol.jpg) :line [Output info:] This compute calculates a global vector of length 3 which contains the energy difference ( \(U_1-U_0\) ) as c_ID\[1\], the Boltzmann factor \(\exp(-(U_1-U_0)/kT)\), or \(V \exp(-(U_1-U_0)/kT)\), as c_ID\[2\] and the volume of the simulation box \(V\) as c_ID\[3\]. \(U_1\) is the pair potential energy obtained with the perturbed parameters and \(U_0\) 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 "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +scalar or vector from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. For example, the computed values can be averaged using "fix ave/time"_fix_ave_time.html. 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 "Making LAMMPS"_Section_start.html#start_3 section for more info. [Related commands:] "fix adapt/fep"_fix_adapt_fep.html, "fix ave/time"_fix_ave_time.html, "pair_lj_soft_coul_soft"_pair_lj_soft_coul_soft.txt [Default:] The option defaults are {tail} = {no}, {volume} = {no}. :line :link(Pearlman) [(Pearlman)] Pearlman, J Chem Phys, 98, 1487 (1994) :link(Mezei) [(Mezei)] Mezei, J Chem Phys, 86, 7084 (1987) :link(Bennet) [(Bennet)] Bennet, J Comput Phys, 22, 245 (1976) :link(BoreschKarplus) [(BoreschKarplus)] Boresch and Karplus, J Phys Chem A, 103, 103 (1999) :link(AllenTildesley) [(AllenTildesley)] Allen and Tildesley, Computer Simulation of Liquids, Oxford University Press (1987) diff --git a/doc/src/compute_gyration.txt b/doc/src/compute_gyration.txt index dc03234de..dd7143152 100644 --- a/doc/src/compute_gyration.txt +++ b/doc/src/compute_gyration.txt @@ -1,72 +1,72 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute gyration command :h3 [Syntax:] compute ID group-ID gyration :pre ID, group-ID are documented in "compute"_compute.html command gyration = style name of this compute command :ul [Examples:] compute 1 molecule gyration :pre [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 :c,image(Eqs/compute_gyration.jpg) 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 "dump custom"_dump.html command for a discussion of "unwrapped" coordinates. See the Atoms section of the "read_data"_read_data.html 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 "set image"_set.html 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 "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +vector values from a compute as input. See "Section +6.15"_Section_howto.html#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 "units"_units.html respectively. [Restrictions:] none [Related commands:] "compute gyration/chunk"_compute_gyration_chunk.html [Default:] none diff --git a/doc/src/compute_gyration_chunk.txt b/doc/src/compute_gyration_chunk.txt index 53b35213b..3beecce58 100644 --- a/doc/src/compute_gyration_chunk.txt +++ b/doc/src/compute_gyration_chunk.txt @@ -1,110 +1,110 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute gyration/chunk command :h3 [Syntax:] compute ID group-ID gyration/chunk chunkID keyword value ... :pre ID, group-ID are documented in "compute"_compute.html command :ulb,l gyration/chunk = style name of this compute command :l chunkID = ID of "compute chunk/atom"_compute_chunk_atom.html command :l zero or more keyword/value pairs may be appended :l keyword = {tensor} :l {tensor} value = none :pre :ule [Examples:] compute 1 molecule gyration/chunk molchunk compute 2 molecule gyration/chunk molchunk tensor :pre [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 "compute chunk/atom"_compute_chunk_atom.html 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 "compute -chunk/atom"_compute_chunk_atom.html doc page and ""Section_howto -23"_Section_howto.html#howto_23 for details of how chunks can be +chunk/atom"_compute_chunk_atom.html doc page and "Section +6.23"_Section_howto.html#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 :c,image(Eqs/compute_gyration.jpg) 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 "compute chunk/atom"_compute_chunk_atom.html 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 "dump custom"_dump.html command for a discussion of "unwrapped" coordinates. See the Atoms section of the "read_data"_read_data.html 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 "set image"_set.html command. The simplest way to output the results of the compute gyration/chunk calculation to a file is to use the "fix ave/time"_fix_ave_time.html command, for example: 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 :pre [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 "compute chunk/atom"_compute_chunk_atom.html 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 "this section"_Section_howto.html#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 "units"_units.html, since they are the square root of values represented by the formula above. [Restrictions:] none [Related commands:] none "compute gyration"_compute_gyration.html [Default:] none diff --git a/doc/src/compute_hexorder_atom.txt b/doc/src/compute_hexorder_atom.txt index bbcab832b..c6f111a6c 100644 --- a/doc/src/compute_hexorder_atom.txt +++ b/doc/src/compute_hexorder_atom.txt @@ -1,116 +1,116 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute hexorder/atom command :h3 [Syntax:] compute ID group-ID hexorder/atom keyword values ... :pre ID, group-ID are documented in "compute"_compute.html command :ulb,l hexorder/atom = style name of this compute command :l one or more keyword/value pairs may be appended :l keyword = {degree} or {nnn} or {cutoff} {cutoff} value = distance cutoff {nnn} value = number of nearest neighbors {degree} value = degree {n} of order parameter :pre :ule [Examples:] compute 1 all hexorder/atom compute 1 all hexorder/atom degree 4 nnn 4 cutoff 1.2 :pre [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 "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: :c,image(Eqs/hexorder.jpg) 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 "special_bonds"_special_bonds.html command can remove pairwise interactions between atoms in the same bond, angle, or dihedral. This is the default setting for the "special_bonds"_special_bonds.html 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 "rerun"_rerun.html command to compute the order parameter for snapshots in the dump file. The rerun script can use a "special_bonds"_special_bonds.html 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 "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +per-atom values from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. [Restrictions:] none [Related commands:] "compute orientorder/atom"_compute_orientorder_atom.html, "compute coord/atom"_compute_coord_atom.html, "compute centro/atom"_compute_centro_atom.html [Default:] The option defaults are {cutoff} = pair style cutoff, {nnn} = 6, {degree} = 6 :line :link(Nelson) [(Nelson)] Nelson, Halperin, Phys Rev B, 19, 2457 (1979). diff --git a/doc/src/compute_inertia_chunk.txt b/doc/src/compute_inertia_chunk.txt index 6f28ed0aa..215f3c1a8 100644 --- a/doc/src/compute_inertia_chunk.txt +++ b/doc/src/compute_inertia_chunk.txt @@ -1,88 +1,88 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute inertia/chunk command :h3 [Syntax:] compute ID group-ID inertia/chunk chunkID :pre ID, group-ID are documented in "compute"_compute.html command inertia/chunk = style name of this compute command chunkID = ID of "compute chunk/atom"_compute_chunk_atom.html command :ul [Examples:] compute 1 fluid inertia/chunk molchunk :pre [Description:] Define a computation that calculates the inertia tensor for multiple chunks of atoms. In LAMMPS, chunks are collections of atoms defined by a "compute chunk/atom"_compute_chunk_atom.html 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 "compute -chunk/atom"_compute_chunk_atom.html doc page and ""Section_howto -23"_Section_howto.html#howto_23 for details of how chunks can be +chunk/atom"_compute_chunk_atom.html doc page and "Section +6.23"_Section_howto.html#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 "compute chunk/atom"_compute_chunk_atom.html 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 "dump custom"_dump.html command for a discussion of "unwrapped" coordinates. See the Atoms section of the "read_data"_read_data.html 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 "set image"_set.html command. The simplest way to output the results of the compute inertia/chunk calculation to a file is to use the "fix ave/time"_fix_ave_time.html command, for example: 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 :pre [Output info:] This compute calculates a global array where the number of rows = the number of chunks {Nchunk} as calculated by the specified "compute chunk/atom"_compute_chunk_atom.html 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 "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +uses global array values from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The array values are "intensive". The array values will be in mass*distance^2 "units"_units.html. [Restrictions:] none [Related commands:] "variable inertia() function"_variable.html [Default:] none diff --git a/doc/src/compute_ke_rigid.txt b/doc/src/compute_ke_rigid.txt index 4e65cae72..f79696a77 100644 --- a/doc/src/compute_ke_rigid.txt +++ b/doc/src/compute_ke_rigid.txt @@ -1,60 +1,60 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute ke/rigid command :h3 [Syntax:] compute ID group-ID ke/rigid fix-ID :pre ID, group-ID are documented in "compute"_compute.html command ke = style name of this compute command fix-ID = ID of rigid body fix :ul [Examples:] compute 1 all ke/rigid myRigid :pre [Description:] Define a computation that calculates the translational kinetic energy of a collection of rigid bodies, as defined by one of the "fix rigid"_fix_rigid.html 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 "fix rigid"_fix_rigid.html 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 "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +global scalar value from a compute as input. See "Section +6.15"_Section_howto.html#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 "units"_units.html. [Restrictions:] This compute is part of the RIGID package. It is only enabled if LAMMPS was built with that package. See the "Making LAMMPS"_Section_start.html#start_3 section for more info. [Related commands:] "compute erotate/rigid"_compute_erotate_rigid.html [Default:] none diff --git a/doc/src/compute_msd_chunk.txt b/doc/src/compute_msd_chunk.txt index 8d3ba0785..7382ca87d 100644 --- a/doc/src/compute_msd_chunk.txt +++ b/doc/src/compute_msd_chunk.txt @@ -1,121 +1,121 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute msd/chunk command :h3 [Syntax:] compute ID group-ID msd/chunk chunkID :pre ID, group-ID are documented in "compute"_compute.html command msd/chunk = style name of this compute command chunkID = ID of "compute chunk/atom"_compute_chunk_atom.html command :ul [Examples:] compute 1 all msd/chunk molchunk :pre [Description:] Define a computation that calculates the mean-squared displacement (MSD) for multiple chunks of atoms. In LAMMPS, chunks are collections of atoms defined by a "compute chunk/atom"_compute_chunk_atom.html 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 "compute -chunk/atom"_compute_chunk_atom.html doc page and ""Section_howto -23"_Section_howto.html#howto_23 for details of how chunks can be +chunk/atom"_compute_chunk_atom.html doc page and "Section +6.23"_Section_howto.html#howto_23 for details of how chunks can be defined and examples of how they can be used to measure properties of a system. Four quantites are calculated by this compute for each chunk. The first 3 quantities are the squared dx,dy,dz displacements of the center-of-mass. The 4th component is the total squared displacement, i.e. (dx*dx + dy*dy + dz*dz) of the center-of-mass. These calculations include all effects due to atoms passing thru periodic boundaries. Note that only atoms in the specified group contribute to the calculation. The "compute chunk/atom"_compute_chunk_atom.html command defines its own group; atoms will have a chunk ID = 0 if they are not in that group, signifying they are not assigned to a chunk, and will thus also not contribute to this calculation. You can specify the "all" group for this command if you simply want to include atoms with non-zero chunk IDs. The slope of the mean-squared displacement (MSD) versus time is proportional to the diffusion coefficient of the diffusing chunks. The displacement of the center-of-mass of the chunk is from its original center-of-mass position, calculated on the timestep this compute command was first invoked. NOTE: The number of chunks {Nchunk} calculated by the "compute chunk/atom"_compute_chunk_atom.html command must remain constant each time this compute is invoked, so that the displacement for each chunk from its original position can be computed consistently. If {Nchunk} does not remain constant, an error will be generated. If needed, you can enforce a constant {Nchunk} by using the {nchunk once} or {ids once} options when specifying the "compute chunk/atom"_compute_chunk_atom.html command. NOTE: This compute stores the original position (of the center-of-mass) of each chunk. When a displacement is calculated on a later timestep, it is assumed that the same atoms are assigned to the same chunk ID. However LAMMPS has no simple way to insure this is the case, though you can use the {ids once} option when specifying the "compute chunk/atom"_compute_chunk_atom.html command. Note that if this is not the case, the MSD calculation does not have a sensible meaning. NOTE: The initial coordinates of the atoms in each chunk are stored in "unwrapped" form, by using the image flags associated with each atom. See the "dump custom"_dump.html command for a discussion of "unwrapped" coordinates. See the Atoms section of the "read_data"_read_data.html 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 "set image"_set.html command. NOTE: If you want the quantities calculated by this compute to be continuous when running from a "restart file"_read_restart.html, 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-chunk quantities will also have the same ID, and thus be initialized correctly with chunk reference positions from the restart file. The simplest way to output the results of the compute com/msd calculation to a file is to use the "fix ave/time"_fix_ave_time.html command, for example: compute cc1 all chunk/atom molecule compute myChunk all com/msd cc1 fix 1 all ave/time 100 1 100 c_myChunk\[*\] file tmp.out mode vector :pre [Output info:] This compute calculates a global array where the number of rows = the number of chunks {Nchunk} as calculated by the specified "compute chunk/atom"_compute_chunk_atom.html command. The number of columns = 4 for dx,dy,dz and the total displacement. These values can be accessed by any command that uses global array values from a compute as input. See "this section"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The array values are "intensive". The array values will be in distance^2 "units"_units.html. [Restrictions:] none [Related commands:] "compute msd"_compute_msd.html [Default:] none diff --git a/doc/src/compute_omega_chunk.txt b/doc/src/compute_omega_chunk.txt index 8c09cecfc..46c72d3dc 100644 --- a/doc/src/compute_omega_chunk.txt +++ b/doc/src/compute_omega_chunk.txt @@ -1,89 +1,89 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute omega/chunk command :h3 [Syntax:] compute ID group-ID omega/chunk chunkID :pre ID, group-ID are documented in "compute"_compute.html command omega/chunk = style name of this compute command chunkID = ID of "compute chunk/atom"_compute_chunk_atom.html command :ul [Examples:] compute 1 fluid omega/chunk molchunk :pre [Description:] Define a computation that calculates the angular velocity (omega) of multiple chunks of atoms. In LAMMPS, chunks are collections of atoms defined by a "compute chunk/atom"_compute_chunk_atom.html 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 "compute -chunk/atom"_compute_chunk_atom.html doc page and ""Section_howto -23"_Section_howto.html#howto_23 for details of how chunks can be +chunk/atom"_compute_chunk_atom.html doc page and "Section +6.23"_Section_howto.html#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 velocity vector for each chunk, via the formula L = Iw where L is the angular momentum vector of the chunk, I is its moment of inertia tensor, and w is omega = angular velocity 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 "compute chunk/atom"_compute_chunk_atom.html 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 velocity in "unwrapped" form, by using the image flags associated with each atom. See the "dump custom"_dump.html command for a discussion of "unwrapped" coordinates. See the Atoms section of the "read_data"_read_data.html 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 "set image"_set.html command. The simplest way to output the results of the compute omega/chunk calculation to a file is to use the "fix ave/time"_fix_ave_time.html command, for example: compute cc1 all chunk/atom molecule compute myChunk all omega/chunk cc1 fix 1 all ave/time 100 1 100 c_myChunk\[*\] file tmp.out mode vector :pre [Output info:] This compute calculates a global array where the number of rows = the number of chunks {Nchunk} as calculated by the specified "compute chunk/atom"_compute_chunk_atom.html command. The number of columns = 3 for the 3 xyz components of the angular velocity for each chunk. These values can be accessed by any command that uses global array -values from a compute as input. See "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +values from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The array values are "intensive". The array values will be in velocity/distance "units"_units.html. [Restrictions:] none [Related commands:] "variable omega() function"_variable.html [Default:] none diff --git a/doc/src/compute_orientorder_atom.txt b/doc/src/compute_orientorder_atom.txt index 11579fe62..3b6c58c82 100644 --- a/doc/src/compute_orientorder_atom.txt +++ b/doc/src/compute_orientorder_atom.txt @@ -1,121 +1,121 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute orientorder/atom command :h3 [Syntax:] compute ID group-ID orientorder/atom keyword values ... :pre ID, group-ID are documented in "compute"_compute.html command :ulb,l orientorder/atom = style name of this compute command :l one or more keyword/value pairs may be appended :l keyword = {cutoff} or {nnn} or {ql} {cutoff} value = distance cutoff {nnn} value = number of nearest neighbors {degrees} values = nlvalues, l1, l2,... :pre :ule [Examples:] compute 1 all orientorder/atom compute 1 all orientorder/atom degrees 5 4 6 8 10 12 nnn NULL cutoff 1.5 :pre [Description:] Define a computation that calculates a set of bond-orientational order parameters {Ql} for each atom in a group. These order parameters were introduced by "Steinhardt et al."_#Steinhardt as a way to characterize the local orientational order in atomic structures. For each atom, {Ql} is a real number defined as follows: :c,image(Eqs/orientorder.jpg) The first equation defines the spherical harmonic order parameters. These are complex number components of the 3D analog of the 2D order parameter {qn}, which is implemented as LAMMPS compute "hexorder/atom"_compute_hexorder_atom.html. The summation is over the {nnn} nearest neighbors of the central atom. The angles theta and phi are the standard spherical polar angles defining the direction of the bond vector {rij}. The second equation defines {Ql}, which is a rotationally invariant scalar quantity obtained by summing over all the components of degree {l}. 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 {Ql}. The default value is 12. If the value is NULL, then all neighbors up to the specified distance cutoff are used. The optional keyword {degrees} defines the list of order parameters to be computed. The first argument {nlvalues} is the number of order parameters. This is followed by that number of integers giving the degree of each order parameter. Because {Q}2 and all odd-degree order parameters are zero for atoms in cubic crystals (see "Steinhardt"_#Steinhardt), the default order parameters are {Q}4, {Q}6, {Q}8, {Q}10, and {Q}12. For the FCC crystal with {nnn}=12, {Q}4 = sqrt(7/3)/8 = 0.19094.... The numerical values of all order parameters up to {Q}12 for a range of commonly encountered high-symmetry structures are given in Table I of "Mickel et al."_#Mickel. The value of {Ql} is set to zero for atoms not in the specified compute group, as well as for atoms that have less than {nnn} neighbors within the distance cutoff. 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 "special_bonds"_special_bonds.html command can remove pairwise interactions between atoms in the same bond, angle, or dihedral. This is the default setting for the "special_bonds"_special_bonds.html 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 "rerun"_rerun.html command to compute the order parameter for snapshots in the dump file. The rerun script can use a "special_bonds"_special_bonds.html command that includes all pairs in the neighbor list. [Output info:] This compute calculates a per-atom array with {nlvalues} columns, giving the {Ql} values for each atom, which are real numbers on the range 0 <= {Ql} <= 1. These values can be accessed by any command that uses -per-atom values from a compute as input. See "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +per-atom values from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. [Restrictions:] none [Related commands:] "compute coord/atom"_compute_coord_atom.html, "compute centro/atom"_compute_centro_atom.html, "compute hexorder/atom"_compute_hexorder_atom.html [Default:] The option defaults are {cutoff} = pair style cutoff, {nnn} = 12, {degrees} = 5 4 6 8 9 10 12 i.e. {Q}4, {Q}6, {Q}8, {Q}10, and {Q}12. :line :link(Steinhardt) [(Steinhardt)] P. Steinhardt, D. Nelson, and M. Ronchetti, Phys. Rev. B 28, 784 (1983). :link(Mickel) [(Mickel)] W. Mickel, S. C. Kapfer, G. E. Schroeder-Turkand, K. Mecke, J. Chem. Phys. 138, 044501 (2013). diff --git a/doc/src/compute_pe.txt b/doc/src/compute_pe.txt index 2e3f5d8be..15f27a8ef 100644 --- a/doc/src/compute_pe.txt +++ b/doc/src/compute_pe.txt @@ -1,80 +1,80 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute pe command :h3 [Syntax:] compute ID group-ID pe keyword ... :pre ID, group-ID are documented in "compute"_compute.html command pe = style name of this compute command zero or more keywords may be appended keyword = {pair} or {bond} or {angle} or {dihedral} or {improper} or {kspace} or {fix} :ul [Examples:] compute 1 all pe compute molPE all pe bond angle dihedral improper :pre [Description:] Define a computation that calculates the potential energy of the entire system of atoms. The specified group must be "all". See the "compute pe/atom"_compute_pe_atom.html command if you want per-atom energies. These per-atom values could be summed for a group of atoms via the "compute reduce"_compute_reduce.html command. The energy is calculated by the various pair, bond, etc potentials defined for the simulation. If no extra keywords are listed, then the potential energy is the sum of pair, bond, angle, dihedral, improper, kspace (long-range), and fix energy. I.e. it is as if all the keywords were listed. If any extra keywords are listed, then only those components are summed to compute the potential energy. The Kspace contribution requires 1 extra FFT each timestep the energy is calculated, if using the PPPM solver via the "kspace_style pppm"_kspace_style.html command. Thus it can increase the cost of the PPPM calculation if it is needed on a large fraction of the simulation timesteps. Various fixes can contribute to the total potential energy of the system if the {fix} contribution is included. See the doc pages for "individual fixes"_fix.html for details of which ones compute a potential energy. NOTE: The "fix_modify energy yes"_fix_modify.html command must also be specified if a fix is to contribute potential energy to this command. A compute of this style with the ID of "thermo_pe" is created when LAMMPS starts up, as if this command were in the input script: compute thermo_pe all pe :pre See the "thermo_style" command for more details. :line [Output info:] This compute calculates a global scalar (the potential energy). This value can be used by any command that uses a global scalar value from -a compute as input. See "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +a compute as input. See "Section +6.15"_Section_howto.html#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 "units"_units.html. [Restrictions:] none [Related commands:] "compute pe/atom"_compute_pe_atom.html [Default:] none diff --git a/doc/src/compute_property_chunk.txt b/doc/src/compute_property_chunk.txt index c10fe5645..578a6df34 100644 --- a/doc/src/compute_property_chunk.txt +++ b/doc/src/compute_property_chunk.txt @@ -1,118 +1,118 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute property/chunk command :h3 [Syntax:] compute ID group-ID property/chunk chunkID input1 input2 ... :pre ID, group-ID are documented in "compute"_compute.html command :ulb,l property/chunk = style name of this compute command :l input = one or more attributes :l attributes = count, id, coord1, coord2, coord3 count = # of atoms in chunk id = original chunk IDs before compression by "compute chunk/atom"_compute_chunk_atom.html coord123 = coordinates for spatial bins calculated by "compute chunk/atom"_compute_chunk_atom.html :pre :ule [Examples:] compute 1 all property/chunk count compute 1 all property/chunk ID coord1 :pre [Description:] Define a computation that stores the specified attributes of chunks of atoms. In LAMMPS, chunks are collections of atoms defined by a "compute chunk/atom"_compute_chunk_atom.html 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 "compute -chunk/atom"_compute_chunk_atom.html doc page and ""Section_howto -23"_Section_howto.html#howto_23 for details of how chunks can be +chunk/atom"_compute_chunk_atom.html doc page and "Section +6.23"_Section_howto.html#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 and stores the specified attributes of chunks as global data so they can be accessed by other "output commands"_Section_howto.html#howto_15 and used in conjunction with other commands that generate per-chunk data, such as "compute com/chunk"_compute_com_chunk.html or "compute msd/chunk"_compute_msd_chunk.html. Note that only atoms in the specified group contribute to the calculation of the {count} attribute. The "compute chunk/atom"_compute_chunk_atom.html command defines its own group; atoms will have a chunk ID = 0 if they are not in that group, signifying they are not assigned to a chunk, and will thus also not contribute to this calculation. You can specify the "all" group for this command if you simply want to include atoms with non-zero chunk IDs. The {count} attribute is the number of atoms in the chunk. The {id} attribute stores the original chunk ID for each chunk. It can only be used if the {compress} keyword was set to {yes} for the "compute chunk/atom"_compute_chunk_atom.html command referenced by chunkID. This means that the original chunk IDs (e.g. molecule IDs) will have been compressed to remove chunk IDs with no atoms assigned to them. Thus a compresed chunk ID of 3 may correspond to an original chunk ID (molecule ID in this case) of 415. The {id} attribute will then be 415 for the 3rd chunk. The {coordN} attributes can only be used if a {binning} style was used in the "compute chunk/atom"_compute_chunk_atom.html command referenced by chunkID. For {bin/1d}, {bin/2d}, and {bin/3d} styles the attribute is the center point of the bin in the corresponding dimension. Style {bin/1d} only defines a {coord1} attribute. Style {bin/2d} adds a {coord2} attribute. Style {bin/3d} adds a {coord3} attribute. Note that if the value of the {units} keyword used in the "compute chunk/atom command"_compute_chunk_atom.html is {box} or {lattice}, the {coordN} attributes will be in distance "units"_units.html. If the value of the {units} keyword is {reduced}, the {coordN} attributes will be in unitless reduced units (0-1). The simplest way to output the results of the compute property/chunk calculation to a file is to use the "fix ave/time"_fix_ave_time.html command, for example: compute cc1 all chunk/atom molecule compute myChunk1 all property/chunk cc1 count compute myChunk2 all com/chunk cc1 fix 1 all ave/time 100 1 100 c_myChunk1 c_myChunk2\[*\] file tmp.out mode vector :pre [Output info:] This compute calculates a global vector or global array depending on the number of input values. The length of the vector or number of rows in the array is the number of chunks. This compute calculates a global vector or global array where the number of rows = the number of chunks {Nchunk} as calculated by the specified "compute chunk/atom"_compute_chunk_atom.html command. If a single input is specified, a global vector is produced. If two or more inputs are specified, a global array is produced where the number of columns = the number of inputs. The vector or array can be accessed by any command that uses global values from a compute as input. See "this section"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The vector or array values are "intensive". The values will be unitless or in the units discussed above. [Restrictions:] none [Related commands:] "fix ave/chunk"_fix_ave_chunk.html [Default:] none diff --git a/doc/src/compute_smd_ulsph_strain_rate.txt b/doc/src/compute_smd_ulsph_strain_rate.txt index 3f32e4391..eb9318e07 100644 --- a/doc/src/compute_smd_ulsph_strain_rate.txt +++ b/doc/src/compute_smd_ulsph_strain_rate.txt @@ -1,56 +1,56 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute smd/ulsph/strain/rate command :h3 [Syntax:] compute ID group-ID smd/ulsph/strain/rate :pre ID, group-ID are documented in "compute"_compute.html command smd/ulsph/strain/rate = style name of this compute command :ul [Examples:] compute 1 all smd/ulsph/strain/rate :pre [Description:] Define a computation that outputs the rate of the logarithmic strain tensor for particles interacting via the updated Lagrangian SPH pair style. See "this PDF guide"_USER/smd/SMD_LAMMPS_userguide.pdf to using Smooth Mach Dynamics in LAMMPS. [Output info:] This compute calculates a per-particle vector of vectors (tensors), which can be accessed by any command that uses per-particle values -from a compute as input. See "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The values will be given in "units"_units.html of one over time. The per-particle vector has 6 entries, corresponding to the xx, yy, zz, xy, xz, yz components of the symmetric strain rate tensor. [Restrictions:] This compute is part of the USER-SMD package. It is only enabled if LAMMPS was built with that package. See the "Making LAMMPS"_Section_start.html#start_2 section for more info. This compute can only be used for particles which interact with the updated Lagrangian SPH pair style. [Related commands:] "compute smd/tlsph/strain/rate"_compute_smd_tlsph_strain_rate.html [Default:] none diff --git a/doc/src/compute_smd_ulsph_stress.txt b/doc/src/compute_smd_ulsph_stress.txt index 4d1994e37..115a4d14b 100644 --- a/doc/src/compute_smd_ulsph_stress.txt +++ b/doc/src/compute_smd_ulsph_stress.txt @@ -1,58 +1,58 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute smd/ulsph/stress command :h3 [Syntax:] compute ID group-ID smd/ulsph/stress :pre ID, group-ID are documented in "compute"_compute.html command smd/ulsph/stress = style name of this compute command :ul [Examples:] compute 1 all smd/ulsph/stress :pre [Description:] Define a computation that outputs the Cauchy stress tensor. See "this PDF guide"_USER/smd/SMD_LAMMPS_userguide.pdf to using Smooth Mach Dynamics in LAMMPS. [Output info:] This compute calculates a per-particle vector of vectors (tensors), which can be accessed by any command that uses per-particle values -from a compute as input. See "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The values will be given in "units"_units.html of pressure. The per-particle vector has 7 entries. The first six entries correspond to the xx, yy, zz, xy, xz, yz components of the symmetric Cauchy stress tensor. The seventh entry is the second invariant of the stress tensor, i.e., the von Mises equivalent stress. [Restrictions:] This compute is part of the USER-SMD package. It is only enabled if LAMMPS was built with that package. See the "Making LAMMPS"_Section_start.html#start_3 section for more info. This compute can only be used for particles which interact with the updated Lagrangian SPH pair style. [Related commands:] "compute smd/ulsph/strain"_compute_smd_ulsph_strain.html, "compute smd/ulsph/strain/rate"_compute_smd_ulsph_strain_rate.html "compute smd/tlsph/stress"_compute_smd_tlsph_stress.html [Default:] none diff --git a/doc/src/compute_sna_atom.txt b/doc/src/compute_sna_atom.txt index b8e3f9b73..7f10fdbcc 100644 --- a/doc/src/compute_sna_atom.txt +++ b/doc/src/compute_sna_atom.txt @@ -1,241 +1,241 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute sna/atom command :h3 compute snad/atom command :h3 compute snav/atom command :h3 [Syntax:] compute ID group-ID sna/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... compute ID group-ID snad/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... compute ID group-ID snav/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... :pre ID, group-ID are documented in "compute"_compute.html command :ulb,l sna/atom = style name of this compute command :l rcutfac = scale factor applied to all cutoff radii (positive real) :l rfac0 = parameter in distance to angle conversion (0 < rcutfac < 1) :l twojmax = band limit for bispectrum components (non-negative integer) :l R_1, R_2,... = list of cutoff radii, one for each type (distance units) :l w_1, w_2,... = list of neighbor weights, one for each type :l zero or more keyword/value pairs may be appended :l keyword = {diagonal} or {rmin0} or {switchflag} :l {diagonal} value = {0} or {1} or {2} or {3} {0} = all j1, j2, j <= twojmax, j2 <= j1 {1} = subset satisfying j1 == j2 {2} = subset satisfying j1 == j2 == j3 {3} = subset satisfying j2 <= j1 <= j {rmin0} value = parameter in distance to angle conversion (distance units) {switchflag} value = {0} or {1} {0} = do not use switching function {1} = use switching function :pre :ule [Examples:] compute b all sna/atom 1.4 0.99363 6 2.0 2.4 0.75 1.0 diagonal 3 rmin0 0.0 compute db all sna/atom 1.4 0.95 6 2.0 1.0 compute vb all sna/atom 1.4 0.95 6 2.0 1.0 :pre [Description:] Define a computation that calculates a set of bispectrum components for each atom in a group. Bispectrum components of an atom are order parameters characterizing the radial and angular distribution of neighbor atoms. The detailed mathematical definition is given in the paper by Thompson et al. "(Thompson)"_#Thompson2014 The position of a neighbor atom {i'} relative to a central atom {i} is a point within the 3D ball of radius {R_ii' = rcutfac*(R_i + R_i')} Bartok et al. "(Bartok)"_#Bartok2010, proposed mapping this 3D ball onto the 3-sphere, the surface of the unit ball in a four-dimensional space. The radial distance {r} within {R_ii'} is mapped on to a third polar angle {theta0} defined by, :c,image(Eqs/compute_sna_atom1.jpg) In this way, all possible neighbor positions are mapped on to a subset of the 3-sphere. Points south of the latitude {theta0max=rfac0*Pi} are excluded. The natural basis for functions on the 3-sphere is formed by the 4D hyperspherical harmonics {U^j_m,m'(theta, phi, theta0).} These functions are better known as {D^j_m,m',} the elements of the Wigner {D}-matrices "(Meremianin"_#Meremianin2006, "Varshalovich)"_#Varshalovich1987. The density of neighbors on the 3-sphere can be written as a sum of Dirac-delta functions, one for each neighbor, weighted by species and radial distance. Expanding this density function as a generalized Fourier series in the basis functions, we can write each Fourier coefficient as :c,image(Eqs/compute_sna_atom2.jpg) The {w_i'} neighbor weights are dimensionless numbers that are chosen to distinguish atoms of different types, while the central atom is arbitrarily assigned a unit weight. The function {fc(r)} ensures that the contribution of each neighbor atom goes smoothly to zero at {R_ii'}: :c,image(Eqs/compute_sna_atom4.jpg) The expansion coefficients {u^j_m,m'} are complex-valued and they are not directly useful as descriptors, because they are not invariant under rotation of the polar coordinate frame. However, the following scalar triple products of expansion coefficients can be shown to be real-valued and invariant under rotation "(Bartok)"_#Bartok2010. :c,image(Eqs/compute_sna_atom3.jpg) The constants {H^jmm'_j1m1m1'_j2m2m2'} are coupling coefficients, analogous to Clebsch-Gordan coefficients for rotations on the 2-sphere. These invariants are the components of the bispectrum and these are the quantities calculated by the compute {sna/atom}. They characterize the strength of density correlations at three points on the 3-sphere. The j2=0 subset form the power spectrum, which characterizes the correlations of two points. The lowest-order components describe the coarsest features of the density function, while higher-order components reflect finer detail. Note that the central atom is included in the expansion, so three point-correlations can be either due to three neighbors, or two neighbors and the central atom. Compute {snad/atom} calculates the derivative of the bispectrum components summed separately for each atom type: :c,image(Eqs/compute_sna_atom5.jpg) The sum is over all atoms {i'} of atom type {I}. For each atom {i}, this compute evaluates the above expression for each direction, each atom type, and each bispectrum component. See section below on output for a detailed explanation. Compute {snav/atom} calculates the virial contribution due to the derivatives: :c,image(Eqs/compute_sna_atom6.jpg) Again, the sum is over all atoms {i'} of atom type {I}. For each atom {i}, this compute evaluates the above expression for each of the six virial components, each atom type, and each bispectrum component. See section below on output for a detailed explanation. The value of all bispectrum components will be zero for atoms not in the group. Neighbor atoms not in the group do not contribute to the bispectrum of atoms in the 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. The argument {rcutfac} is a scale factor that controls the ratio of atomic radius to radial cutoff distance. The argument {rfac0} and the optional keyword {rmin0} define the linear mapping from radial distance to polar angle {theta0} on the 3-sphere. The argument {twojmax} and the keyword {diagonal} define which bispectrum components are generated. See section below on output for a detailed explanation of the number of bispectrum components and the ordered in which they are listed The keyword {switchflag} can be used to turn off the switching function. NOTE: If you have a bonded system, then the settings of "special_bonds"_special_bonds.html command can remove pairwise interactions between atoms in the same bond, angle, or dihedral. This is the default setting for the "special_bonds"_special_bonds.html 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 calculation. One way to get around this, is to write a dump file, and use the "rerun"_rerun.html command to compute the bispectrum components for snapshots in the dump file. The rerun script can use a "special_bonds"_special_bonds.html command that includes all pairs in the neighbor list. ;line [Output info:] Compute {sna/atom} calculates a per-atom array, each column corresponding to a particular bispectrum component. The total number of columns and the identities of the bispectrum component contained in each column depend on the values of {twojmax} and {diagonal}, as described by the following piece of python code: for j1 in range(0,twojmax+1): if(diagonal==2): print j1/2.,j1/2.,j1/2. elif(diagonal==1): for j in range(0,min(twojmax,2*j1)+1,2): print j1/2.,j1/2.,j/2. elif(diagonal==0): for j2 in range(0,j1+1): for j in range(j1-j2,min(twojmax,j1+j2)+1,2): print j1/2.,j2/2.,j/2. elif(diagonal==3): for j2 in range(0,j1+1): for j in range(j1-j2,min(twojmax,j1+j2)+1,2): if (j>=j1): print j1/2.,j2/2.,j/2. :pre Compute {snad/atom} evaluates a per-atom array. The columns are arranged into {ntypes} blocks, listed in order of atom type {I}. Each block contains three sub-blocks corresponding to the {x}, {y}, and {z} components of the atom position. Each of these sub-blocks contains one column for each bispectrum component, the same as for compute {sna/atom} Compute {snav/atom} evaluates a per-atom array. The columns are arranged into {ntypes} blocks, listed in order of atom type {I}. Each block contains six sub-blocks corresponding to the {xx}, {yy}, {zz}, {yz}, {xz}, and {xy} components of the virial tensor in Voigt notation. Each of these sub-blocks contains one column for each bispectrum component, the same as for compute {sna/atom} These values can be accessed by any command that uses per-atom values -from a compute as input. See "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. [Restrictions:] These computes are part of the SNAP package. They are only enabled if LAMMPS was built with that package. See the "Making LAMMPS"_Section_start.html#start_3 section for more info. [Related commands:] "pair_style snap"_pair_snap.html [Default:] The optional keyword defaults are {diagonal} = 0, {rmin0} = 0, {switchflag} = 1. :line :link(Thompson2014) [(Thompson)] Thompson, Swiler, Trott, Foiles, Tucker, under review, preprint available at "arXiv:1409.3880"_http://arxiv.org/abs/1409.3880 :link(Bartok2010) [(Bartok)] Bartok, Payne, Risi, Csanyi, Phys Rev Lett, 104, 136403 (2010). :link(Meremianin2006) [(Meremianin)] Meremianin, J. Phys. A, 39, 3099 (2006). :link(Varshalovich1987) [(Varshalovich)] Varshalovich, Moskalev, Khersonskii, Quantum Theory of Angular Momentum, World Scientific, Singapore (1987). diff --git a/doc/src/compute_stress_atom.txt b/doc/src/compute_stress_atom.txt index 35e586068..274947843 100644 --- a/doc/src/compute_stress_atom.txt +++ b/doc/src/compute_stress_atom.txt @@ -1,164 +1,164 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute stress/atom command :h3 [Syntax:] compute ID group-ID stress/atom temp-ID keyword ... :pre ID, group-ID are documented in "compute"_compute.html command stress/atom = style name of this compute command temp-ID = ID of compute that calculates temperature, can be NULL if not needed zero or more keywords may be appended keyword = {ke} or {pair} or {bond} or {angle} or {dihedral} or {improper} or {kspace} or {fix} or {virial} :ul [Examples:] compute 1 mobile stress/atom NULL compute 1 mobile stress/atom myRamp compute 1 all stress/atom NULL pair bond :pre [Description:] Define a computation that computes the symmetric per-atom stress tensor for each atom in a group. The tensor for each atom has 6 components and is stored as a 6-element vector in the following order: xx, yy, zz, xy, xz, yz. See the "compute pressure"_compute_pressure.html command if you want the stress tensor (pressure) of the entire system. The stress tensor for atom {I} is given by the following formula, where {a} and {b} take on values x,y,z to generate the 6 components of the symmetric tensor: :c,image(Eqs/stress_tensor.jpg) The first term is a kinetic energy contribution for atom {I}. See details below on how the specified {temp-ID} can affect the velocities used in this calculation. The second term is a pairwise energy contribution where {n} loops over the {Np} neighbors of atom {I}, {r1} and {r2} are the positions of the 2 atoms in the pairwise interaction, and {F1} and {F2} are the forces on the 2 atoms resulting from the pairwise interaction. The third term is a bond contribution of similar form for the {Nb} bonds which atom {I} is part of. There are similar terms for the {Na} angle, {Nd} dihedral, and {Ni} improper interactions atom {I} is part of. There is also a term for the KSpace contribution from long-range Coulombic interactions, if defined. Finally, there is a term for the {Nf} "fixes"_fix.html that apply internal constraint forces to atom {I}. Currently, only the "fix shake"_fix_shake.html and "fix rigid"_fix_rigid.html commands contribute to this term. As the coefficients in the formula imply, a virial contribution produced by a small set of atoms (e.g. 4 atoms in a dihedral or 3 atoms in a Tersoff 3-body interaction) is assigned in equal portions to each atom in the set. E.g. 1/4 of the dihedral virial to each of the 4 atoms, or 1/3 of the fix virial due to SHAKE constraints applied to atoms in a a water molecule via the "fix shake"_fix_shake.html command. If no extra keywords are listed, all of the terms in this formula are included in the per-atom stress tensor. If any extra keywords are listed, only those terms are summed to compute the tensor. The {virial} keyword means include all terms except the kinetic energy {ke}. Note that the stress for each atom is due to its interaction with all other atoms in the simulation, not just with other atoms in the group. Details of how LAMMPS computes the virial for individual atoms for either pairwise or manybody potentials, and including the effects of periodic boundary conditions is discussed in "(Thompson)"_#Thompson. The basic idea for manybody potentials is to treat each component of the force computation between a small cluster of atoms in the same manner as in the formula above for bond, angle, dihedral, etc interactions. Namely the quantity R dot F is summed over the atoms in the interaction, with the R vectors unwrapped by periodic boundaries so that the cluster of atoms is close together. The total contribution for the cluster interaction is divided evenly among those atoms. The "dihedral_style charmm"_dihedral_charmm.html style calculates pairwise interactions between 1-4 atoms. The virial contribution of these terms is included in the pair virial, not the dihedral virial. The KSpace contribution is calculated using the method in "(Heyes)"_#Heyes for the Ewald method and by the methodology described in "(Sirk)"_#Sirk for PPPM. The choice of KSpace solver is specified by the "kspace_style pppm"_kspace_style.html command. Note that for PPPM, the calcluation requires 6 extra FFTs each timestep that per-atom stress is calculated. Thus it can significantly increase the cost of the PPPM calculation if it is needed on a large fraction of the simulation timesteps. The {temp-ID} argument can be used to affect the per-atom velocities used in the kinetic energy contribution to the total stress. If the kinetic energy is not included in the stress, than the temperature compute is not used and can be specified as NULL. If the kinetic energy is included and you wish to use atom velocities as-is, then {temp-ID} can also be specified as NULL. If desired, the specified temperature compute can be one that subtracts off a bias to leave each atom with only a thermal velocity to use in the formula above, e.g. by subtracting a background streaming velocity. See the doc pages for individual "compute commands"_compute.html to determine which ones include a bias. :line Note that as defined in the formula, per-atom stress is the negative of the per-atom pressure tensor. It is also really a stress*volume formulation, meaning the computed quantity is in units of pressure*volume. It would need to be divided by a per-atom volume to have units of stress (pressure), but an individual atom's volume is not well defined or easy to compute in a deformed solid or a liquid. See the "compute voronoi/atom"_compute_voronoi_atom.html command for one possible way to estimate a per-atom volume. Thus, if the diagonal components of the per-atom stress tensor are summed for all atoms in the system and the sum is divided by dV, where d = dimension and V is the volume of the system, the result should be -P, where P is the total pressure of the system. These lines in an input script for a 3d system should yield that result. I.e. the last 2 columns of thermo output will be the same: compute peratom all stress/atom NULL compute p all reduce sum c_peratom\[1\] c_peratom\[2\] c_peratom\[3\] variable press equal -(c_p\[1\]+c_p\[2\]+c_p\[3\])/(3*vol) thermo_style custom step temp etotal press v_press :pre [Output info:] This compute calculates a per-atom array with 6 columns, which can be accessed by indices 1-6 by any command that uses per-atom values from -a compute as input. See "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The per-atom array values will be in pressure*volume "units"_units.html as discussed above. [Restrictions:] none [Related commands:] "compute pe"_compute_pe.html, "compute pressure"_compute_pressure.html [Default:] none :line :link(Heyes) [(Heyes)] Heyes, Phys Rev B 49, 755 (1994), :link(Sirk) [(Sirk)] Sirk, Moore, Brown, J Chem Phys, 138, 064505 (2013). :link(Thompson) [(Thompson)] Thompson, Plimpton, Mattson, J Chem Phys, 131, 154107 (2009). diff --git a/doc/src/compute_temp_chunk.txt b/doc/src/compute_temp_chunk.txt index 826d0f6e0..d565c9513 100644 --- a/doc/src/compute_temp_chunk.txt +++ b/doc/src/compute_temp_chunk.txt @@ -1,237 +1,237 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute temp/chunk command :h3 [Syntax:] compute ID group-ID temp/chunk chunkID value1 value2 ... keyword value ... :pre ID, group-ID are documented in "compute"_compute.html command :ulb,l temp/chunk = style name of this compute command :l chunkID = ID of "compute chunk/atom"_compute_chunk_atom.html command :l zero or more values can be listed as value1,value2,etc :l value = {temp} or {kecom} or {internal} :l temp = temperature of each chunk kecom = kinetic energy of each chunk based on velocity of center of mass internal = internal kinetic energy of each chunk :pre zero or more keyword/value pairs may be appended :l keyword = {com} or {bias} or {adof} or {cdof} :l {com} value = {yes} or {no} yes = subtract center-of-mass velocity from each chunk before calculating temperature no = do not subtract center-of-mass velocity {bias} value = bias-ID bias-ID = ID of a temperature compute that removes a velocity bias {adof} value = dof_per_atom dof_per_atom = define this many degrees-of-freedom per atom {cdof} value = dof_per_chunk dof_per_chunk = define this many degrees-of-freedom per chunk :pre :ule [Examples:] compute 1 fluid temp/chunk molchunk compute 1 fluid temp/chunk molchunk temp internal compute 1 fluid temp/chunk molchunk bias tpartial adof 2.0 :pre [Description:] Define a computation that calculates the temperature of a group of atoms that are also in chunks, after optionally subtracting out the center-of-mass velocity of each chunk. By specifying optional values, it can also calulate the per-chunk temperature or energies of the multiple chunks of atoms. In LAMMPS, chunks are collections of atoms defined by a "compute chunk/atom"_compute_chunk_atom.html 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 "compute -chunk/atom"_compute_chunk_atom.html doc page and ""Section_howto -23"_Section_howto.html#howto_23 for details of how chunks can be +chunk/atom"_compute_chunk_atom.html doc page and "Section +6.23"_Section_howto.html#howto_23 for details of how chunks can be defined and examples of how they can be used to measure properties of a system. The temperature is calculated by the formula KE = DOF/2 k T, where KE = total kinetic energy of all atoms assigned to chunks (sum of 1/2 m v^2), DOF = the total number of degrees of freedom for those atoms, k = Boltzmann constant, and T = temperature. The DOF is calculated as N*adof + Nchunk*cdof, where N = number of atoms contributing to the KE, adof = degrees of freedom per atom, and cdof = degrees of freedom per chunk. By default adof = 2 or 3 = dimensionality of system, as set via the "dimension"_dimension.html command, and cdof = 0.0. This gives the usual formula for temperature. A kinetic energy tensor, stored as a 6-element vector, is also calculated by this compute for use in the computation of a pressure tensor. The formula for the components of the tensor is the same as the above formula, except that v^2 is replaced by vx*vy for the xy component, etc. The 6 components of the vector are ordered xx, yy, zz, xy, xz, yz. Note that the number of atoms contributing to the temperature is calculated each time the temperature is evaluated since it is assumed the atoms may be dynamically assigned to chunks. Thus there is no need to use the {dynamic} option of the "compute_modify"_compute_modify.html command for this compute style. If any optional values are specified, then per-chunk quantities are also calculated and stored in a global array, as described below. The {temp} value calculates the temperature for each chunk by the formula KE = DOF/2 k T, where KE = total kinetic energy of the chunk of atoms (sum of 1/2 m v^2), DOF = the total number of degrees of freedom for all atoms in the chunk, k = Boltzmann constant, and T = temperature. The DOF in this case is calculated as N*adof + cdof, where N = number of atoms in the chunk, adof = degrees of freedom per atom, and cdof = degrees of freedom per chunk. By default adof = 2 or 3 = dimensionality of system, as set via the "dimension"_dimension.html command, and cdof = 0.0. This gives the usual formula for temperature. The {kecom} value calculates the kinetic energy of each chunk as if all its atoms were moving with the velocity of the center-of-mass of the chunk. The {internal} value calculates the internal kinetic energy of each chunk. The interal KE is summed over the atoms in the chunk using an internal "thermal" velocity for each atom, which is its velocity minus the center-of-mass velocity of the chunk. :line Note that currently the global and per-chunk temperatures calculated by this compute only include translational degrees of freedom for each atom. No rotational degrees of freedom are included for finite-size particles. Also no degrees of freedom are subtracted for any velocity bias or constraints that are applied, such as "compute temp/partial"_compute_temp_partial.html, or "fix shake"_fix_shake.html or "fix rigid"_fix_rigid.html. This is because those degrees of freedom (e.g. a constrained bond) could apply to sets of atoms that are both included and excluded from a specific chunk, and hence the concept is somewhat ill-defined. In some cases, you can use the {adof} and {cdof} keywords to adjust the calculated degress of freedom appropriately, as explained below. Note that the per-chunk temperature calulated by this compute and the "fix ave/chunk temp"_fix_ave_chunk.html command can be different. This compute calculates the temperature for each chunk for a single snapshot. Fix ave/chunk can do that but can also time average those values over many snapshots, or it can compute a temperature as if the atoms in the chunk on different timesteps were collected together as one set of atoms to calculate their temperature. This compute allows the center-of-mass velocity of each chunk to be subtracted before calculating the temperature; fix ave/chunk does not. NOTE: Only atoms in the specified group contribute to the calculations performed by this compute. The "compute chunk/atom"_compute_chunk_atom.html command defines its own group; atoms will have a chunk ID = 0 if they are not in that group, signifying they are not assigned to a chunk, and will thus also not contribute to this calculation. You can specify the "all" group for this command if you simply want to include atoms with non-zero chunk IDs. The simplest way to output the per-chunk results of the compute temp/chunk calculation to a file is to use the "fix ave/time"_fix_ave_time.html command, for example: compute cc1 all chunk/atom molecule compute myChunk all temp/chunk cc1 temp fix 1 all ave/time 100 1 100 c_myChunk file tmp.out mode vector :pre :line The keyword/value option pairs are used in the following ways. The {com} keyword can be used with a value of {yes} to subtract the velocity of the center-of-mass for each chunk from the velocity of the atoms in that chunk, before calculating either the global or per-chunk temperature. This can be useful if the atoms are streaming or otherwise moving collectively, and you wish to calculate only the thermal temperature. For the {bias} keyword, {bias-ID} refers to the ID of a temperature compute that removes a "bias" velocity from each atom. This also allows calculation of the global or per-chunk temperature using only the thermal temperature of atoms in each chunk after the translational kinetic energy components have been altered in a prescribed way, e.g. to remove a velocity profile. It also applies to the calculation of the other per-chunk values, such as {kecom} or {internal}, which involve the center-of-mass velocity of each chunk, which is calculated after the velocity bias is removed from each atom. Note that the temperature compute will apply its bias globally to the entire system, not on a per-chunk basis. The {adof} and {cdof} keywords define the values used in the degree of freedom (DOF) formulas used for the global or per-chunk temperature, as described above. They can be used to calculate a more appropriate temperature for some kinds of chunks. Here are 3 examples: If spatially binned chunks contain some number of water molecules and "fix shake"_fix_shake.html is used to make each molecule rigid, then you could calculate a temperature with 6 degrees of freedom (DOF) (3 translational, 3 rotational) per molecule by setting {adof} to 2.0. If "compute temp/partial"_compute_temp_partial.html is used with the {bias} keyword to only allow the x component of velocity to contribute to the temperature, then {adof} = 1.0 would be appropriate. If each chunk consists of a large molecule, with some number of its bonds constrained by "fix shake"_fix_shake.html or the entire molecule by "fix rigid/small"_fix_rigid.html, {adof} = 0.0 and {cdof} could be set to the remaining degrees of freedom for the entire molecule (entire chunk in this case), e.g. 6 for 3d, or 3 for 2d, for a rigid molecule. :line [Output info:] This compute calculates a global scalar (the temperature) and a global vector of length 6 (KE tensor), which can be accessed by indices 1-6. These values can be used by any command that uses global scalar or vector values from a compute as input. See "this section"_Section_howto.html#howto_15 for an overview of LAMMPS output options. This compute also optionally calculates a global array, if one or more of the optional values are specified. The number of rows in the array = the number of chunks {Nchunk} as calculated by the specified "compute chunk/atom"_compute_chunk_atom.html command. The number of columns is the number of specifed values (1 or more). These values can be accessed by any command that uses global array values from a -compute as input. Again, see "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +compute as input. Again, see "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The scalar value calculated by this compute is "intensive". The vector values are "extensive". The array values are "intensive". The scalar value will be in temperature "units"_units.html. The vector values will be in energy "units"_units.html. The array values will be in temperature "units"_units.html for the {temp} value, and in energy "units"_units.html for the {kecom} and {internal} values. [Restrictions:] The {com} and {bias} keywords cannot be used together. [Related commands:] "compute temp"_compute_temp.html, "fix ave/chunk temp"_fix_ave_chunk.html [Default:] The option defaults are com no, no bias, adof = dimensionality of the system (2 or 3), and cdof = 0.0. diff --git a/doc/src/compute_temp_cs.txt b/doc/src/compute_temp_cs.txt index 7170ef951..46846d6ee 100644 --- a/doc/src/compute_temp_cs.txt +++ b/doc/src/compute_temp_cs.txt @@ -1,119 +1,119 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute temp/cs command :h3 [Syntax:] compute ID group-ID temp/cs group1 group2 :pre ID, group-ID are documented in "compute"_compute.html command temp/cs = style name of this compute command group1 = group-ID of either cores or shells group2 = group-ID of either shells or cores :ul [Examples:] compute oxygen_c-s all temp/cs O_core O_shell compute core_shells all temp/cs cores shells :pre [Description:] Define a computation that calculates the temperature of a system based on the center-of-mass velocity of atom pairs that are bonded to each other. This compute is designed to be used with the adiabatic core/shell model of "(Mitchell and Finchham)"_#MitchellFinchham. See "Section 6.25"_Section_howto.html#howto_25 of the manual for an overview of the model as implemented in LAMMPS. Specifically, this compute enables correct temperature calculation and thermostatting of core/shell pairs where it is desirable for the internal degrees of freedom of the core/shell pairs to not be influenced by a thermostat. A compute of this style can be used by any command that computes a temperature via "fix_modify"_fix_modify.html e.g. "fix temp/rescale"_fix_temp_rescale.html, "fix npt"_fix_nh.html, etc. Note that this compute does not require all ions to be polarized, hence defined as core/shell pairs. One can mix core/shell pairs and ions without a satellite particle if desired. The compute will consider the non-polarized ions according to the physical system. For this compute, core and shell particles are specified by two respective group IDs, which can be defined using the "group"_group.html command. The number of atoms in the two groups must be the same and there should be one bond defined between a pair of atoms in the two groups. Non-polarized ions which might also be included in the treated system should not be included into either of these groups, they are taken into account by the {group-ID} (2nd argument) of the compute. The temperature is calculated by the formula KE = dim/2 N k T, where KE = total kinetic energy of the group of atoms (sum of 1/2 m v^2), dim = 2 or 3 = dimensionality of the simulation, N = number of atoms in the group, k = Boltzmann constant, and T = temperature. Note that the velocity of each core or shell atom used in the KE calculation is the velocity of the center-of-mass (COM) of the core/shell pair the atom is part of. A kinetic energy tensor, stored as a 6-element vector, is also calculated by this compute for use in the computation of a pressure tensor. The formula for the components of the tensor is the same as the above formula, except that v^2 is replaced by vx*vy for the xy component, etc. The 6 components of the vector are ordered xx, yy, zz, xy, xz, yz. In contrast to the temperature, the velocity of each core or shell atom is taken individually. The change this fix makes to core/shell atom velocities is essentially computing the temperature after a "bias" has been removed from the velocity of the atoms. This "bias" is the velocity of the atom relative to the COM velocity of the core/shell pair. If this compute is used with a fix command that performs thermostatting then this bias will be subtracted from each atom, thermostatting of the remaining COM velocity will be performed, and the bias will be added back in. This means the thermostating will effectively be performed on the core/shell pairs, instead of on the individual core and shell atoms. Thermostatting fixes that work in this way include "fix nvt"_fix_nh.html, "fix temp/rescale"_fix_temp_rescale.html, "fix temp/berendsen"_fix_temp_berendsen.html, and "fix langevin"_fix_langevin.html. The internal energy of core/shell pairs can be calculated by the "compute temp/chunk"_compute_temp_chunk.html command, if chunks are -defined as core/shell pairs. See "Section_howto -25"_Section_howto.html#howto_25 for more discussion on how to do this. +defined as core/shell pairs. See "Section +6.25"_Section_howto.html#howto_25 for more discussion on how to do this. [Output info:] This compute calculates a global scalar (the temperature) and a global vector of length 6 (KE tensor), which can be accessed by indices 1-6. These values can be used by any command that uses global scalar or vector values from a compute as input. The scalar value calculated by this compute is "intensive". The vector values are "extensive". The scalar value will be in temperature "units"_units.html. The vector values will be in energy "units"_units.html. [Restrictions:] The number of core/shell pairs contributing to the temperature is assumed to be constant for the duration of the run. No fixes should be used which generate new molecules or atoms during a simulation. [Related commands:] "compute temp"_compute_temp.html, "compute temp/chunk"_compute_temp_chunk.html [Default:] none :line :link(MitchellFinchham) [(Mitchell and Finchham)] Mitchell, Finchham, J Phys Condensed Matter, 5, 1031-1038 (1993). diff --git a/doc/src/compute_ti.txt b/doc/src/compute_ti.txt index 1fbbb592f..71b62281d 100644 --- a/doc/src/compute_ti.txt +++ b/doc/src/compute_ti.txt @@ -1,137 +1,137 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute ti command :h3 [Syntax:] compute ID group ti keyword args ... :pre ID, group-ID are documented in "compute"_compute.html command :ulb,l ti = style name of this compute command :l one or more attribute/arg pairs may be appended :l keyword = pair style (lj/cut, gauss, born, etc) or {tail} or {kspace} :l pair style args = atype v_name1 v_name2 atype = atom type (see asterisk form below) v_name1 = variable with name1 that is energy scale factor and function of lambda v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda {tail} args = atype v_name1 v_name2 atype = atom type (see asterisk form below) v_name1 = variable with name1 that is energy tail correction scale factor and function of lambda v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda {kspace} args = atype v_name1 v_name2 atype = atom type (see asterisk form below) v_name1 = variable with name1 that is K-Space scale factor and function of lambda v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda :pre :ule [Examples:] compute 1 all ti lj/cut 1 v_lj v_dlj coul/long 2 v_c v_dc kspace 1 v_ks v_dks compute 1 all ti lj/cut 1*3 v_lj v_dlj coul/long * v_c v_dc kspace * v_ks v_dks :pre [Description:] Define a computation that calculates the derivative of the interaction potential with respect to {lambda}, the coupling parameter used in a thermodynamic integration. This derivative can be used to infer a free energy difference resulting from an alchemical simulation, as described in "Eike"_#Eike. Typically this compute will be used in conjunction with the "fix adapt"_fix_adapt.html command which can perform alchemical transformations by adusting the strength of an interaction potential as a simulation runs, as defined by one or more "pair_style"_pair_style.html or "kspace_style"_kspace_style.html commands. This scaling is done via a prefactor on the energy, forces, virial calculated by the pair or K-Space style. The prefactor is often a function of a {lambda} parameter which may be adjusted from 0 to 1 (or vice versa) over the course of a "run"_run.html. The time-dependent adjustment is what the "fix adapt"_fix_adapt.html command does. Assume that the unscaled energy of a pair_style or kspace_style is given by U. Then the scaled energy is Us = f(lambda) U :pre where f() is some function of lambda. What this compute calculates is dUs / d(lambda) = U df(lambda)/dlambda = Us / f(lambda) df(lambda)/dlambda :pre which is the derivative of the system's scaled potential energy Us with respect to {lambda}. To perform this calculation, you provide one or more atom types as {atype}. {Atype} can be specified in one of two ways. An explicit numeric values can be used, as in the 1st example above. Or a wildcard asterisk can be used in place of or in conjunction with the {atype} argument to select multiple 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). You also specify two functions, as "equal-style variables"_variable.html. The first is specified as {v_name1}, where {name1} is the name of the variable, and is f(lambda) in the notation above. The second is specified as {v_name2}, where {name2} is the name of the variable, and is df(lambda) / dlambda in the notation above. I.e. it is the analytic derivative of f() with respect to lambda. Note that the {name1} variable is also typically given as an argument to the "fix adapt"_fix_adapt.html command. An alchemical simulation may use several pair potentials together, invoked via the "pair_style hybrid or hybrid/overlay"_pair_hybrid.html command. The total dUs/dlambda for the overall system is calculated as the sum of each contributing term as listed by the keywords in the compute ti command. Individual pair potentials can be listed, which will be sub-styles in the hybrid case. You can also include a K-space term via the {kspace} keyword. You can also include a pairwise long-range tail correction to the energy via the {tail} keyword. For each term you can specify a different (or the same) scale factor by the two variables that you list. Again, these will typically correspond toe the scale factors applied to these various potentials and the K-Space contribution via the "fix adapt"_fix_adapt.html command. More details about the exact functional forms for the computation of du/dl can be found in the paper by "Eike"_#Eike. :line [Output info:] This compute calculates a global scalar, namely dUs/dlambda. This value can be used by any command that uses a global scalar value from -a compute as input. See "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +a compute as input. See "Section +6.15"_Section_howto.html#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 "units"_units.html. [Restrictions:] This compute is part of the MISC package. It is only enabled if LAMMPS was built with that package. See the "Making LAMMPS"_Section_start.html#start_3 section for more info. [Related commands:] "fix adapt"_fix_adapt.html [Default:] none :line :link(Eike) [(Eike)] Eike and Maginn, Journal of Chemical Physics, 124, 164503 (2006). diff --git a/doc/src/compute_torque_chunk.txt b/doc/src/compute_torque_chunk.txt index 334152b04..b9f832dd0 100644 --- a/doc/src/compute_torque_chunk.txt +++ b/doc/src/compute_torque_chunk.txt @@ -1,87 +1,87 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute torque/chunk command :h3 [Syntax:] compute ID group-ID torque/chunk chunkID :pre ID, group-ID are documented in "compute"_compute.html command torque/chunk = style name of this compute command chunkID = ID of "compute chunk/atom"_compute_chunk_atom.html command :ul [Examples:] compute 1 fluid torque/chunk molchunk :pre [Description:] Define a computation that calculates the torque on multiple chunks of atoms. In LAMMPS, chunks are collections of atoms defined by a "compute chunk/atom"_compute_chunk_atom.html 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 "compute -chunk/atom"_compute_chunk_atom.html doc page and ""Section_howto -23"_Section_howto.html#howto_23 for details of how chunks can be +chunk/atom"_compute_chunk_atom.html doc page and "Section +6.23"_Section_howto.html#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 torque vector for eqch chunk, due to the forces on 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 "compute chunk/atom"_compute_chunk_atom.html 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 torque in "unwrapped" form, by using the image flags associated with each atom. See the "dump custom"_dump.html command for a discussion of "unwrapped" coordinates. See the Atoms section of the "read_data"_read_data.html 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 "set image"_set.html command. The simplest way to output the results of the compute torque/chunk calculation to a file is to use the "fix ave/time"_fix_ave_time.html command, for example: compute cc1 all chunk/atom molecule compute myChunk all torque/chunk cc1 fix 1 all ave/time 100 1 100 c_myChunk\[*\] file tmp.out mode vector :pre [Output info:] This compute calculates a global array where the number of rows = the number of chunks {Nchunk} as calculated by the specified "compute chunk/atom"_compute_chunk_atom.html command. The number of columns = 3 for the 3 xyz components of the torque for each chunk. These values can be accessed by any command that uses global array values from a compute as input. See "Section 6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The array values are "intensive". The array values will be in force-distance "units"_units.html. [Restrictions:] none [Related commands:] "variable torque() function"_variable.html [Default:] none diff --git a/doc/src/compute_vcm_chunk.txt b/doc/src/compute_vcm_chunk.txt index 0b9154713..de02c586b 100644 --- a/doc/src/compute_vcm_chunk.txt +++ b/doc/src/compute_vcm_chunk.txt @@ -1,77 +1,77 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute vcm/chunk command :h3 [Syntax:] compute ID group-ID vcm/chunk chunkID :pre ID, group-ID are documented in "compute"_compute.html command vcm/chunk = style name of this compute command chunkID = ID of "compute chunk/atom"_compute_chunk_atom.html command :ul [Examples:] compute 1 fluid vcm/chunk molchunk :pre [Description:] Define a computation that calculates the center-of-mass velocity for multiple chunks of atoms. In LAMMPS, chunks are collections of atoms defined by a "compute chunk/atom"_compute_chunk_atom.html 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 "compute -chunk/atom"_compute_chunk_atom.html doc page and ""Section_howto -23"_Section_howto.html#howto_23 for details of how chunks can be +chunk/atom"_compute_chunk_atom.html doc page and "Section +6.23"_Section_howto.html#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 components of the center-of-mass velocity for each chunk. This is done by summing mass*velocity for each atom in the chunk and dividing the sum by the total mass of the chunk. Note that only atoms in the specified group contribute to the calculation. The "compute chunk/atom"_compute_chunk_atom.html command defines its own group; atoms will have a chunk ID = 0 if they are not in that group, signifying they are not assigned to a chunk, and will thus also not contribute to this calculation. You can specify the "all" group for this command if you simply want to include atoms with non-zero chunk IDs. The simplest way to output the results of the compute vcm/chunk calculation to a file is to use the "fix ave/time"_fix_ave_time.html command, for example: compute cc1 all chunk/atom molecule compute myChunk all vcm/chunk cc1 fix 1 all ave/time 100 1 100 c_myChunk\[*\] file tmp.out mode vector :pre [Output info:] This compute calculates a global array where the number of rows = the number of chunks {Nchunk} as calculated by the specified "compute chunk/atom"_compute_chunk_atom.html command. The number of columns = 3 for the x,y,z center-of-mass velocity coordinates of each chunk. These values can be accessed by any command that uses global array -values from a compute as input. See "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +values from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. The array values are "intensive". The array values will be in velocity "units"_units.html. [Restrictions:] none [Related commands:] none [Default:] none diff --git a/doc/src/compute_voronoi_atom.txt b/doc/src/compute_voronoi_atom.txt index 3dcdffacb..899fc8438 100644 --- a/doc/src/compute_voronoi_atom.txt +++ b/doc/src/compute_voronoi_atom.txt @@ -1,224 +1,224 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line compute voronoi/atom command :h3 [Syntax:] compute ID group-ID voronoi/atom keyword arg ... :pre ID, group-ID are documented in "compute"_compute.html command :ulb,l voronoi/atom = style name of this compute command :l zero or more keyword/value pairs may be appended :l keyword = {only_group} or {surface} or {radius} or {edge_histo} or {edge_threshold} or {face_threshold} or {neighbors} or {peratom} :l {only_group} = no arg {occupation} = no arg {surface} arg = sgroup-ID sgroup-ID = compute the dividing surface between group-ID and sgroup-ID this keyword adds a third column to the compute output {radius} arg = v_r v_r = radius atom style variable for a poly-disperse Voronoi tessellation {edge_histo} arg = maxedge maxedge = maximum number of Voronoi cell edges to be accounted in the histogram {edge_threshold} arg = minlength minlength = minimum length for an edge to be counted {face_threshold} arg = minarea minarea = minimum area for a face to be counted {neighbors} value = {yes} or {no} = store list of all neighbors or no {peratom} value = {yes} or {no} = per-atom quantities accessible or no :pre :ule [Examples:] compute 1 all voronoi/atom compute 2 precipitate voronoi/atom surface matrix compute 3b precipitate voronoi/atom radius v_r compute 4 solute voronoi/atom only_group compute 5 defects voronoi/atom occupation compute 6 all voronoi/atom neighbors yes :pre [Description:] Define a computation that calculates the Voronoi tessellation of the atoms in the simulation box. The tessellation is calculated using all atoms in the simulation, but non-zero values are only stored for atoms in the group. By default two per-atom quantities are calculated by this compute. The first is the volume of the Voronoi cell around each atom. Any point in an atom's Voronoi cell is closer to that atom than any other. The second is the number of faces of the Voronoi cell. This is equal to the number of nearest neighbors of the central atom, plus any exterior faces (see note below). If the {peratom} keyword is set to "no", the per-atom quantities are still calculated, but they are not accessible. :line If the {only_group} keyword is specified the tessellation is performed only with respect to the atoms contained in the compute group. This is equivalent to deleting all atoms not contained in the group prior to evaluating the tessellation. If the {surface} keyword is specified a third quantity per atom is computed: the Voronoi cell surface of the given atom. {surface} takes a group ID as an argument. If a group other than {all} is specified, only the Voronoi cell facets facing a neighbor atom from the specified group are counted towards the surface area. In the example above, a precipitate embedded in a matrix, only atoms at the surface of the precipitate will have non-zero surface area, and only the outward facing facets of the Voronoi cells are counted (the hull of the precipitate). The total surface area of the precipitate can be obtained by running a "reduce sum" compute on c_2\[3\] If the {radius} keyword is specified with an atom style variable as the argument, a poly-disperse Voronoi tessellation is performed. Examples for radius variables are variable r1 atom (type==1)*0.1+(type==2)*0.4 compute radius all property/atom radius variable r2 atom c_radius :pre Here v_r1 specifies a per-type radius of 0.1 units for type 1 atoms and 0.4 units for type 2 atoms, and v_r2 accesses the radius property present in atom_style sphere for granular models. The {edge_histo} keyword activates the compilation of a histogram of number of edges on the faces of the Voronoi cells in the compute group. The argument {maxedge} of the this keyword is the largest number of edges on a single Voronoi cell face expected to occur in the sample. This keyword adds the generation of a global vector with {maxedge}+1 entries. The last entry in the vector contains the number of faces with with more than {maxedge} edges. Since the polygon with the smallest amount of edges is a triangle, entries 1 and 2 of the vector will always be zero. The {edge_threshold} and {face_threshold} keywords allow the suppression of edges below a given minimum length and faces below a given minimum area. Ultra short edges and ultra small faces can occur as artifacts of the Voronoi tessellation. These keywords will affect the neighbor count and edge histogram outputs. If the {occupation} keyword is specified the tessellation is only performed for the first invocation of the compute and then stored. For all following invocations of the compute the number of atoms in each Voronoi cell in the stored tessellation is counted. In this mode the compute returns a per-atom array with 2 columns. The first column is the number of atoms currently in the Voronoi volume defined by this atom at the time of the first invocation of the compute (note that the atom may have moved significantly). The second column contains the total number of atoms sharing the Voronoi cell of the stored tessellation at the location of the current atom. Numbers in column one can be any positive integer including zero, while column two values will always be greater than zero. Column one data can be used to locate vacancies (the coordinates are given by the atom coordinates at the time step when the compute was first invoked), while column two data can be used to identify interstitial atoms. If the {neighbors} value is set to yes, then this compute creates a local array with 3 columns. There is one row for each face of each Voronoi cell. The 3 columns are the atom ID of the atom that owns the cell, the atom ID of the atom in the neighboring cell (or zero if the face is external), and the area of the face. The array can be accessed by any command that uses local values from a compute as input. See "this section"_Section_howto.html#howto_15 for an overview of LAMMPS output options. More specifically, the array can be accessed by a "dump local"_dump.html command to write a file containing all the Voronoi neighbors in a system: compute 6 all voronoi/atom neighbors yes dump d2 all local 1 dump.neighbors index c_6\[1\] c_6\[2\] c_6\[3\] :pre If the {face_threshold} keyword is used, then only faces with areas greater than the threshold are stored. :line The Voronoi calculation is performed by the freely available "Voro++ package"_voronoi, written by Chris Rycroft at UC Berkeley and LBL, which must be installed on your system when building LAMMPS for use with this compute. See instructions on obtaining and installing the Voro++ software in the src/VORONOI/README file. :link(voronoi,http://math.lbl.gov/voro++/) NOTE: The calculation of Voronoi volumes is performed by each processor for the atoms it owns, and includes the effect of ghost atoms stored by the processor. This assumes that the Voronoi cells of owned atoms are not affected by atoms beyond the ghost atom cut-off distance. This is usually a good assumption for liquid and solid systems, but may lead to underestimation of Voronoi volumes in low density systems. By default, the set of ghost atoms stored by each processor is determined by the cutoff used for "pair_style"_pair_style.html interactions. The cutoff can be set explicitly via the "comm_modify cutoff"_comm_modify.html command. The Voronoi cells for atoms adjacent to empty regions will extend into those regions up to the communication cutoff in x, y, or z. In that situation, an exterior face is created at the cutoff distance normal to the x, y, or z direction. For triclinic systems, the exterior face is parallel to the corresponding reciprocal lattice vector. NOTE: The Voro++ package performs its calculation in 3d. This will still work for a 2d LAMMPS simulation, provided all the atoms have the same z coordinate. The Voronoi cell of each atom will be a columnar polyhedron with constant cross-sectional area along the z direction and two exterior faces at the top and bottom of the simulation box. If the atoms do not all have the same z coordinate, then the columnar cells will be accordingly distorted. The cross-sectional area of each Voronoi cell can be obtained by dividing its volume by the z extent of the simulation box. Note that you define the z extent of the simulation box for 2d simulations when using the "create_box"_create_box.html or "read_data"_read_data.html commands. [Output info:] By default, this compute calculates a per-atom array with 2 columns. In regular dynamic tessellation mode the first column is the Voronoi volume, the second is the neighbor count, as described above (read above for the output data in case the {occupation} keyword is specified). These values can be accessed by any command that uses -per-atom values from a compute as input. See "Section_howto -15"_Section_howto.html#howto_15 for an overview of LAMMPS output +per-atom values from a compute as input. See "Section +6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output options. If the {peratom} keyword is set to "no", the per-atom array is still created, but it is not accessible. If the {edge_histo} keyword is used, then this compute generates a global vector of length {maxedge}+1, containing a histogram of the number of edges per face. If the {neighbors} value is set to yes, then this compute calculates a local array with 3 columns. There is one row for each face of each Voronoi cell. NOTE: Some LAMMPS commands such as the "compute reduce"_compute_reduce.html command can accept either a per-atom or local quantity. If this compute produces both quantities, the command may access the per-atom quantity, even if you want to access the local quantity. This effect can be eliminated by using the {peratom} keyword to turn off the production of the per-atom quantities. For the default value {yes} both quantities are produced. For the value {no}, only the local array is produced. The Voronoi cell volume will be in distance "units"_units.html cubed. The Voronoi face area will be in distance "units"_units.html squared. [Restrictions:] This compute is part of the VORONOI package. It is only enabled if LAMMPS was built with that package. See the "Making LAMMPS"_Section_start.html#start_3 section for more info. [Related commands:] "dump custom"_dump.html, "dump local"_dump.html [Default:] {neighbors} no, {peratom} yes diff --git a/doc/src/fix_ave_chunk.txt b/doc/src/fix_ave_chunk.txt index d02fa17e1..3ed91c861 100644 --- a/doc/src/fix_ave_chunk.txt +++ b/doc/src/fix_ave_chunk.txt @@ -1,478 +1,478 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line fix ave/chunk command :h3 [Syntax:] fix ID group-ID ave/chunk Nevery Nrepeat Nfreq chunkID value1 value2 ... keyword args ... :pre ID, group-ID are documented in "fix"_fix.html command :ulb,l ave/chunk = style name of this fix command :l Nevery = use input values every this many timesteps :l Nrepeat = # of times to use input values for calculating averages :l Nfreq = calculate averages every this many timesteps :l chunkID = ID of "compute chunk/atom"_compute_chunk_atom.html command :l one or more input values can be listed :l value = vx, vy, vz, fx, fy, fz, density/mass, density/number, temp, c_ID, c_ID\[I\], f_ID, f_ID\[I\], v_name :l vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component) density/number, density/mass = number or mass density temp = temperature c_ID = per-atom vector calculated by a compute with ID c_ID\[I\] = Ith column of per-atom array calculated by a compute with ID, I can include wildcard (see below) f_ID = per-atom vector calculated by a fix with ID f_ID\[I\] = Ith column of per-atom array calculated by a fix with ID, I can include wildcard (see below) v_name = per-atom vector calculated by an atom-style variable with name :pre zero or more keyword/arg pairs may be appended :l keyword = {norm} or {ave} or {bias} or {adof} or {cdof} or {file} or {overwrite} or {title1} or {title2} or {title3} :l {norm} arg = {all} or {sample} or {none} = how output on {Nfreq} steps is normalized all = output is sum of atoms across all {Nrepeat} samples, divided by atom count sample = output is sum of {Nrepeat} sample averages, divided by {Nrepeat} none = output is sum of {Nrepeat} sample sums, divided by {Nrepeat} {ave} args = {one} or {running} or {window M} one = output new average value every Nfreq steps running = output cumulative average of all previous Nfreq steps window M = output average of M most recent Nfreq steps {bias} arg = bias-ID bias-ID = ID of a temperature compute that removes a velocity bias for temperature calculation {adof} value = dof_per_atom dof_per_atom = define this many degrees-of-freedom per atom for temperature calculation {cdof} value = dof_per_chunk dof_per_chunk = define this many degrees-of-freedom per chunk for temperature calculation {file} arg = filename filename = file to write results to {overwrite} arg = none = overwrite output file with only latest output {format} arg = string string = C-style format string {title1} arg = string string = text to print as 1st line of output file {title2} arg = string string = text to print as 2nd line of output file {title3} arg = string string = text to print as 3rd line of output file :pre :ule [Examples:] fix 1 all ave/chunk 10000 1 10000 binchunk c_myCentro title1 "My output values" fix 1 flow ave/chunk 100 10 1000 molchunk vx vz norm sample file vel.profile fix 1 flow ave/chunk 100 5 1000 binchunk density/mass ave running fix 1 flow ave/chunk 100 5 1000 binchunk density/mass ave running :pre [NOTE:] If you are trying to replace a deprectated fix ave/spatial command with the newer, more flexible fix ave/chunk and "compute chunk/atom"_compute_chunk_atom.html commands, you simply need to split the fix ave/spatial arguments across the two new commands. For example, this command: fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile :pre could be replaced by: compute cc1 flow chunk/atom bin/1d y 0.0 1.0 fix 1 flow ave/chunk 100 10 1000 cc1 vx vz norm sample file vel.profile :pre [Description:] Use one or more per-atom vectors as inputs every few timesteps, sum the values over the atoms in each chunk at each timestep, then average the per-chunk values over longer timescales. The resulting chunk averages can be used by other "output commands"_Section_howto.html#howto_15 such as "thermo_style custom"_thermo_style.html, and can also be written to a file. In LAMMPS, chunks are collections of atoms defined by a "compute chunk/atom"_compute_chunk_atom.html 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 "compute -chunk/atom"_compute_chunk_atom.html doc page and ""Section_howto -23"_Section_howto.html#howto_23 for details of how chunks can be +chunk/atom"_compute_chunk_atom.html doc page and "Section +6.23"_Section_howto.html#howto_23 for details of how chunks can be defined and examples of how they can be used to measure properties of a system. Note that only atoms in the specified group contribute to the summing and averaging calculations. The "compute chunk/atom"_compute_chunk_atom.html command defines its own group as well as an optional region. Atoms will have a chunk ID = 0, meaning they belong to no chunk, if they are not in that group or region. Thus you can specify the "all" group for this command if you simply want to use the chunk definitions provided by chunkID. Each specified per-atom value can be an atom attribute (position, velocity, force component), a mass or number density, or the result of a "compute"_compute.html or "fix"_fix.html or the evaluation of an atom-style "variable"_variable.html. In the latter cases, the compute, fix, or variable must produce a per-atom quantity, not a global quantity. Note that the "compute property/atom"_compute_property_atom.html command provides access to any attribute defined and stored by atoms. If you wish to time-average global quantities from a compute, fix, or variable, then see the "fix ave/time"_fix_ave_time.html command. The per-atom values of each input vector are summed and averaged independently of the per-atom values in other input vectors. "Computes"_compute.html that produce per-atom quantities are those which have the word {atom} in their style name. See the doc pages for individual "fixes"_fix.html to determine which ones produce per-atom quantities. "Variables"_variable.html of style {atom} are the only ones that can be used with this fix since all other styles of variable produce global quantities. Note that for values from a compute or fix, the bracketed index I can be specified using a wildcard asterisk with the index to effectively specify multiple values. This takes the form "*" or "*n" or "n*" or "m*n". If N = the size of the vector (for {mode} = scalar) or the number of columns in the array (for {mode} = vector), then an asterisk with no numeric values means all indices from 1 to N. A leading asterisk means all indices from 1 to n (inclusive). A trailing asterisk means all indices from n to N (inclusive). A middle asterisk means all indices from m to n (inclusive). Using a wildcard is the same as if the individual columns of the array had been listed one by one. E.g. these 2 fix ave/chunk commands are equivalent, since the "compute property/atom"_compute_property_atom.html command creates, in this case, a per-atom array with 3 columns: compute myAng all property/atom angmomx angmomy angmomz fix 1 all ave/chunk 100 1 100 cc1 c_myAng\[*\] file tmp.angmom fix 2 all ave/chunk 100 1 100 cc1 c_myAng\[1\] c_myAng\[2\] c_myAng\[3\] file tmp.angmom :pre NOTE: This fix works by creating an array of size {Nchunk} by Nvalues on each processor. {Nchunk} is the number of chunks which is defined by the "compute chunk/atom"_compute_chunk_atom.html command. Nvalues is the number of input values specified. Each processor loops over its atoms, tallying its values to the appropriate chunk. Then the entire array is summed across all processors. This means that using a large number of chunks will incur an overhead in memory and computational cost (summing across processors), so be careful to define a reasonable number of chunks. :line The {Nevery}, {Nrepeat}, and {Nfreq} arguments specify on what timesteps the input values will be accessed and contribute to the average. The final averaged quantities are generated on timesteps that are a multiples of {Nfreq}. The average is over {Nrepeat} quantities, computed in the preceding portion of the simulation every {Nevery} timesteps. {Nfreq} must be a multiple of {Nevery} and {Nevery} must be non-zero even if {Nrepeat} is 1. Also, the timesteps contributing to the average value cannot overlap, i.e. Nrepeat*Nevery can not exceed Nfreq. For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on timesteps 90,92,94,96,98,100 will be used to compute the final average on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on timestep 200, etc. If Nrepeat=1 and Nfreq = 100, then no time averaging is done; values are simply generated on timesteps 100,200,etc. Each input value can also be averaged over the atoms in each chunk. The way the averaging is done across the {Nrepeat} timesteps to produce output on the {Nfreq} timesteps, and across multiple {Nfreq} outputs, is determined by the {norm} and {ave} keyword settings, as discussed below. NOTE: To perform per-chunk averaging within a {Nfreq} time window, the number of chunks {Nchunk} defined by the "compute chunk/atom"_compute_chunk_atom.html command must remain constant. If the {ave} keyword is set to {running} or {window} then {Nchunk} must remain constant for the duration of the simulation. This fix forces the chunk/atom compute specified by chunkID to hold {Nchunk} constant for the appropriate time windows, by not allowing it to re-calcualte {Nchunk}, which can also affect how it assigns chunk IDs to atoms. More details are given on the "compute chunk/atom"_compute_chunk_atom.html doc page. :line The atom attribute values (vx,vy,vz,fx,fy,fz) are self-explanatory. As noted above, any other atom attributes can be used as input values to this fix by using the "compute property/atom"_compute_property_atom.html command and then specifying an input value from that compute. The {density/number} value means the number density is computed for each chunk, i.e. number/volume. The {density/mass} value means the mass density is computed for each chunk, i.e. total-mass/volume. The output values are in units of 1/volume or density (mass/volume). See the "units"_units.html command doc page for the definition of density for each choice of units, e.g. gram/cm^3. If the chunks defined by the "compute chunk/atom"_compute_chunk_atom.html command are spatial bins, the volume is the bin volume. Otherwise it is the volume of the entire simulation box. The {temp} value means the temperature is computed for each chunk, by the formula KE = DOF/2 k T, where KE = total kinetic energy of the chunk of atoms (sum of 1/2 m v^2), DOF = the total number of degrees of freedom for all atoms in the chunk, k = Boltzmann constant, and T = temperature. The DOF is calculated as N*adof + cdof, where N = number of atoms in the chunk, adof = degrees of freedom per atom, and cdof = degrees of freedom per chunk. By default adof = 2 or 3 = dimensionality of system, as set via the "dimension"_dimension.html command, and cdof = 0.0. This gives the usual formula for temperature. Note that currently this temperature only includes translational degrees of freedom for each atom. No rotational degrees of freedom are included for finite-size particles. Also no degrees of freedom are subtracted for any velocity bias or constraints that are applied, such as "compute temp/partial"_compute_temp_partial.html, or "fix shake"_fix_shake.html or "fix rigid"_fix_rigid.html. This is because those degrees of freedom (e.g. a constrained bond) could apply to sets of atoms that are both included and excluded from a specific chunk, and hence the concept is somewhat ill-defined. In some cases, you can use the {adof} and {cdof} keywords to adjust the calculated degress of freedom appropriately, as explained below. Also note that a bias can be subtracted from atom velocities before they are used in the above formula for KE, by using the {bias} keyword. This allows, for example, a thermal temperature to be computed after removal of a flow velocity profile. Note that the per-chunk temperature calculated by this fix and the "compute temp/chunk"_compute_temp_chunk.html command can be different. The compute calculates the temperature for each chunk for a single snapshot. This fix can do that but can also time average those values over many snapshots, or it can compute a temperature as if the atoms in the chunk on different timesteps were collected together as one set of atoms to calculate their temperature. The compute allows the center-of-mass velocity of each chunk to be subtracted before calculating the temperature; this fix does not. If a value 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 "add them to LAMMPS"_Section_modify.html. See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values. If a value begins with "f_", a fix ID must follow which has been previously defined in the input script. If no bracketed 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 {Nevery}, else an error results. Users can also write code for their own fix styles and "add them to LAMMPS"_Section_modify.html. See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values. If a value begins with "v_", a variable name must follow which has been previously defined in the input script. 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 average within chunks. :line Additional optional keywords also affect the operation of this fix and its outputs. The {norm} keyword affects how averaging is done for the per-chunk values that are output every {Nfreq} timesteps. It the {norm} setting is {all}, which is the default, a chunk value is summed over all atoms in all {Nrepeat} samples, as is the count of atoms in the chunk. The averaged output value for the chunk on the {Nfreq} timesteps is Total-sum / Total-count. In other words it is an average over atoms across the entire {Nfreq} timescale. If the {norm} setting is {sample}, the chunk value is summed over atoms for each sample, as is the count, and an "average sample value" is computed for each sample, i.e. Sample-sum / Sample-count. The output value for the chunk on the {Nfreq} timesteps is the average of the {Nrepeat} "average sample values", i.e. the sum of {Nrepeat} "average sample values" divided by {Nrepeat}. In other words it is an average of an average. If the {norm} setting is {none}, a similar computation as for the {sample} seting is done, except the individual "average sample values" are "summed sample values". A summed sample value is simply the chunk value summed over atoms in the sample, without dividing by the number of atoms in the sample. The output value for the chunk on the {Nfreq} timesteps is the average of the {Nrepeat} "summed sample values", i.e. the sum of {Nrepeat} "summed sample values" divided by {Nrepeat}. The {ave} keyword determines how the per-chunk values produced every {Nfreq} steps are averaged with values produced on previous steps that were multiples of {Nfreq}, before they are accessed by another output command or written to a file. If the {ave} setting is {one}, which is the default, then the chunk values produced on timesteps that are multiples of {Nfreq} are independent of each other; they are output as-is without further averaging. If the {ave} setting is {running}, then the chunk values produced on timesteps that are multiples of {Nfreq} are summed and averaged in a cumulative sense before being output. Each output chunk value is thus the average of the chunk value produced on that timestep with all preceding values for the same chunk. This running average begins when the fix is defined; it can only be restarted by deleting the fix via the "unfix"_unfix.html command, or re-defining the fix by re-specifying it. If the {ave} setting is {window}, then the chunk values produced on timesteps that are multiples of {Nfreq} are summed and averaged within a moving "window" of time, so that the last M values for the same chunk are used to produce the output. E.g. if M = 3 and Nfreq = 1000, then the output on step 10000 will be the average of the individual chunk values on steps 8000,9000,10000. Outputs on early steps will average over less than M values if they are not available. The {bias} keyword specifies the ID of a temperature compute that removes a "bias" velocity from each atom, specified as {bias-ID}. It is only used when the {temp} value is calculated, to compute the thermal temperature of each chunk after the translational kinetic energy components have been altered in a prescribed way, e.g. to remove a flow velocity profile. See the doc pages for individual computes that calculate a temperature to see which ones implement a bias. The {adof} and {cdof} keywords define the values used in the degree of freedom (DOF) formula described above for for temperature calculation for each chunk. They are only used when the {temp} value is calculated. They can be used to calculate a more appropriate temperature for some kinds of chunks. Here are 3 examples: If spatially binned chunks contain some number of water molecules and "fix shake"_fix_shake.html is used to make each molecule rigid, then you could calculate a temperature with 6 degrees of freedom (DOF) (3 translational, 3 rotational) per molecule by setting {adof} to 2.0. If "compute temp/partial"_compute_temp_partial.html is used with the {bias} keyword to only allow the x component of velocity to contribute to the temperature, then {adof} = 1.0 would be appropriate. If each chunk consists of a large molecule, with some number of its bonds constrained by "fix shake"_fix_shake.html or the entire molecule by "fix rigid/small"_fix_rigid.html, {adof} = 0.0 and {cdof} could be set to the remaining degrees of freedom for the entire molecule (entire chunk in this case), e.g. 6 for 3d, or 3 for 2d, for a rigid molecule. The {file} keyword allows a filename to be specified. Every {Nfreq} timesteps, a section of chunk info will be written to a text file in the following format. A line with the timestep and number of chunks is written. Then one line per chunk is written, containing the chunk ID (1-Nchunk), an optional original ID value, optional coordinate values for chunks that represent spatial bins, the number of atoms in the chunk, and one or more calculated values. More explanation of the optional values is given below. The number of values in each line corresponds to the number of values specified in the fix ave/chunk command. The number of atoms and the value(s) are summed or average quantities, as explained above. The {overwrite} keyword will continuously overwrite the output file with the latest output, so that it only contains one timestep worth of output. This option can only be used with the {ave running} setting. The {format} keyword sets the numeric format of each value when it is printed to a file via the {file} keyword. Note that all values are floating point quantities. The default format is %g. You can specify a higher precision if desired, e.g. %20.16g. The {title1} and {title2} and {title3} keywords allow specification of the strings that will be printed as the first 3 lines of the output file, assuming the {file} keyword was used. LAMMPS uses default values for each of these, so they do not need to be specified. By default, these header lines are as follows: # Chunk-averaged data for fix ID and group name # Timestep Number-of-chunks # Chunk (OrigID) (Coord1) (Coord2) (Coord3) Ncount value1 value2 ... :pre In the first line, ID and name are replaced with the fix-ID and group name. The second line describes the two values that are printed at the first of each section of output. In the third line the values are replaced with the appropriate value names, e.g. fx or c_myCompute[2]. The words in parenthesis only appear with corresponding columns if the chunk style specified for the "compute chunk/atom"_compute_chunk_atom.html command supports them. The OrigID column is only used if the {compress} keyword was set to {yes} for the "compute chunk/atom"_compute_chunk_atom.html command. This means that the original chunk IDs (e.g. molecule IDs) will have been compressed to remove chunk IDs with no atoms assigned to them. Thus a compresed chunk ID of 3 may correspond to an original chunk ID or molecule ID of 415. The OrigID column will list 415 for the 3rd chunk. The CoordN columns only appear if a {binning} style was used in the "compute chunk/atom"_compute_chunk_atom.html command. For {bin/1d}, {bin/2d}, and {bin/3d} styles the column values are the center point of the bin in the corresponding dimension. Just Coord1 is used for {bin/1d}, Coord2 is added for {bin/2d}, Coord3 is added for {bin/3d}. For {bin/sphere}, just Coord1 is used, and it is the radial coordinate. For {bin/cylinder}, Coord1 and Coord2 are used. Coord1 is the radial coordinate (away from the cylinder axis), and coord2 is the coordinate along the cylinder axis. Note that if the value of the {units} keyword used in the "compute chunk/atom command"_compute_chunk_atom.html is {box} or {lattice}, the coordinate values will be in distance "units"_units.html. If the value of the {units} keyword is {reduced}, the coordinate values will be in unitless reduced units (0-1). This is not true for the Coord1 value of style {bin/sphere} or {bin/cylinder} which both represent radial dimensions. Those values are always in distance "units"_units.html. :line [Restart, fix_modify, output, run start/stop, minimize info:] No information about this fix is written to "binary restart files"_restart.html. None of the "fix_modify"_fix_modify.html options are relevant to this fix. This fix computes a global array of values which can be accessed by various "output commands"_Section_howto.html#howto_15. The values can only be accessed on timesteps that are multiples of {Nfreq} since that is when averaging is performed. The global array has # of rows = the number of chunks {Nchunk} as calculated by the specified "compute chunk/atom"_compute_chunk_atom.html command. The # of columns = M+1+Nvalues, where M = 1 to 4, depending on whether the optional columns for OrigID and CoordN are used, as explained above. Following the optional columns, the next column contains the count of atoms in the chunk, and the remaining columns are the Nvalue quantities. When the array is accessed with a row I that exceeds the current number of chunks, than a 0.0 is returned by the fix instead of an error, since the number of chunks can vary as a simulation runs depending on how that value is computed by the compute chunk/atom command. The array values calculated by this fix are treated as "intensive", since they are typically already normalized by the count of atoms in each chunk. No parameter of this fix can be used with the {start/stop} keywords of the "run"_run.html command. This fix is not invoked during "energy minimization"_minimize.html. [Restrictions:] none [Related commands:] "compute"_compute.html, "fix ave/atom"_fix_ave_atom.html, "fix ave/histo"_fix_ave_histo.html, "fix ave/time"_fix_ave_time.html, "variable"_variable.html, "fix ave/correlate"_fix_ave_correlate.html [Default:] The option defaults are norm = all, ave = one, bias = none, no file output, and title 1,2,3 = strings as described above. diff --git a/doc/src/fix_nve_body.txt b/doc/src/fix_nve_body.txt index 77d0a5e90..0f80d3aa7 100755 --- a/doc/src/fix_nve_body.txt +++ b/doc/src/fix_nve_body.txt @@ -1,62 +1,62 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line fix nve/body command :h3 [Syntax:] fix ID group-ID nve/body :pre ID, group-ID are documented in "fix"_fix.html command nve/body = style name of this fix command :ul [Examples:] fix 1 all nve/body :pre [Description:] Perform constant NVE integration to update position, velocity, orientation, and angular velocity for body particles in the group each timestep. V is volume; E is energy. This creates a system trajectory -consistent with the microcanonical ensemble. See "Section_howto -14"_Section_howto.html#howto_14 of the manual and the "body"_body.html +consistent with the microcanonical ensemble. See "Section +6.14"_Section_howto.html#howto_14 of the manual and the "body"_body.html doc page for more details on using body particles. This fix differs from the "fix nve"_fix_nve.html command, which assumes point particles and only updates their position and velocity. [Restart, fix_modify, output, run start/stop, minimize info:] No information about this fix is written to "binary restart files"_restart.html. None of the "fix_modify"_fix_modify.html options are relevant to this fix. No global or per-atom quantities are stored by this fix for access by various "output commands"_Section_howto.html#howto_15. No parameter of this fix can be used with the {start/stop} keywords of the "run"_run.html command. This fix is not invoked during "energy minimization"_minimize.html. [Restrictions:] This fix is part of the BODY package. It is only enabled if LAMMPS was built with that package. See the "Making LAMMPS"_Section_start.html#start_3 section for more info. This fix requires that atoms store torque and angular momementum and a quaternion as defined by the "atom_style body"_atom_style.html command. All particles in the group must be body particles. They cannot be point particles. [Related commands:] "fix nve"_fix_nve.html, "fix nve/sphere"_fix_nve_sphere.html, "fix nve/asphere"_fix_nve_asphere.html [Default:] none diff --git a/doc/src/fix_viscosity.txt b/doc/src/fix_viscosity.txt index 744197256..a5e8b4156 100644 --- a/doc/src/fix_viscosity.txt +++ b/doc/src/fix_viscosity.txt @@ -1,169 +1,169 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line fix viscosity command :h3 [Syntax:] fix ID group-ID viscosity N vdim pdim Nbin keyword value ... :pre ID, group-ID are documented in "fix"_fix.html command :ulb,l viscosity = style name of this fix command :l N = perform momentum exchange every N steps :l vdim = {x} or {y} or {z} = which momentum component to exchange :l pdim = {x} or {y} or {z} = direction of momentum transfer :l Nbin = # of layers in pdim direction (must be even number) :l zero or more keyword/value pairs may be appended :l keyword = {swap} or {target} :l {swap} value = Nswap = number of swaps to perform every N steps {vtarget} value = V or INF = target velocity of swap partners (velocity units) :pre :ule [Examples:] fix 1 all viscosity 100 x z 20 fix 1 all viscosity 50 x z 20 swap 2 vtarget 1.5 :pre [Description:] Use the Muller-Plathe algorithm described in "this paper"_#Muller-Plathe to exchange momenta between two particles in different regions of the simulation box every N steps. This induces a shear velocity profile in the system. As described below this enables a viscosity of the fluid to be calculated. This algorithm is sometimes called a reverse non-equilibrium MD (reverse NEMD) approach to computing viscosity. This is because the usual NEMD approach is to impose a shear velocity profile on the system and measure the response via an off-diagonal component of the stress tensor, which is proportional to the momentum flux. In the Muller-Plathe method, the momentum flux is imposed, and the shear velocity profile is the system's response. The simulation box is divided into {Nbin} layers in the {pdim} direction, where the layer 1 is at the low end of that dimension and the layer {Nbin} is at the high end. Every N steps, Nswap pairs of atoms are chosen in the following manner. Only atoms in the fix group are considered. Nswap atoms in layer 1 with positive velocity components in the {vdim} direction closest to the target value {V} are selected. Similarly, Nswap atoms in the "middle" layer (see below) with negative velocity components in the {vdim} direction closest to the negative of the target value {V} are selected. The two sets of Nswap atoms are paired up and their {vdim} momenta components are swapped within each pair. This resets their velocities, typically in opposite directions. Over time, this induces a shear velocity profile in the system which can be measured using commands such as the following, which writes the profile to the file tmp.profile: compute layers all chunk/atom bin/1d z lower 0.05 units reduced fix f1 all ave/chunk 100 10 1000 layers vx file tmp.profile :pre Note that by default, Nswap = 1 and vtarget = INF, though this can be changed by the optional {swap} and {vtarget} keywords. When vtarget = INF, one or more atoms with the most positive and negative velocity components are selected. Setting these parameters appropriately, in conjunction with the swap rate N, allows the momentum flux rate to be adjusted across a wide range of values, and the momenta to be exchanged in large chunks or more smoothly. The "middle" layer for momenta swapping is defined as the {Nbin}/2 + 1 layer. Thus if {Nbin} = 20, the two swapping layers are 1 and 11. This should lead to a symmetric velocity profile since the two layers are separated by the same distance in both directions in a periodic sense. This is why {Nbin} is restricted to being an even number. As described below, the total momentum transferred by these velocity swaps is computed by the fix and can be output. Dividing this quantity by time and the cross-sectional area of the simulation box yields a momentum flux. The ratio of momentum flux to the slope of the shear velocity profile is proportional to the viscosity of the fluid, in appropriate units. See the "Muller-Plathe paper"_#Muller-Plathe for details. NOTE: If your system is periodic in the direction of the momentum flux, then the flux is going in 2 directions. This means the effective momentum flux in one direction is reduced by a factor of 2. You will see this in the equations for viscosity in the Muller-Plathe paper. LAMMPS is simply tallying momentum which does not account for whether or not your system is periodic; you must use the value appropriately to yield a viscosity for your system. NOTE: After equilibration, if the velocity profile you observe is not linear, then you are likely swapping momentum too frequently and are not in a regime of linear response. In this case you cannot accurately infer a viscosity and should try increasing the Nevery parameter. An alternative method for calculating a viscosity is to run a NEMD -simulation, as described in "Section_howto -13"_Section_howto.html#howto_13 of the manual. NEMD simulations +simulation, as described in "Section +6.13"_Section_howto.html#howto_13 of the manual. NEMD simulations deform the simmulation box via the "fix deform"_fix_deform.html command. Thus they cannot be run on a charged system using a "PPPM solver"_kspace_style.html since PPPM does not currently support non-orthogonal boxes. Using fix viscosity keeps the box orthogonal; thus it does not suffer from this limitation. [Restart, fix_modify, output, run start/stop, minimize info:] No information about this fix is written to "binary restart files"_restart.html. None of the "fix_modify"_fix_modify.html options are relevant to this fix. This fix computes a global scalar which can be accessed by various "output commands"_Section_howto.html#howto_15. The scalar is the cummulative momentum transferred between the bottom and middle of the simulation box (in the {pdim} direction) is stored as a scalar quantity by this fix. This quantity is zeroed when the fix is defined and accumlates thereafter, once every N steps. The units of the quantity are momentum = mass*velocity. The scalar value calculated by this fix is "intensive". No parameter of this fix can be used with the {start/stop} keywords of the "run"_run.html command. This fix is not invoked during "energy minimization"_minimize.html. [Restrictions:] This fix is part of the MISC package. It is only enabled if LAMMPS was built with that package. See the "Making LAMMPS"_Section_start.html#start_3 section for more info. Swaps conserve both momentum and kinetic energy, even if the masses of the swapped atoms are not equal. Thus you should not need to thermostat the system. If you do use a thermostat, you may want to apply it only to the non-swapped dimensions (other than {vdim}). LAMMPS does not check, but you should not use this fix to swap velocities of atoms that are in constrained molecules, e.g. via "fix shake"_fix_shake.html or "fix rigid"_fix_rigid.html. This is because application of the constraints will alter the amount of transferred momentum. You should, however, be able to use flexible molecules. See the "Maginn paper"_#Maginn for an example of using this algorithm in a computation of alcohol molecule properties. When running a simulation with large, massive particles or molecules in a background solvent, you may want to only exchange momenta bewteen solvent particles. [Related commands:] "fix ave/chunk"_fix_ave_chunk.html, "fix thermal/conductivity"_fix_thermal_conductivity.html [Default:] The option defaults are swap = 1 and vtarget = INF. :line :link(Muller-Plathe) [(Muller-Plathe)] Muller-Plathe, Phys Rev E, 59, 4894-4898 (1999). :link(Maginn) [(Maginn)] Kelkar, Rafferty, Maginn, Siepmann, Fluid Phase Equilibria, 260, 218-231 (2007). diff --git a/doc/src/pair_buck_long.txt b/doc/src/pair_buck_long.txt index 752ef71f9..ba18738e4 100644 --- a/doc/src/pair_buck_long.txt +++ b/doc/src/pair_buck_long.txt @@ -1,171 +1,171 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line pair_style buck/long/coul/long command :h3 pair_style buck/long/coul/long/omp command :h3 [Syntax:] pair_style buck/long/coul/long flag_buck flag_coul cutoff (cutoff2) :pre flag_buck = {long} or {cut} :ulb,l {long} = use Kspace long-range summation for the dispersion term 1/r^6 {cut} = use a cutoff :pre flag_coul = {long} or {off} :l {long} = use Kspace long-range summation for the Coulombic term 1/r {off} = omit the Coulombic term :pre cutoff = global cutoff for Buckingham (and Coulombic if only 1 cutoff) (distance units) :l cutoff2 = global cutoff for Coulombic (optional) (distance units) :l :ule [Examples:] pair_style buck/long/coul/long cut off 2.5 pair_style buck/long/coul/long cut long 2.5 4.0 pair_style buck/long/coul/long long long 4.0 pair_coeff * * 1 1 pair_coeff 1 1 1 3 4 :pre [Description:] The {buck/long/coul/long} style computes a Buckingham potential (exp/6 instead of Lennard-Jones 12/6) and Coulombic potential, given by :c,image(Eqs/pair_buck.jpg) :c,image(Eqs/pair_coulomb.jpg) Rc is the cutoff. If one cutoff is specified in the pair_style command, it is used for both the Buckingham and Coulombic terms. If two cutoffs are specified, they are used as cutoffs for the Buckingham and Coulombic terms respectively. The purpose of this pair style is to capture long-range interactions resulting from both attractive 1/r^6 Buckingham and Coulombic 1/r interactions. This is done by use of the {flag_buck} and {flag_coul} -settings. The ""Ismail"_#Ismail paper has more details on when it is +settings. The "Ismail"_#Ismail paper has more details on when it is appropriate to include long-range 1/r^6 interactions, using this potential. If {flag_buck} is set to {long}, no cutoff is used on the Buckingham 1/r^6 dispersion term. The long-range portion can be calculated by using the "kspace_style ewald/disp or pppm/disp"_kspace_style.html commands. The specified Buckingham cutoff then determines which portion of the Buckingham interactions are computed directly by the pair potential versus which part is computed in reciprocal space via the Kspace style. If {flag_buck} is set to {cut}, the Buckingham interactions are simply cutoff, as with "pair_style buck"_pair_buck.html. If {flag_coul} is set to {long}, no cutoff is used on the Coulombic interactions. The long-range portion can calculated by using any of several "kspace_style"_kspace_style.html command options such as {pppm} or {ewald}. Note that if {flag_buck} is also set to long, then the {ewald/disp} or {pppm/disp} Kspace style needs to be used to perform the long-range calculations for both the Buckingham and Coulombic interactions. If {flag_coul} is set to {off}, Coulombic interactions are not computed. The following coefficients must be defined for each pair of atoms types via the "pair_coeff"_pair_coeff.html command as in the examples above, or in the data file or restart files read by the "read_data"_read_data.html or "read_restart"_read_restart.html commands: A (energy units) rho (distance units) C (energy-distance^6 units) cutoff (distance units) cutoff2 (distance units) :ul The second coefficient, rho, must be greater than zero. The latter 2 coefficients are optional. If not specified, the global Buckingham and Coulombic cutoffs specified in the pair_style command are used. If only one cutoff is specified, it is used as the cutoff for both Buckingham and Coulombic interactions for this type pair. If both coefficients are specified, they are used as the Buckingham and Coulombic cutoffs for this type pair. Note that if you are using {flag_buck} set to {long}, you cannot specify a Buckingham cutoff for an atom type pair, since only one global Buckingham cutoff is allowed. Similarly, if you are using {flag_coul} set to {long}, you cannot specify a Coulombic cutoff for an atom type pair, since only one global Coulombic cutoff is allowed. :line Styles with a {gpu}, {intel}, {kk}, {omp}, or {opt} suffix are functionally the same as the corresponding style without the suffix. They have been optimized to run faster, depending on your available hardware, as discussed in "Section 5"_Section_accelerate.html 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 GPU, USER-INTEL, KOKKOS, USER-OMP and OPT packages, respectively. They are only enabled if LAMMPS was built with those packages. See the "Making LAMMPS"_Section_start.html#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 "-suffix command-line switch"_Section_start.html#start_7 when you invoke LAMMPS, or you can use the "suffix"_suffix.html command in your input script. See "Section 5"_Section_accelerate.html of the manual for more instructions on how to use the accelerated styles effectively. :line [Mixing, shift, table, tail correction, restart, rRESPA info]: This pair styles does not support mixing. Thus, coefficients for all I,J pairs must be specified explicitly. This pair style supports the "pair_modify"_pair_modify.html shift option for the energy of the exp() and 1/r^6 portion of the pair interaction, assuming {flag_buck} is {cut}. This pair style does not support the "pair_modify"_pair_modify.html shift option for the energy of the Buckingham portion of the pair interaction. This pair style supports the "pair_modify"_pair_modify.html table and table/disp options since they can tabulate the short-range portion of the long-range Coulombic and dispersion interactions. This pair style write its information to "binary restart files"_restart.html, so pair_style and pair_coeff commands do not need to be specified in an input script that reads a restart file. This pair style supports the use of the {inner}, {middle}, and {outer} keywords of the "run_style respa"_run_style.html command, meaning the pairwise forces can be partitioned by distance at different levels of the rRESPA hierarchy. See the "run_style"_run_style.html command for details. :line [Restrictions:] This style is part of the KSPACE package. It is only enabled if LAMMPS was built with that package. See the "Making LAMMPS"_Section_start.html#start_3 section for more info. Note that the KSPACE package is installed by default. [Related commands:] "pair_coeff"_pair_coeff.html [Default:] none :line :link(Ismail) [(Ismail)] Ismail, Tsige, In 't Veld, Grest, Molecular Physics (accepted) (2007). diff --git a/doc/src/tad.txt b/doc/src/tad.txt index 8e93b93c3..8a0bd31c7 100644 --- a/doc/src/tad.txt +++ b/doc/src/tad.txt @@ -1,312 +1,312 @@ "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) :link(lc,Section_commands.html#comm) :line tad command :h3 [Syntax:] tad N t_event T_lo T_hi delta tmax compute-ID \ keyword value ... :pre N = # of timesteps to run (not including dephasing/quenching) :ulb,l t_event = timestep interval between event checks :l T_lo = temperature at which event times are desired :l T_hi = temperature at which MD simulation is performed :l delta = desired confidence level for stopping criterion :l tmax = reciprocal of lowest expected preexponential factor (time units) :l compute-ID = ID of the compute used for event detection :l zero or more keyword/value pairs may be appended :l keyword = {min} or {neb} or {min_style} or {neb_style} or {neb_log} :l {min} values = etol ftol maxiter maxeval etol = stopping tolerance for energy (energy units) ftol = stopping tolerance for force (force units) maxiter = max iterations of minimize maxeval = max number of force/energy evaluations {neb} values = ftol N1 N2 Nevery etol = stopping tolerance for energy (energy units) ftol = stopping tolerance for force (force units) N1 = max # of iterations (timesteps) to run initial NEB N2 = max # of iterations (timesteps) to run barrier-climbing NEB Nevery = print NEB statistics every this many timesteps {neb_style} value = {quickmin} or {fire} {neb_step} value = dtneb dtneb = timestep for NEB damped dynamics minimization {neb_log} value = file where NEB statistics are printed :pre :ule [Examples:] tad 2000 50 1800 2300 0.01 0.01 event tad 2000 50 1800 2300 0.01 0.01 event & min 1e-05 1e-05 100 100 & neb 0.0 0.01 200 200 20 & min_style cg & neb_style fire & neb_log log.neb :pre [Description:] Run a temperature accelerated dynamics (TAD) simulation. This method requires two or more partitions to perform NEB transition state searches. TAD is described in "this paper"_#Voter by Art Voter. It is a method that uses accelerated dynamics at an elevated temperature to generate results at a specified lower temperature. A good overview of accelerated dynamics methods for such systems is given in "this review paper"_#Voter2 from the same group. In general, these methods assume that the long-time dynamics is dominated by infrequent events i.e. the system is is confined to low energy basins for long periods, punctuated by brief, randomly-occurring transitions to adjacent basins. TAD is suitable for infrequent-event systems, where in addition, the transition kinetics are well-approximated by harmonic transition state theory (hTST). In hTST, the temperature dependence of transition rates follows the Arrhenius relation. As a consequence a set of event times generated in a high-temperature simulation can be mapped to a set of much longer estimated times in the low-temperature system. However, because this mapping involves the energy barrier of the transition event, which is different for each event, the first event at the high temperature may not be the earliest event at the low temperature. TAD handles this by first generating a set of possible events from the current basin. After each event, the simulation is reflected backwards into the current basin. This is repeated until the stopping criterion is satisfied, at which point the event with the earliest low-temperature occurrence time is selected. The stopping criterion is that the confidence measure be greater than 1-{delta}. The confidence measure is the probability that no earlier low-temperature event will occur at some later time in the high-temperature simulation. hTST provides an lower bound for this probability, based on the user-specified minimum pre-exponential factor (reciprocal of {tmax}). In order to estimate the energy barrier for each event, the TAD method invokes the "NEB"_neb.html method. Each NEB replica runs on a partition of processors. The current NEB implementation in LAMMPS restricts you to having exactly one processor per replica. For more information, see the documentation for the "neb"_neb.html command. In the current LAMMPS implementation of TAD, all the non-NEB TAD operations are performed on the first partition, while the other -partitions remain idle. See "Section_howto -5"_Section_howto.html#howto_5 of the manual for further discussion of +partitions remain idle. See "Section +6.5"_Section_howto.html#howto_5 of the manual for further discussion of multi-replica simulations. A TAD run has several stages, which are repeated each time an event is performed. The logic for a TAD run is as follows: while (time remains): while (time < tstop): until (event occurs): run dynamics for t_event steps quench run neb calculation using all replicas compute tlo from energy barrier update earliest event update tstop reflect back into current basin execute earliest event :pre Before this outer loop begins, the initial potential energy basin is identified by quenching (an energy minimization, see below) the initial state and storing the resulting coordinates for reference. Inside the inner loop, dynamics is run continuously according to whatever integrator has been specified by the user, stopping every {t_event} steps to check if a transition event has occurred. This check is performed by quenching the system and comparing the resulting atom coordinates to the coordinates from the previous basin. A quench is an energy minimization and is performed by whichever algorithm has been defined by the "min_style"_min_style.html command; its default is the CG minimizer. The tolerances and limits for each quench can be set by the {min} keyword. Note that typically, you do not need to perform a highly-converged minimization to detect a transition event. The event check is performed by a compute with the specified {compute-ID}. Currently there is only one compute that works with the TAD commmand, which is the "compute event/displace"_compute_event_displace.html command. Other event-checking computes may be added. "Compute event/displace"_compute_event_displace.html checks whether any atom in the compute group has moved further than a specified threshold distance. If so, an "event" has occurred. The NEB calculation is similar to that invoked by the "neb"_neb.html command, except that the final state is generated internally, instead of being read in from a file. The style of minimization performed by NEB is determined by the {neb_style} keyword and must be a damped dynamics minimizer. The tolerances and limits for each NEB calculation can be set by the {neb} keyword. As discussed on the "neb"_neb.html, it is often advantageous to use a larger timestep for NEB than for normal dyanmics. Since the size of the timestep set by the "timestep"_timestep.html command is used by TAD for performing dynamics, there is a {neb_step} keyword which can be used to set a larger timestep for each NEB calculation if desired. :line A key aspect of the TAD method is setting the stopping criterion appropriately. If this criterion is too conservative, then many events must be generated before one is finally executed. Conversely, if this criterion is too aggressive, high-entropy high-barrier events will be over-sampled, while low-entropy low-barrier events will be under-sampled. If the lowest pre-exponential factor is known fairly accurately, then it can be used to estimate {tmax}, and the value of {delta} can be set to the desired confidence level e.g. {delta} = 0.05 corresponds to 95% confidence. However, for systems where the dynamics are not well characterized (the most common case), it will be necessary to experiment with the values of {delta} and {tmax} to get a good trade-off between accuracy and performance. A second key aspect is the choice of {t_hi}. A larger value greatly increases the rate at which new events are generated. However, too large a value introduces errors due to anharmonicity (not accounted for within hTST). Once again, for any given system, experimentation is necessary to determine the best value of {t_hi}. :line Five kinds of output can be generated during a TAD run: event statistics, NEB statistics, thermodynamic output by each replica, dump files, and restart files. Event statistics are printed to the screen and master log.lammps file each time an event is executed. The quantities are the timestep, CPU time, global event number {N}, local event number {M}, event status, energy barrier, time margin, {t_lo} and {delt_lo}. The timestep is the usual LAMMPS timestep, which corresponds to the high-temperature time at which the event was detected, in units of timestep. The CPU time is the total processor time since the start of the TAD run. The global event number {N} is a counter that increments with each executed event. The local event number {M} is a counter that resets to zero upon entering each new basin. The event status is {E} when an event is executed, and is {D} for an event that is detected, while {DF} is for a detected event that is also the earliest (first) event at the low temperature. The time margin is the ratio of the high temperature time in the current basin to the stopping time. This last number can be used to judge whether the stopping time is too short or too long (see above). {t_lo} is the low-temperature event time when the current basin was entered, in units of timestep. del{t_lo} is the time of each detected event, measured relative to {t_lo}. {delt_lo} is equal to the high-temperature time since entering the current basin, scaled by an exponential factor that depends on the hi/lo temperature ratio and the energy barrier for that event. On lines for executed events, with status {E}, the global event number is incremented by one, the local event number and time margin are reset to zero, while the global event number, energy barrier, and {delt_lo} match the last event with status {DF} in the immediately preceding block of detected events. The low-temperature event time {t_lo} is incremented by {delt_lo}. NEB statistics are written to the file specified by the {neb_log} keyword. If the keyword value is "none", then no NEB statistics are printed out. The statistics are written every {Nevery} timesteps. See the "neb"_neb.html command for a full description of the NEB statistics. When invoked from TAD, NEB statistics are never printed to the screen. Because the NEB calculation must run on multiple partitions, LAMMPS produces additional screen and log files for each partition, e.g. log.lammps.0, log.lammps.1, etc. For the TAD command, these contain the thermodynamic output of each NEB replica. In addition, the log file for the first partition, log.lammps.0, will contain thermodynamic output from short runs and minimizations corresponding to the dynamics and quench operations, as well as a line for each new detected event, as described above. After the TAD command completes, timing statistics for the TAD run are printed in each replica's log file, giving a breakdown of how much CPU time was spent in each stage (NEB, dynamics, quenching, etc). Any "dump files"_dump.html defined in the input script will be written to during a TAD run at timesteps when an event is executed. This means the the requested dump frequency in the "dump"_dump.html command is ignored. There will be one dump file (per dump command) created for all partitions. The atom coordinates of the dump snapshot are those of the minimum energy configuration resulting from quenching following the executed event. The timesteps written into the dump files correspond to the timestep at which the event occurred and NOT the clock. A dump snapshot corresponding to the initial minimum state used for event detection is written to the dump file at the beginning of each TAD run. If the "restart"_restart.html command is used, a single restart file for all the partitions is generated, which allows a TAD run to be continued by a new input script in the usual manner. The restart file is generated after an event is executed. The restart file contains a snapshot of the system in the new quenched state, including the event number and the low-temperature time. The restart frequency specified in the "restart"_restart.html command is interpreted differently when performing a TAD run. It does not mean the timestep interval between restart files. Instead it means an event interval for executed events. Thus a frequency of 1 means write a restart file every time an event is executed. A frequency of 10 means write a restart file every 10th executed event. When an input script reads a restart file from a previous TAD run, the new script can be run on a different number of replicas or processors. Note that within a single state, the dynamics will typically temporarily continue beyond the event that is ultimately chosen, until the stopping criterionis satisfied. When the event is eventually executed, the timestep counter is reset to the value when the event was detected. Similarly, after each quench and NEB minimization, the timestep counter is reset to the value at the start of the minimization. This means that the timesteps listed in the replica log files do not always increase monotonically. However, the timestep values printed to the master log file, dump files, and restart files are always monotonically increasing. :line [Restrictions:] This command can only be used if LAMMPS was built with the REPLICA package. See the "Making LAMMPS"_Section_start.html#start_3 section for more info on packages. {N} setting must be integer multiple of {t_event}. Runs restarted from restart files written during a TAD run will only produce identical results if the user-specified integrator supports exact restarts. So "fix nvt"_fix_nh.html will produce an exact restart, but "fix langevin"_fix_langevin.html will not. This command cannot be used when any fixes are defined that keep track of elapsed time to perform time-dependent operations. Examples include the "ave" fixes such as "fix ave/chunk"_fix_ave_chunk.html. Also "fix dt/reset"_fix_dt_reset.html and "fix deposit"_fix_deposit.html. [Related commands:] "compute event/displace"_compute_event_displace.html, "min_modify"_min_modify.html, "min_style"_min_style.html, "run_style"_run_style.html, "minimize"_minimize.html, "temper"_temper.html, "neb"_neb.html, "prd"_prd.html [Default:] The option defaults are {min} = 0.1 0.1 40 50, {neb} = 0.01 100 100 10, {neb_style} = {quickmin}, {neb_step} = the same timestep set by the "timestep"_timestep.html command, and {neb_log} = "none". :line :link(Voter) [(Voter)] Sorensen and Voter, J Chem Phys, 112, 9599 (2000) :link(Voter2) [(Voter2)] Voter, Montalenti, Germann, Annual Review of Materials Research 32, 321 (2002).