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

Merge branch 'develop' into qtpie

Browse Source
This commit is contained in:
Stan Moore
2024-11-12 11:37:40 -08:00
committed by GitHub
parent 5673375d21 a445545ffb
commit 2d2bc029a4
901 changed files with 85215 additions and 41370 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
doc/src/Build_development.rst
View File

@ -138,12 +138,27 @@ during development:
The status of this automated testing can be viewed on `https://ci.lammps.org
<https://ci.lammps.org>`_.
The scripts and inputs for integration, run, and regression testing
are maintained in a
`separate repository <https://github.com/lammps/lammps-testing>`_
of the LAMMPS project on GitHub. A few tests are also run as GitHub
Actions and their configuration files are in the ``.github/workflows/``
folder of the LAMMPS git tree.
The scripts and inputs for integration, run, and legacy regression
testing are maintained in a `separate repository
<https://github.com/lammps/lammps-testing>`_ of the LAMMPS project on
GitHub. A few tests are also run as GitHub Actions and their
configuration files are in the ``.github/workflows/`` folder of the
LAMMPS git tree.
Regression tests can also be performed locally with the :ref:`regression
tester tool <regression>`. The tool checks if a given LAMMPS binary run
with selected input examples produces thermo output that is consistent
with the provided log files. The script can be run in one pass over all
available input files, but it can also first create multiple lists of
inputs or folders that can then be run with multiple workers
concurrently to speed things up. Another mode allows to do a quick
check of inputs that contain commands that have changes in the current
checkout branch relative to a git branch. This works similar to the two
pass mode, but will select only shorter runs and no more than 100 inputs
that are chosen randomly. This ensures that this test runs
significantly faster compared to the full test run. These test runs can
also be performed with instrumented LAMMPS binaries (see previous
section).
The unit testing facility is integrated into the CMake build process of
the LAMMPS source code distribution itself. It can be enabled by

77
doc/src/Build_extras.rst
View File

@ -7,6 +7,8 @@ in addition to
.. list-table::
:align: center
:header-rows: 1
:widths: 50 50
:width: 80%
* - CMake build
- Traditional make
@ -115,7 +117,7 @@ GPU package
To build with this package, you must choose options for precision and
which GPU hardware to build for. The GPU package currently supports
three different types of backends: OpenCL, CUDA and HIP.
three different types of back ends: OpenCL, CUDA and HIP.
CMake build
^^^^^^^^^^^
@ -205,7 +207,7 @@ necessary for ``hipcc`` and the linker to work correctly.
.. versionadded:: 3Aug2022
Using the CHIP-SPV implementation of HIP is supported. It allows one to
run HIP code on Intel GPUs via the OpenCL or Level Zero backends. To use
run HIP code on Intel GPUs via the OpenCL or Level Zero back ends. To use
CHIP-SPV, you must set ``-DHIP_USE_DEVICE_SORT=OFF`` in your CMake
command line as CHIP-SPV does not yet support hipCUB. As of Summer 2022,
the use of HIP for Intel GPUs is experimental. You should only use this
@ -751,14 +753,27 @@ This list was last updated for version 4.3.0 of the Kokkos library.
platform-appropriate vendor library: rocFFT on AMD GPUs or cuFFT on
NVIDIA GPUs.
To simplify compilation, five preset files are included in the
For Intel GPUs using SYCL, set these variables:
.. code-block:: bash
-D Kokkos_ARCH_HOSTARCH=yes # HOSTARCH = HOST from list above
-D Kokkos_ARCH_GPUARCH=yes # GPUARCH = GPU from list above
-D Kokkos_ENABLE_SYCL=yes
-D Kokkos_ENABLE_OPENMP=yes
-D FFT_KOKKOS=MKL_GPU
This will enable FFTs on the GPU using the oneMKL library.
To simplify compilation, six preset files are included in the
``cmake/presets`` folder, ``kokkos-serial.cmake``,
``kokkos-openmp.cmake``, ``kokkos-cuda.cmake``,
``kokkos-hip.cmake``, and ``kokkos-sycl.cmake``. They will enable
the KOKKOS package and enable some hardware choices. For GPU
support those preset files must be customized to match the
hardware used. So to compile with CUDA device parallelization with
some common packages enabled, you can do the following:
``kokkos-hip.cmake``, ``kokkos-sycl-nvidia.cmake``, and
``kokkos-sycl-intel.cmake``. They will enable the KOKKOS
package and enable some hardware choices. For GPU support those
preset files must be customized to match the hardware used. So
to compile with CUDA device parallelization with some common
packages enabled, you can do the following:
.. code-block:: bash
@ -830,6 +845,18 @@ This list was last updated for version 4.3.0 of the Kokkos library.
FFT_INC = -DFFT_HIPFFT # enable use of hipFFT (optional)
FFT_LIB = -lhipfft # link to hipFFT library
For Intel GPUs using SYCL:
.. code-block:: make
KOKKOS_DEVICES = SYCL
KOKKOS_ARCH = HOSTARCH,GPUARCH # HOSTARCH = HOST from list above that is
# hosting the GPU
# GPUARCH = GPU from list above
FFT_INC = -DFFT_KOKKOS_MKL_GPU # enable use of oneMKL for Intel GPUs (optional)
# link to oneMKL FFT library
FFT_LIB = -lmkl_sycl_dft -lmkl_intel_ilp64 -lmkl_tbb_thread -mkl_core -ltbb
Advanced KOKKOS compilation settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -2224,28 +2251,38 @@ verified to work in February 2020 with Quantum Espresso versions 6.3 to
RHEO package
------------
To build with this package you must have the `GNU Scientific Library
(GSL) <https://www.gnu.org/software/gsl/>` installed in locations that
are accessible in your environment. The GSL library should be at least
version 2.7.
This package depends on the BPM package.
.. tabs::
.. tab:: CMake build
If CMake cannot find the GSL library or include files, you can set:
.. code-block:: bash
-D GSL_ROOT_DIR=path # path to root of GSL installation
-D PKG_RHEO=yes # enable the package itself
-D PKG_BPM=yes # the RHEO package requires BPM
-D USE_INTERNAL_LINALG=value # prefer internal LAPACK if true
Some features in the RHEO package are dependent on code in the BPM
package so the latter one *must* be enabled as well.
The RHEO package also requires LAPACK (and BLAS) and CMake
can identify their locations and pass that info to the RHEO
build script. But on some systems this may cause problems when
linking or the dependency is not desired. By using the setting
``-D USE_INTERNAL_LINALG=yes`` when running the CMake
configuration, you will select compiling and linking the bundled
linear algebra library and work around the limitations.
.. tab:: Traditional make
LAMMPS will try to auto-detect the GSL compiler and linker flags
from the corresponding ``pkg-config`` file (``gsl.pc``), otherwise
you can edit the file ``lib/rheo/Makefile.lammps``
to specify the paths and library names where indicated by comments.
This must be done **before** the package is installed.
The RHEO package requires LAPACK (and BLAS) which can be either
a system provided library or the bundled "linalg" library. This
is a subset of LAPACK translated to C++. For that, one of the
provided ``Makefile.lammps.<config>`` files needs to be copied
to ``Makefile.lammps`` and edited as needed. The default file
uses the bundled "linalg" library, which can be built by
``make lib-linalg args='-m serial'`` in the ``src`` folder.
----------

29
doc/src/Build_settings.rst
View File

@ -67,10 +67,10 @@ libraries and better pipelining for packing and communication.
.. code-block:: bash
-D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found,
# else KISS
-D FFT_KOKKOS=value # FFTW3 or MKL or KISS or CUFFT or HIPFFT,
# default is KISS
-D FFT=value # FFTW3 or MKL or NVPL or KISS,
# default is FFTW3 if found, else KISS
-D FFT_KOKKOS=value # FFTW3 or MKL or NVPL or KISS or CUFFT
# or HIPFFT or MKL_GPU, default is KISS
-D FFT_SINGLE=value # yes or no (default), no = double precision
-D FFT_PACK=value # array (default) or pointer or memcpy
-D FFT_USE_HEFFTE=value # yes or no (default), yes links to heFFTe
@ -103,6 +103,8 @@ libraries and better pipelining for packing and communication.
-D FFT_HEFFTE_BACKEND=value # FFTW or MKL or empty/undefined for the stock
# heFFTe back end
-D Heffte_ROOT=path # path to an existing heFFTe installation
-D nvpl_fft_INCLUDE_DIR=path # path to NVPL FFT include files
-D nvpl_fft_LIBRARY_DIR=path # path to NVPL FFT libraries
.. note::
@ -121,9 +123,10 @@ libraries and better pipelining for packing and communication.
.. code-block:: make
FFT_INC = -DFFT_<NAME> # where <NAME> is KISS (default), FFTW3,
# FFTW (same as FFTW3), or MKL
# FFTW (same as FFTW3), NVPL, or MKL
FFT_INC = -DFFT_KOKKOS_<NAME> # where <NAME> is KISS (default), FFTW3,
# FFTW (same as FFTW3), MKL, CUFFT, or HIPFFT
# FFTW (same as FFTW3), NVPL, MKL, CUFFT,
# HIPFFT, or MKL_GPU
FFT_INC = -DFFT_SINGLE # do not specify for double precision
FFT_INC = -DFFT_FFTW_THREADS # enable using threaded FFTW3 libraries
FFT_INC = -DFFT_MKL_THREADS # enable using threaded FFTs with MKL libraries
@ -141,6 +144,9 @@ libraries and better pipelining for packing and communication.
# cuFFT either precision
FFT_LIB = -lcufft
# MKL_GPU either precision
FFT_LIB = -lmkl_sycl_dft -lmkl_intel_ilp64 -lmkl_tbb_thread -lmkl_core -ltbb
# FFTW3 double precision
FFT_LIB = -lfftw3
@ -165,6 +171,10 @@ libraries and better pipelining for packing and communication.
# MKL with automatic runtime selection of interface libs
FFT_LIB = -lmkl_rt
# threaded NVPL FFT
FFT_LIB = -lnvpl_fftw
As with CMake, you do not need to set paths in ``FFT_INC`` or
``FFT_PATH``, if the compiler can find the FFT header and library
files in its default search path. You must specify ``FFT_LIB``
@ -218,10 +228,15 @@ The Intel MKL math library is part of the Intel compiler suite. It
can be used with the Intel or GNU compiler (see the ``FFT_LIB`` setting
above).
The NVIDIA Performance Libraries (NVPL) FFT library is optimized for NVIDIA
Grace Armv9.0 architecture. You can download it from https://docs.nvidia.com/nvpl/
The cuFFT and hipFFT FFT libraries are packaged with NVIDIA's CUDA and
AMD's HIP installations, respectively. These FFT libraries require the
Kokkos acceleration package to be enabled and the Kokkos back end to be
GPU-resident (i.e., HIP or CUDA).
GPU-resident (i.e., HIP or CUDA). Similarly, GPU offload of FFTs on
Intel GPUs with oneMKL currently requires the Kokkos acceleration
package to be enabled with the SYCL back end.
Performing 3d FFTs in parallel can be time-consuming due to data access
and required communication. This cost can be reduced by performing

1
doc/src/Commands_fix.rst
View File

@ -178,6 +178,7 @@ OPT.
* :doc:`python/move <fix_python_move>`
* :doc:`qbmsst <fix_qbmsst>`
* :doc:`qeq/comb (o) <fix_qeq_comb>`
* :doc:`qeq/ctip <fix_qeq>`
* :doc:`qeq/dynamic <fix_qeq>`
* :doc:`qeq/fire <fix_qeq>`
* :doc:`qeq/point <fix_qeq>`

3
doc/src/Commands_pair.rst
View File

@ -44,7 +44,7 @@ OPT.
* :doc:`born/coul/wolf/cs (g) <pair_cs>`
* :doc:`born/gauss <pair_born_gauss>`
* :doc:`bpm/spring <pair_bpm_spring>`
* :doc:`brownian (o) <pair_brownian>`
* :doc:`brownian (ko) <pair_brownian>`
* :doc:`brownian/poly (o) <pair_brownian>`
* :doc:`buck (giko) <pair_buck>`
* :doc:`buck/coul/cut (giko) <pair_buck>`
@ -59,6 +59,7 @@ OPT.
* :doc:`comb (o) <pair_comb>`
* :doc:`comb3 <pair_comb>`
* :doc:`cosine/squared <pair_cosine_squared>`
* :doc:`coul/ctip <pair_coul>`
* :doc:`coul/cut (gko) <pair_coul>`
* :doc:`coul/cut/dielectric <pair_dielectric>`
* :doc:`coul/cut/global (o) <pair_coul>`

1
doc/src/Developer_write.rst
View File

@ -12,3 +12,4 @@ details are provided for writing code for LAMMPS.
Developer_write_pair
Developer_write_fix
Developer_write_command

348
doc/src/Developer_write_command.rst Normal file
View File

@ -0,0 +1,348 @@
Writing a new command style
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Command styles allow to do system manipulations or interfaces to the
operating system.
In the text below, we will discuss the implementation of one example. As
shown on the page for :doc:`writing or extending command styles
<Modify_command>`, in order to implement a new command style, a new class
must be written that is either directly or indirectly derived from the
``Command`` class. There is just one method that must be implemented:
``Command::command()``. In addition, a custom constructor is needed to get
access to the members of the ``LAMMPS`` class like the ``Error`` class to
print out error messages. The ``Command::command()`` method processes the
arguments passed to the command in the input and executes it. Any other
methods would be for the convenience of implementation of the new command.
In general, new command styles should be added to the :ref:`EXTRA-COMMAND
package <PKG-EXTRA-COMMAND>`. If you feel that your contribution should be
added to a different package, please consult with the :doc:`LAMMPS
developers <Intro_authors>` first. The contributed code needs to support
the :doc:`traditional GNU make build process <Build_make>` **and** the
:doc:`CMake build process <Build_cmake>`.
----
Case 1: Implementing the geturl command
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In this section, we will describe the procedure of adding a simple command
style to LAMMPS: the :doc:`geturl command <geturl>` that allows to download
files directly without having to rely on an external program like "wget" or
"curl". The complete implementation can be found in the files
``src/EXTRA-COMMAND/geturl.cpp`` and ``src/EXTRA-COMMAND/geturl.h`` of the
LAMMPS source code.
Interfacing the *libcurl* library
"""""""""""""""""""""""""""""""""
Rather than implementing the various protocols for downloading files, we
rely on an external library: `libcurl library <https:://curl.se/libcurl/>`_.
This requires that the library and its headers are installed. For the
traditional GNU make build system, this simply requires edits to the machine
makefile to add compilation flags like for other libraries. For the CMake
based build system, we need to add some lines to the file
``cmake/Modules/Packages/EXTRA-COMMAND.cmake``:
.. code-block:: cmake
find_package(CURL QUIET COMPONENTS HTTP HTTPS)
option(WITH_CURL "Enable libcurl support" ${CURL_FOUND})
if(WITH_CURL)
find_package(CURL REQUIRED COMPONENTS HTTP HTTPS)
target_compile_definitions(lammps PRIVATE -DLAMMPS_CURL)
target_link_libraries(lammps PRIVATE CURL::libcurl)
endif()
The first ``find_package()`` command uses a built-in CMake module to find
an existing *libcurl* installation with development headers and support for
using the HTTP and HTTPS protocols. The "QUIET" flag ensures that there is
no screen output and no error if the search fails. The status of the search
is recorded in the "${CURL_FOUND}" variable. That variable sets the default
of the WITH_CURL option, which toggles whether support for *libcurl* is included
or not.
The second ``find_package()`` uses the "REQUIRED" flag to produce an error
if the WITH_CURL option was set to ``True``, but no suitable *libcurl*
implementation with development support was found. This construct is used
so that the CMake script code inside the ``if(WITH_CURL)`` and ``endif()``
block can be expanded later to download and compile *libcurl* as part of the
LAMMPS build process, if it is not found locally. The
``target_compile_definitions()`` function added the define ``-DLAMMPS_CURL``
to the compilation flags when compiling objects for the LAMMPS library.
This allows to always compile the :doc:`geturl command <geturl>`, but use
pre-processing to compile in the interface to *libcurl* only when it is
present and usable and otherwise stop with an error message about the
unavailability of *libcurl* to execute the functionality of the command.
Header file
"""""""""""
The first segment of any LAMMPS source should be the copyright and
license statement. Note the marker in the first line to indicate to
editors like emacs that this file is a C++ source, even though the .h
extension suggests a C source (this is a convention inherited from the
very beginning of the C++ version of LAMMPS).
.. code-block:: c++
/* -*- c++ -*- ----------------------------------------------------------
LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
https://www.lammps.org/, Sandia National Laboratories
LAMMPS development team: developers@lammps.org
Copyright (2003) Sandia Corporation. Under the terms of Contract
DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
certain rights in this software. This software is distributed under
the GNU General Public License.
See the README file in the top-level LAMMPS directory.
------------------------------------------------------------------------- */
Every command style must be registered in LAMMPS by including the following
lines of code in the second part of the header after the copyright
message and before the include guards for the class definition:
.. code-block:: c++
#ifdef COMMAND_CLASS
// clang-format off
CommandStyle(geturl,GetURL);
// clang-format on
#else
This block between ``#ifdef COMMAND_CLASS`` and ``#else`` will be
included by the ``Input`` class in ``input.cpp`` to build a map of
"factory functions" that will create an instance of a Command class
and call its ``command()`` method. The map connects the name of the
command ``geturl`` with the name of the class ``GetURL``. During
compilation, LAMMPS constructs a file ``style_command.h`` that contains
``#include`` statements for all "installed" command styles. Before
including ``style_command.h`` into ``input.cpp``, the ``COMMAND_CLASS``
define is set and the ``CommandStyle(name,class)`` macro defined. The
code of the macro adds the installed command styles to the "factory map"
which enables the ``Input`` to execute the command.
The list of header files to include in ``style_command.h`` is automatically
updated by the build system if there are new files, so the presence of the
new header file in the ``src/EXTRA-COMMAND`` folder and the enabling of the
EXTRA-COMMAND package will trigger LAMMPS to include the new command style
when it is (re-)compiled. The "// clang-format" format comments are needed
so that running :ref:`clang-format <clang-format>` on the file will not
insert unwanted blanks which would break the ``CommandStyle`` macro.
The third part of the header file is the actual class definition of the
``GetURL`` class. This has the custom constructor and the ``command()``
method implemented by this command style. For the constructor there is
nothing to do but to pass the ``lmp`` pointer to the base class. Since the
``command()`` method is labeled "virtual" in the base class, it must be
given the "override" property.
.. code-block:: c++
#ifndef LMP_GETURL_H
#define LMP_GETURL_H
#include "command.h"
namespace LAMMPS_NS {
class GetURL : public Command {
public:
GetURL(class LAMMPS *lmp) : Command(lmp) {};
void command(int, char **) override;
};
} // namespace LAMMPS_NS
#endif
#endif
The "override" property helps to detect unexpected mismatches because
compilation will stop with an error in case the signature of a function
is changed in the base class without also changing it in all derived
classes.
Implementation file
"""""""""""""""""""
We move on to the implementation of the ``GetURL`` class in the
``geturl.cpp`` file. This file also starts with a LAMMPS copyright and
license header. Below that notice is typically the space where comments may
be added with additional information about this specific file, the
author(s), affiliation(s), and email address(es). This way the contributing
author(s) can be easily contacted, when there are questions about the
implementation later. Since the file(s) may be around for a long time, it
is beneficial to use some kind of "permanent" email address, if possible.
.. code-block:: c++
/* ----------------------------------------------------------------------
LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
https://www.lammps.org/, Sandia National Laboratories
LAMMPS development team: developers@lammps.org
Copyright (2003) Sandia Corporation. Under the terms of Contract
DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
certain rights in this software. This software is distributed under
the GNU General Public License.
See the README file in the top-level LAMMPS directory.
------------------------------------------------------------------------- */
/* ----------------------------------------------------------------------
Contributing authors: Axel Kohlmeyer (Temple U),
------------------------------------------------------------------------- */
#include "geturl.h"
#include "comm.h"
#include "error.h"
#if defined(LAMMPS_CURL)
#include <curl/curl.h>
#endif
using namespace LAMMPS_NS;
The second section of the implementation file has various include
statements. The include file for the class header has to come first, then a
couple of LAMMPS classes (sorted alphabetically) followed by the header for
the *libcurl* interface. This is wrapped into an ``#ifdef`` block so that
LAMMPS will compile this file without error when the *libcurl* header is not
available and thus the define not set. The final statement of this segment
imports the ``LAMMPS_NS::`` namespace globally for this file. This way, all
LAMMPS specific functions and classes do not have to be prefixed with
``LAMMPS_NS::``.
The command() function (required)
"""""""""""""""""""""""""""""""""
Since the required custom constructor is trivial and implemented in the
header, there is only one function that must be implemented for a command
style and that is the ``command()`` function.
.. code-block:: c++
void GetURL::command(int narg, char **arg)
{
#if !defined(LAMMPS_CURL)
error->all(FLERR, "LAMMPS has not been compiled with libcurl support");
#else
if (narg < 1) utils::missing_cmd_args(FLERR, "geturl", error);
int verify = 1;
int overwrite = 1;
int verbose = 0;
This first part also has the ``#ifdef`` block depending on the LAMMPS_CURL
define. This way the command will simply print an error, if *libcurl* is
not available but will not fail to compile. Furthermore, it sets the
defaults for the following optional arguments.
.. code-block:: c++
// process arguments
std::string url = arg[0];
// sanity check
if ((url.find(':') == std::string::npos) || (url.find('/') == std::string::npos))
error->all(FLERR, "URL '{}' is not a supported URL", url);
std::string output = url.substr(url.find_last_of('/') + 1);
if (output.empty()) error->all(FLERR, "URL '{}' must end in a file string", url);
This block stores the positional, i.e. non-optional argument of the URL to
be downloaded and adds a couple of sanity checks on the string to make sure it is
a valid URL. Also it derives the default name of the output file from the URL.
.. code-block:: c++
int iarg = 1;
while (iarg < narg) {
if (strcmp(arg[iarg], "output") == 0) {
if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "geturl output", error);
output = arg[iarg + 1];
++iarg;
} else if (strcmp(arg[iarg], "overwrite") == 0) {
if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "geturl overwrite", error);
overwrite = utils::logical(FLERR, arg[iarg + 1], false, lmp);
++iarg;
} else if (strcmp(arg[iarg], "verify") == 0) {
if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "geturl verify", error);
verify = utils::logical(FLERR, arg[iarg + 1], false, lmp);
++iarg;
} else if (strcmp(arg[iarg], "verbose") == 0) {
if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "geturl verbose", error);
verbose = utils::logical(FLERR, arg[iarg + 1], false, lmp);
++iarg;
} else {
error->all(FLERR, "Unknown geturl keyword: {}", arg[iarg]);
}
++iarg;
}
This block parses the optional arguments following the URL and stops with an
error if there are arguments missing or an unknown argument is encountered.
.. code-block:: c++
// only download files from rank 0
if (comm->me != 0) return;
if (!overwrite && platform::file_is_readable(output)) return;
// open output file for writing
FILE *out = fopen(output.c_str(), "wb");
if (!out)
error->all(FLERR, "Cannot open output file {} for writing: {}", output, utils::getsyserror());
Here all MPI ranks other than 0 will return, so that the URL download will
only happen from a single MPI rank. For that rank the output file is opened
for writing using the C library function ``fopen()``.
.. code-block:: c++
// initialize curl and perform download
CURL *curl;
curl_global_init(CURL_GLOBAL_DEFAULT);
curl = curl_easy_init();
if (curl) {
(void) curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
(void) curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *) out);
(void) curl_easy_setopt(curl, CURLOPT_FILETIME, 1L);
(void) curl_easy_setopt(curl, CURLOPT_FAILONERROR, 1L);
if (verbose && screen) {
(void) curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
(void) curl_easy_setopt(curl, CURLOPT_STDERR, (void *) screen);
}
if (!verify) {
(void) curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
(void) curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
}
auto res = curl_easy_perform(curl);
if (res != CURLE_OK) {
long response = 0L;
curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &response);
error->one(FLERR, "Download of {} failed with: {} {}", output, curl_easy_strerror(res),
response);
}
curl_easy_cleanup(curl);
This block now implements the actual URL download with the selected options
via the "easy" interface of *libcurl*. For the details of what these
function calls do, please have a look at the `*libcurl documentation
<https://curl.se/libcurl/c/allfuncs.html>`_.
.. code-block:: c++
}
curl_global_cleanup();
fclose(out);
#endif
}
Finally, the previously opened file is closed and the command is complete.

2
doc/src/Developer_write_pair.rst
View File

@ -160,7 +160,7 @@ message and before the include guards for the class definition:
#endif
This block of between ``#ifdef PAIR_CLASS`` and ``#else`` will be
This block between ``#ifdef PAIR_CLASS`` and ``#else`` will be
included by the ``Force`` class in ``force.cpp`` to build a map of
"factory functions" that will create an instance of these classes and
return a pointer to it. The map connects the name of the pair style,

41
doc/src/Howto_bioFF.rst
View File

@ -1,5 +1,5 @@
CHARMM, AMBER, COMPASS, and DREIDING force fields
=================================================
CHARMM, AMBER, COMPASS, DREIDING, and OPLS force fields
=======================================================
A compact summary of the concepts, definitions, and properties of
force fields with explicit bonded interactions (like the ones discussed
@ -236,6 +236,40 @@ documentation for the formula it computes.
* :doc:`special_bonds <special_bonds>` dreiding
OPLS
----
OPLS (Optimized Potentials for Liquid Simulations) is a general force
field for atomistic simulation of organic molecules in solvent. It was
developed by the `Jorgensen group
<https://traken.chem.yale.edu/oplsaam.html>`_ at Purdue University and
later at Yale University. Multiple versions of the OPLS parameters
exist for united atom representations (OPLS-UA) and for all-atom
representations (OPLS-AA).
This force field is based on atom types mapped to specific functional
groups in organic and biological molecules. Each atom includes a
static, partial atomic charge reflecting the oxidation state of the
element derived from its bonded neighbors :ref:`(Jorgensen)
<howto-jorgensen>` and computed based on increments determined by the
atom type of the atoms bond to it.
The interaction styles listed below compute force field formulas that
are fully or in part consistent with the OPLS style force fields. See
each command's documentation for the formula it computes. Some are only
compatible with a subset of OPLS interactions.
* :doc:`bond_style <bond_harmonic>` harmonic
* :doc:`angle_style <angle_harmonic>` harmonic
* :doc:`dihedral_style <dihedral_opls>` opls
* :doc:`improper_style <improper_cvff>` cvff
* :doc:`improper_style <improper_fourier>` fourier
* :doc:`improper_style <improper_harmonic>` harmonic
* :doc:`pair_style <pair_lj_cut_coul>` lj/cut/coul/cut
* :doc:`pair_style <pair_lj_cut_coul>` lj/cut/coul/long
* :doc:`pair_modify <pair_modify>` geometric
* :doc:`special_bonds <special_bonds>` lj/coul 0.0 0.0 0.5
----------
.. _Typelabel2:
@ -266,3 +300,6 @@ documentation for the formula it computes.
**(Mayo)** Mayo, Olfason, Goddard III (1990). J Phys Chem, 94, 8897-8909. https://doi.org/10.1021/j100389a010
.. _howto-Jorgensen:
**(Jorgensen)** Jorgensen, Tirado-Rives (1988). J Am Chem Soc, 110, 1657-1666. https://doi.org/10.1021/ja00214a001

14
doc/src/Howto_bpm.rst
View File

@ -5,7 +5,11 @@ The BPM package implements bonded particle models which can be used to
simulate mesoscale solids. Solids are constructed as a collection of
particles, which each represent a coarse-grained region of space much
larger than the atomistic scale. Particles within a solid region are
then connected by a network of bonds to provide solid elasticity.
then connected by a network of bonds to model solid elasticity.
There are many names for methods that are based on similar (or
equivalent) capabilities to those in this package, including, but not
limited to, cohesive beam models, bonded DEMs, lattice spring models,
mass spring models, and lattice particle methods.
Unlike traditional bonds in molecular dynamics, the equilibrium bond
length can vary between bonds. Bonds store the reference state. This
@ -42,7 +46,8 @@ Currently, there are two types of bonds included in the BPM package. The
first bond style, :doc:`bond bpm/spring <bond_bpm_spring>`, only applies
pairwise, central body forces. Point particles must have :doc:`bond atom
style <atom_style>` and may be thought of as nodes in a spring
network. Alternatively, the second bond style, :doc:`bond bpm/rotational
network. An optional multibody term can be used to adjust the network's
Poisson's ratio. Alternatively, the second bond style, :doc:`bond bpm/rotational
<bond_bpm_rotational>`, resolves tangential forces and torques arising
with the shearing, bending, and twisting of the bond due to rotation or
displacement of particles. Particles are similar to those used in the
@ -55,8 +60,9 @@ orientation similar to :doc:`fix nve/asphere <fix_nve_asphere>`.
In addition to bond styles, a new pair style :doc:`pair bpm/spring
<pair_bpm_spring>` was added to accompany the bpm/spring bond
style. This pair style is simply a hookean repulsion with similar
velocity damping as its sister bond style.
style. By default, this pair style is simply a hookean repulsion with
similar velocity damping as its sister bond style, but optional
arguments can be used to modify the force.
----------

67
doc/src/Howto_chunk.rst
View File

@ -58,28 +58,30 @@ chunk ID for an individual atom can also be static (e.g. a molecule
ID), or dynamic (e.g. what spatial bin an atom is in as it moves).
Note that this compute allows the per-atom output of other
:doc:`computes <compute>`, :doc:`fixes <fix>`, and
:doc:`variables <variable>` to be used to define chunk IDs for each
atom. This means you can write your own compute or fix to output a
per-atom quantity to use as chunk ID. See the :doc:`Modify <Modify>`
doc pages for info on how to do this. You can also define a :doc:`per-atom variable <variable>` in the input script that uses a formula to
generate a chunk ID for each atom.
:doc:`computes <compute>`, :doc:`fixes <fix>`, and :doc:`variables
<variable>` to be used to define chunk IDs for each atom. This means
you can write your own compute or fix to output a per-atom quantity to
use as chunk ID. See the :doc:`Modify <Modify>` doc pages for info on
how to do this. You can also define a :doc:`per-atom variable
<variable>` in the input script that uses a formula to generate a chunk
ID for each atom.
Fix ave/chunk command:
----------------------
This fix takes the ID of a :doc:`compute chunk/atom <compute_chunk_atom>` command as input. For each chunk,
it then sums one or more specified per-atom values over the atoms in
each chunk. The per-atom values can be any atom property, such as
velocity, force, charge, potential energy, kinetic energy, stress,
etc. Additional keywords are defined for per-chunk properties like
density and temperature. More generally any per-atom value generated
by other :doc:`computes <compute>`, :doc:`fixes <fix>`, and :doc:`per-atom variables <variable>`, can be summed over atoms in each chunk.
This fix takes the ID of a :doc:`compute chunk/atom
<compute_chunk_atom>` command as input. For each chunk, it then sums
one or more specified per-atom values over the atoms in each chunk. The
per-atom values can be any atom property, such as velocity, force,
charge, potential energy, kinetic energy, stress, etc. Additional
keywords are defined for per-chunk properties like density and
temperature. More generally any per-atom value generated by other
:doc:`computes <compute>`, :doc:`fixes <fix>`, and :doc:`per-atom
variables <variable>`, can be summed over atoms in each chunk.
Similar to other averaging fixes, this fix allows the summed per-chunk
values to be time-averaged in various ways, and output to a file. The
fix produces a global array as output with one row of values per
chunk.
fix produces a global array as output with one row of values per chunk.
Compute \*/chunk commands:
--------------------------
@ -97,17 +99,20 @@ category:
* :doc:`compute torque/chunk <compute_vcm_chunk>`
* :doc:`compute vcm/chunk <compute_vcm_chunk>`
They each take the ID of a :doc:`compute chunk/atom <compute_chunk_atom>` command as input. As their names
indicate, they calculate the center-of-mass, radius of gyration,
moments of inertia, mean-squared displacement, temperature, torque,
and velocity of center-of-mass for each chunk of atoms. The :doc:`compute property/chunk <compute_property_chunk>` command can tally the
count of atoms in each chunk and extract other per-chunk properties.
They each take the ID of a :doc:`compute chunk/atom
<compute_chunk_atom>` command as input. As their names indicate, they
calculate the center-of-mass, radius of gyration, moments of inertia,
mean-squared displacement, temperature, torque, and velocity of
center-of-mass for each chunk of atoms. The :doc:`compute
property/chunk <compute_property_chunk>` command can tally the count of
atoms in each chunk and extract other per-chunk properties.
The reason these various calculations are not part of the :doc:`fix ave/chunk command <fix_ave_chunk>`, is that each requires a more
The reason these various calculations are not part of the :doc:`fix
ave/chunk command <fix_ave_chunk>`, is that each requires a more
complicated operation than simply summing and averaging over per-atom
values in each chunk. For example, many of them require calculation
of a center of mass, which requires summing mass\*position over the
atoms and then dividing by summed mass.
values in each chunk. For example, many of them require calculation of
a center of mass, which requires summing mass\*position over the atoms
and then dividing by summed mass.
All of these computes produce a global vector or global array as
output, with one or more values per chunk. The output can be used in
@ -118,9 +123,10 @@ various ways:
* As input to the :doc:`fix ave/histo <fix_ave_histo>` command to
histogram values across chunks. E.g. a histogram of cluster sizes or
molecule diffusion rates.
* As input to special functions of :doc:`equal-style variables <variable>`, like sum() and max() and ave(). E.g. to
find the largest cluster or fastest diffusing molecule or average
radius-of-gyration of a set of molecules (chunks).
* As input to special functions of :doc:`equal-style variables
<variable>`, like sum() and max() and ave(). E.g. to find the largest
cluster or fastest diffusing molecule or average radius-of-gyration of
a set of molecules (chunks).
Other chunk commands:
---------------------
@ -138,9 +144,10 @@ spatially average per-chunk values calculated by a per-chunk compute.
The :doc:`compute reduce/chunk <compute_reduce_chunk>` command reduces a
peratom value across the atoms in each chunk to produce a value per
chunk. When used with the :doc:`compute chunk/spread/atom <compute_chunk_spread_atom>` command it can
create peratom values that induce a new set of chunks with a second
:doc:`compute chunk/atom <compute_chunk_atom>` command.
chunk. When used with the :doc:`compute chunk/spread/atom
<compute_chunk_spread_atom>` command it can create peratom values that
induce a new set of chunks with a second :doc:`compute chunk/atom
<compute_chunk_atom>` command.
Example calculations with chunks
--------------------------------

2
doc/src/Howto_cmake.rst
View File

@ -348,7 +348,7 @@ Some common LAMMPS specific variables
* - ``FFT``
- select which FFT library to use: ``FFTW3``, ``MKL``, ``KISS`` (default, unless FFTW3 is found)
* - ``FFT_KOKKOS``
- select which FFT library to use in Kokkos-enabled styles: ``FFTW3``, ``MKL``, ``HIPFFT``, ``CUFFT``, ``KISS`` (default)
- select which FFT library to use in Kokkos-enabled styles: ``FFTW3``, ``MKL``, ``HIPFFT``, ``CUFFT``, ``MKL_GPU``, ``KISS`` (default)
* - ``FFT_SINGLE``
- select whether to use single precision FFTs (default: ``off``)
* - ``WITH_JPEG``

4
doc/src/Howto_pylammps.rst
View File

@ -39,16 +39,18 @@ lammps.lammps
* interface modeled after the LAMMPS :ref:`C language library interface API <lammps_c_api>`
* requires knowledge of how LAMMPS internally works (C pointers, etc)
* full support for running Python with MPI using `mpi4py <https://mpi4py.readthedocs.io>`_
* no overhead from creating a more Python-like interface
lammps.PyLammps
"""""""""""""""
* higher-level abstraction built on *top* of original :py:class:`ctypes based interface <lammps.lammps>`
* higher-level abstraction built on *top* of the original :py:class:`ctypes based interface <lammps.lammps>`
* manipulation of Python objects
* communication with LAMMPS is hidden from API user
* shorter, more concise Python
* better IPython integration, designed for quick prototyping
* designed for serial execution
* additional overhead from capturing and parsing the LAMMPS screen output
Quick Start
-----------

4
doc/src/Intro_authors.rst
View File

@ -56,7 +56,7 @@ lammps.org". General questions about LAMMPS should be posted in the
- SNL
- jmgoff at sandia.gov
- machine learned potentials, QEq solvers, Python
* - Megan McCarthy
* - Meg McCarthy
- SNL
- megmcca at sandia.gov
- alloys, micro-structure, machine learned potentials
@ -67,7 +67,7 @@ lammps.org". General questions about LAMMPS should be posted in the
* - `Trung Nguyen <tn_>`_
- U Chicago
- ndactrung at gmail.com
- soft matter, GPU package
- soft matter, GPU package, DIELECTRIC package, regression testing
.. _rb: https://rbberger.github.io/
.. _gc: https://enthalpiste.fr/

13
doc/src/Intro_portability.rst
View File

@ -31,18 +31,19 @@ Operating systems
^^^^^^^^^^^^^^^^^
The primary development platform for LAMMPS is Linux. Thus, the chances
for LAMMPS to compile without problems on Linux machines are the best.
for LAMMPS to compile without problems are the best on Linux machines.
Also, compilation and correct execution on macOS and Windows (using
Microsoft Visual C++) is checked automatically for largest part of the
source code. Some (optional) features are not compatible with all
Microsoft Visual C++) is checked automatically for the largest part of
the source code. Some (optional) features are not compatible with all
operating systems, either through limitations of the corresponding
LAMMPS source code or through source code or build system
incompatibilities of required libraries.
LAMMPS source code or through incompatibilities of source code or
build system of required external libraries or packages.
Executables for Windows may be created natively using either Cygwin or
Visual Studio or with a Linux to Windows MinGW cross-compiler.
Additionally, FreeBSD and Solaris have been tested successfully.
Additionally, FreeBSD and Solaris have been tested successfully to
run LAMMPS and produce results consistent with those on Linux.
Compilers
^^^^^^^^^

2
doc/src/Packages_details.rst
View File

@ -880,7 +880,7 @@ groups of atoms that interact with the remaining atoms as electrolyte.
**Authors:** The ELECTRODE package is written and maintained by Ludwig
Ahrens-Iwers (TUHH, Hamburg, Germany), Shern Tee (UQ, Brisbane, Australia) and
Robert Meissner (TUHH, Hamburg, Germany).
Robert Meissner (Helmholtz-Zentrum Hereon, Geesthacht and TUHH, Hamburg, Germany).
.. versionadded:: 4May2022

81
doc/src/Run_windows.rst
View File

@ -3,71 +3,70 @@ Running LAMMPS on Windows
To run a serial (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 script,
* Install a LAMMPS installer package from https://packages.lammps.org/windows.html
* Open the "Command Prompt" or "Terminal" app.
* Change to the directory where you have your input script,
(e.g. by typing: cd "Documents").
* At the command prompt, type "lmp -in in.file", where
in.file is the name of your LAMMPS input script.
* At the command prompt, type "lmp -in in.file.lmp", where
``in.file.lmp`` is the name of your LAMMPS input script.
Note that the serial executable includes support for multi-threading
parallelization from the styles in the OPENMP packages. To run with
4 threads, you can type this:
parallelization from the styles in the OPENMP and KOKKOS packages.
To run with 4 threads, you can type this:
.. code-block:: bash
lmp -in in.lj -pk omp 4 -sf omp
lmp -in in.lj.lmp -pk omp 4 -sf omp
lmp -in in.lj.lmp -k on t 4 -sf kk
Alternately, you can also install a package with LAMMPS-GUI included and
open the LAMMPS-GUI app (the package includes the command line version
of LAMMPS as well) and open the input file in the GUI and run it from
there. For details on LAMMPS-GUI, see :doc:`Howto_lammps_gui`.
----------
For the MPI executable, which allows you to run LAMMPS under Windows
in parallel, follow these steps.
For the MS-MPI executables, which allow you to run LAMMPS under Windows
in parallel using MPI rather than multi-threading, follow these steps.
Download and install a compatible MPI library binary package:
* for 32-bit Windows: `mpich2-1.4.1p1-win-ia32.msi <https://download.lammps.org/thirdparty/mpich2-1.4.1p1-win-ia32.msi>`_
* for 64-bit Windows: `mpich2-1.4.1p1-win-x86-64.msi <https://download.lammps.org/thirdparty/mpich2-1.4.1p1-win-x86-64.msi>`_
The LAMMPS Windows installer packages will automatically adjust your
path for the default location of this MPI package. After the
installation of the MPICH2 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").
Download and install the MS-MPI runtime package ``msmpisetup.exe`` from
https://www.microsoft.com/en-us/download/details.aspx?id=105289 (Note
that the ``msmpisdk.msi`` is **only** required for **compilation** of
LAMMPS from source on Windows using Microsoft Visual Studio). After
installation of MS-MPI perform a reboot.
Then you can run the executable in serial like in the example above
or in parallel using MPI with one of the following commands:
.. code-block:: bash
mpiexec -localonly 4 lmp -in in.file
mpiexec -np 4 lmp -in in.file
mpiexec -localonly 4 lmp -in in.file.lmp
mpiexec -np 4 lmp -in in.file.lmp
where in.file is the name of your LAMMPS input script. For the latter
case, you may be prompted to enter the password that you set during
installation of the MPI library software.
where ``in.file.lmp`` is the name of your LAMMPS input script. For the
latter case, you may be prompted to enter the password that you set
during installation of the MPI library software.
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 this:
Note that the parallel executable also includes OpenMP multi-threading
through both the OPENMP and the KOKKOS package, which can be combined
with MPI using something like:
.. code-block:: bash
lmp -in in.lj
mpiexec -localonly 2 lmp -in in.lj.lmp -pk omp 2 -sf omp
mpiexec -localonly 2 lmp -in in.lj.lmp -kokkos on t 2 -sf kk
Note that the parallel executable also includes OpenMP
multi-threading, which can be combined with MPI using something like:
.. code-block:: bash
mpiexec -localonly 2 lmp -in in.lj -pk omp 2 -sf omp
-------------
MPI parallelization will work for *all* functionality in LAMMPS and in
many cases the MPI parallelization is more efficient than
multi-threading since LAMMPS was designed from ground up for MPI
parallelization using domain decomposition. Multi-threading is only
available for selected styles and implemented on top of the MPI
parallelization. Multi-threading is most useful for systems with large
load imbalances when using domain decomposition and a smaller number
of threads (<= 8).

2
doc/src/Tools.rst
View File

@ -1022,7 +1022,7 @@ regression tests with a given LAMMPS binary. The tool launches the
LAMMPS binary with any given input script under one of the `examples`
subdirectories, and compares the thermo output in the generated log file
with those in the provided log file with the same number of processors
ub the same subdirectory. If the differences between the actual and
in the same subdirectory. If the differences between the actual and
reference values are within specified tolerances, the test is considered
passed. For each test batch, that is, a set of example input scripts,
the mpirun command, the LAMMPS command line arguments, and the

8
doc/src/angles.rst
View File

@ -1,8 +0,0 @@
Angle Styles
############
.. toctree::
:maxdepth: 1
:glob:
angle_*

60
doc/src/bond_bpm_spring.rst
View File

@ -10,7 +10,7 @@ Syntax
bond_style bpm/spring keyword value attribute1 attribute2 ...
* optional keyword = *overlay/pair* or *store/local* or *smooth* or *break*
* optional keyword = *overlay/pair* or *store/local* or *smooth* or *break* or *volume/factor*
.. parsed-literal::
@ -36,6 +36,9 @@ Syntax
*break* value = *yes* or *no*
indicates whether bonds break during a run
*volume/factor* value = *yes* or *no*
indicates whether forces include the volumetric contribution
Examples
""""""""
@ -44,6 +47,9 @@ Examples
bond_style bpm/spring
bond_coeff 1 1.0 0.05 0.1
bond_style bpm/spring volume/factor yes
bond_coeff 1 1.0 0.05 0.1 0.5
bond_style bpm/spring myfix 1000 time id1 id2
dump 1 all local 1000 dump.broken f_myfix[1] f_myfix[2] f_myfix[3]
dump_modify 1 write_header no
@ -97,15 +103,6 @@ approach the critical strain
w = 1.0 - \left( \frac{r - r_0}{r_0 \epsilon_c} \right)^8 .
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data
<read_data>` or :doc:`read_restart <read_restart>` commands:
* :math:`k` (force/distance units)
* :math:`\epsilon_c` (unit less)
* :math:`\gamma` (force/velocity units)
If the *normalize* keyword is set to *yes*, the elastic bond force will be
normalized by :math:`r_0` such that :math:`k` must be given in force units.
@ -123,6 +120,43 @@ during a simulation run. This will prevent some unnecessary calculation.
However, if a bond reaches a strain greater than :math:`\epsilon_c`,
it will trigger an error.
.. versionadded:: TBD
The *volume/factor* keyword toggles whether an additional multibody
contribution is added to he force using the formulation in
:ref:`(Clemmer2) <multibody-Clemmer>`,
.. math::
\alpha_v \left(\left[\frac{V_i + V_j}{V_{0,i} + V_{0,j}}\right]^{1/3} - \frac{r_{ij}}{r_{0,ij}}\right)
where :math:`\alpha_v` is a user specified coefficient and :math:`V_i`
and :math:`V_{0,i}` are estimates of the current and local volume
of atom :math:`i`. These volumes are calculated as the sum of current
or initial bond lengths cubed. In 2D, the volume is replaced with an area
calculated using bond lengths squared and the cube root in the above equation
is accordingly replaced with a square root. This approximation assumes bonds
are evenly distributed on a spherical surface and neglects constant prefactors
which are irrelevant since only the ratio of volumes matters. This term may be
used to adjust the Poisson's ratio.
If a bond is broken (or created), :math:`V_{0,i}` is updated by subtracting
(or adding) that bond's contribution.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data
<read_data>` or :doc:`read_restart <read_restart>` commands:
* :math:`k` (force/distance units)
* :math:`\epsilon_c` (unit less)
* :math:`\gamma` (force/velocity units)
Additionally, if *volume/factor* is set to *yes*, a fourth coefficient
must be provided:
* :math:`a_v` (force units)
If the *store/local* keyword is used, an internal fix will track bonds that
break during the simulation. Whenever a bond breaks, data is processed
and transferred to an internal fix labeled *fix_ID*. This allows the
@ -213,7 +247,7 @@ Related commands
Default
"""""""
The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *no*, and *break* = *yes*
The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *no*, *break* = *yes*, and *volume/factor* = *no*
----------
@ -224,3 +258,7 @@ The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *
.. _Groot4:
**(Groot)** Groot and Warren, J Chem Phys, 107, 4423-35 (1997).
.. _multibody-Clemmer:
**(Clemmer2)** Clemmer, Monti, Lechman, Soft Matter, 20, 1702 (2024).

8
doc/src/bonds.rst
View File

@ -1,8 +0,0 @@
Bond Styles
###########
.. toctree::
:maxdepth: 1
:glob:
bond_*

2
doc/src/compute_angle_local.rst
View File

@ -78,7 +78,7 @@ system and output the statistics in various ways:
compute 2 all angle/local eng theta v_cos v_cossq set theta t
dump 1 all local 100 tmp.dump c_1[*] c_2[*]
compute 3 all reduce ave c_2[*]
compute 3 all reduce ave c_2[*] inputs local
thermo_style custom step temp press c_3[*]
fix 10 all ave/histo 10 10 100 -1 1 20 c_2[3] mode vector file tmp.histo

2
doc/src/compute_bond_local.rst
View File

@ -139,7 +139,7 @@ output the statistics in various ways:
compute 2 all bond/local engpot dist v_dsq set dist d
dump 1 all local 100 tmp.dump c_1[*] c_2[*]
compute 3 all reduce ave c_2[*]
compute 3 all reduce ave c_2[*] inputs local
thermo_style custom step temp press c_3[*]
fix 10 all ave/histo 10 10 100 0 6 20 c_2[3] mode vector file tmp.histo

4
doc/src/compute_composition_atom.rst
View File

@ -88,6 +88,10 @@ too frequently.
----------
.. include:: accel_styles.rst
----------
Output info
"""""""""""

2
doc/src/compute_dihedral_local.rst
View File

@ -76,7 +76,7 @@ angle in the system and output the statistics in various ways:
compute 2 all dihedral/local phi v_cos v_cossq set phi p
dump 1 all local 100 tmp.dump c_1[*] c_2[*]
compute 3 all reduce ave c_2[*]
compute 3 all reduce ave c_2[*] inputs local
thermo_style custom step temp press c_3[*]
fix 10 all ave/histo 10 10 100 -1 1 20 c_2[2] mode vector file tmp.histo

4
doc/src/compute_pressure.rst
View File

@ -125,10 +125,6 @@ where thermo_temp is the ID of a similarly defined compute of style
----------
.. include:: accel_styles.rst
----------
Output info
"""""""""""

10
doc/src/compute_reduce.rst
View File

@ -206,11 +206,13 @@ IDs and the bond stretch will be printed with thermodynamic output.
The *inputs* keyword allows selection of whether all the inputs are
per-atom or local quantities. As noted above, all the inputs must be
the same kind (per-atom or local). Per-atom is the default setting.
If a compute or fix is specified as an input, it must produce per-atom
or local data to match this setting. If it produces both, e.g. for
the same kind (per-atom or local). Per-atom is the default setting. If
a compute or fix is specified as an input, it must produce per-atom or
local data to match this setting. If it produces both, like for example
the :doc:`compute voronoi/atom <compute_voronoi_atom>` command, then
this keyword selects between them.
this keyword selects between them. If a compute *only* produces local
data, like for example the :doc:`compute bond/local command
<compute_bond_local>`, the setting "inputs local" is *required*.
----------

93
doc/src/compute_reduce_chunk.rst
View File

@ -37,55 +37,57 @@ Description
Define a calculation that reduces one or more per-atom vectors into
per-chunk values. This can be useful for diagnostic output. Or when
used in conjunction with the :doc:`compute chunk/spread/atom <compute_chunk_spread_atom>` command it can be
used to create per-atom values that induce a new set of chunks with a
second :doc:`compute chunk/atom <compute_chunk_atom>` command. An
example is given below.
used in conjunction with the :doc:`compute chunk/spread/atom
<compute_chunk_spread_atom>` command it can be used to create per-atom
values that induce a new set of chunks with a second :doc:`compute
chunk/atom <compute_chunk_atom>` command. An example is given below.
In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom <compute_chunk_atom>` command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom <compute_chunk_atom>` and :doc:`Howto chunk <Howto_chunk>`
doc pages for details of how chunks can be defined and examples of how
they can be used to measure properties of a system.
In LAMMPS, chunks are collections of atoms defined by a :doc:`compute
chunk/atom <compute_chunk_atom>` command, which assigns each atom to a
single chunk (or no chunk). The ID for this command is specified as
chunkID. For example, a single chunk could be the atoms in a molecule
or atoms in a spatial bin. See the :doc:`compute chunk/atom
<compute_chunk_atom>` and :doc:`Howto chunk <Howto_chunk>` doc pages for
details of how chunks can be defined and examples of how they can be
used to measure properties of a system.
For each atom, this compute accesses its chunk ID from the specified
*chunkID* compute. The per-atom value from an input contributes
to a per-chunk value corresponding the the chunk ID.
*chunkID* compute. The per-atom value from an input contributes to a
per-chunk value corresponding the chunk ID.
The reduction operation is specified by the *mode* setting and is
performed over all the per-atom values from the atoms in each chunk.
The *sum* option adds the pre-atom values to a per-chunk total. The
*min* or *max* options find the minimum or maximum value of the
per-atom values for each chunk.
The *sum* option adds the per-atom values to a per-chunk total. The
*min* or *max* options find the minimum or maximum value of the per-atom
values for each chunk.
Note that only atoms in the specified group contribute to the
reduction operation. If the *chunkID* compute returns a 0 for the
chunk ID of an atom (i.e., the atom is not in a chunk defined by the
:doc:`compute chunk/atom <compute_chunk_atom>` command), that atom will
also not contribute to the reduction operation. An input that is a
compute or fix may define its own group which affects the quantities
it returns. For example, a compute with return a zero value for atoms
that are not in the group specified for that compute.
Note that only atoms in the specified group contribute to the reduction
operation. If the *chunkID* compute returns a 0 for the chunk ID of an
atom (i.e., the atom is not in a chunk defined by the :doc:`compute
chunk/atom <compute_chunk_atom>` command), that atom will also not
contribute to the reduction operation. An input that is a compute or
fix may define its own group which affects the quantities it returns.
For example, a compute will return a zero value for atoms that are not
in the group specified for that compute.
Each listed input is operated on independently. Each input can be the
result of a :doc:`compute <compute>` or :doc:`fix <fix>` or the evaluation
of an atom-style :doc:`variable <variable>`.
result of a :doc:`compute <compute>` or :doc:`fix <fix>` or the
evaluation of an atom-style :doc:`variable <variable>`.
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
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 "m\*" or
"m\*n". If :math:`N` is 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 :math:`N`. A leading
asterisk means all indices from 1 to n (inclusive). A trailing
asterisk means all indices from n to :math:`N` (inclusive). A middle asterisk
means all indices from m to n (inclusive).
"m\*n". If :math:`N` is 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 :math:`N`.
A leading asterisk means all indices from 1 to n (inclusive). A
trailing asterisk means all indices from n to :math:`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. For example, the following two compute reduce/chunk
commands are equivalent, since the
:doc:`compute property/chunk <compute_property_chunk>` command creates a per-atom
had been listed one by one. For example, the following two compute
reduce/chunk commands are equivalent, since the :doc:`compute
property/chunk <compute_property_chunk>` command creates a per-atom
array with 3 columns:
.. code-block:: LAMMPS
@ -164,13 +166,14 @@ Output info
"""""""""""
This compute calculates a global vector if a single input value is
specified, otherwise a global array is output. The number of columns
in the array is the number of inputs provided. The length of the
vector or the number of vector elements or array rows = the number of
chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom <compute_chunk_atom>` command. The vector or array can
be accessed by any command that uses global values from a compute as
input. See the :doc:`Howto output <Howto_output>` page for an
overview of LAMMPS output options.
specified, otherwise a global array is output. The number of columns in
the array is the number of inputs provided. The length of the vector or
the number of vector elements or array rows = the number of chunks
*Nchunk* as calculated by the specified :doc:`compute chunk/atom
<compute_chunk_atom>` command. The vector or array can be accessed by
any command that uses global values from a compute as input. See the
:doc:`Howto output <Howto_output>` page for an overview of LAMMPS output
options.
The per-atom values for the vector or each column of the array will be
in whatever :doc:`units <units>` the corresponding input value is in.
@ -183,7 +186,9 @@ Restrictions
Related commands
""""""""""""""""
:doc:`compute chunk/atom <compute_chunk_atom>`, :doc:`compute reduce <compute_reduce>`, :doc:`compute chunk/spread/atom <compute_chunk_spread_atom>`
:doc:`compute chunk/atom <compute_chunk_atom>`,
:doc:`compute reduce <compute_reduce>`,
:doc:`compute chunk/spread/atom <compute_chunk_spread_atom>`
Default
"""""""

2
doc/src/compute_rheo_property_atom.rst
View File

@ -81,7 +81,7 @@ includes *xx*, *xy*, *yx*, and *yy*. In 3D, this includes *xx*, *xy*, *xz*,
Many properties require their respective fixes, listed below in related
commands, be defined. For instance, the *viscosity* attribute is the
viscosity of a particle calculated by
:doc:`fix rheo/viscous <fix_rheo_viscosity>`. The meaning of less obvious
:doc:`fix rheo/viscosity <fix_rheo_viscosity>`. The meaning of less obvious
properties is described below.
The *phase* property indicates whether the particle is in a fluid state,

3
doc/src/compute_stress_mop.rst
View File

@ -129,6 +129,9 @@ package <Build_package>` doc page on for more info.
The method is implemented for orthogonal simulation boxes whose
size does not change in time, and axis-aligned planes.
Contributions from bonds, angles, and dihedrals are not compatible
with MPI parallel runs.
The method only works with two-body pair interactions, because it
requires the class method ``Pair::single()`` to be implemented, which is
not possible for manybody potentials. In particular, compute

6
doc/src/compute_temp_deform.rst
View File

@ -128,6 +128,12 @@ See the :doc:`Howto thermostat <Howto_thermostat>` page for a
discussion of different ways to compute temperature and perform
thermostatting.
----------
.. include:: accel_styles.rst
----------
Output info
"""""""""""

8
doc/src/compute_temp_partial.rst
View File

@ -46,7 +46,7 @@ degrees of freedom.
A symmetric tensor, stored as a six-element vector, is also calculated
by this compute for use in the computation of a pressure tensor by the
:doc:`compute pressue <compute_pressure>` command. The formula for
:doc:`compute pressure <compute_pressure>` command. The formula for
the components of the tensor is the same as the above expression for
:math:`E_\mathrm{kin}`, except that the 1/2 factor is NOT included and
the :math:`v_i^2` is replaced by :math:`v_{i,x} v_{i,y}` for the
@ -82,12 +82,6 @@ See the :doc:`Howto thermostat <Howto_thermostat>` page for a
discussion of different ways to compute temperature and perform
thermostatting.
----------
.. include:: accel_styles.rst
----------
Output info
"""""""""""

8
doc/src/computes.rst
View File

@ -1,8 +0,0 @@
Computes
########
.. toctree::
:maxdepth: 1
:glob:
compute_*

8
doc/src/dihedrals.rst
View File

@ -1,8 +0,0 @@
Dihedral Styles
###############
.. toctree::
:maxdepth: 1
:glob:
dihedral_*

1
doc/src/fix.rst
View File

@ -357,6 +357,7 @@ accelerated styles exist.
* :doc:`python/move <fix_python_move>` - move particles using a Python function during a simulation run
* :doc:`qbmsst <fix_qbmsst>` - quantum bath multi-scale shock technique time integrator
* :doc:`qeq/comb <fix_qeq_comb>` - charge equilibration for COMB potential
* :doc:`qeq/ctip <fix_qeq>` - charge equilibration for CTIP potential
* :doc:`qeq/dynamic <fix_qeq>` - charge equilibration via dynamic method
* :doc:`qeq/fire <fix_qeq>` - charge equilibration via FIRE minimizer
* :doc:`qeq/point <fix_qeq>` - charge equilibration via point method

88
doc/src/fix_adapt.rst
View File

@ -319,25 +319,36 @@ all types from 1 to :math:`N`. A leading asterisk means all types from
:math:`N` (inclusive). A middle asterisk means all types from m to n
(inclusive).
Currently *bond* does not support bond_style hybrid nor bond_style
hybrid/overlay as bond styles. The bond styles that currently work
with fix_adapt are
If :doc:`bond_style hybrid <bond_hybrid>` is used, *bstyle* should be a
sub-style name. The bond styles that currently work with fix adapt are:
+------------------------------------+------------+------------+
| :doc:`class2 <bond_class2>` | r0 | type bonds |
+------------------------------------+------------+------------+
| :doc:`fene <bond_fene>` | k,r0 | type bonds |
+------------------------------------+------------+------------+
| :doc:`fene/nm <bond_fene>` | k,r0 | type bonds |
+------------------------------------+------------+------------+
| :doc:`gromos <bond_gromos>` | k,r0 | type bonds |
+------------------------------------+------------+------------+
| :doc:`harmonic <bond_harmonic>` | k,r0 | type bonds |
+------------------------------------+------------+------------+
| :doc:`morse <bond_morse>` | r0 | type bonds |
+------------------------------------+------------+------------+
| :doc:`nonlinear <bond_nonlinear>` | epsilon,r0 | type bonds |
+------------------------------------+------------+------------+
+-----------------------------------------------------+---------------------------+------------+
| :doc:`class2 <bond_class2>` | k2,k3,k4,r0 | type bonds |
+-----------------------------------------------------+---------------------------+------------+
| :doc:`fene <bond_fene>` | k,r0 | type bonds |
+-----------------------------------------------------+---------------------------+------------+
| :doc:`fene/expand <bond_fene_expand>` | k,r0,epsilon,sigma,shift | type bonds |
+-----------------------------------------------------+---------------------------+------------+
| :doc:`fene/nm <bond_fene>` | k,r0 | type bonds |
+-----------------------------------------------------+---------------------------+------------+
| :doc:`gaussian <bond_gaussian>` | alpha,width,r0 | type bonds |
+-----------------------------------------------------+---------------------------+------------+
| :doc:`gromos <bond_gromos>` | k,r0 | type bonds |
+-----------------------------------------------------+---------------------------+------------+
| :doc:`harmonic <bond_harmonic>` | k,r0 | type bonds |
+-----------------------------------------------------+---------------------------+------------+
| :doc:`harmonic/restrain <bond_harmonic_restrain>` | k | type bonds |
+-----------------------------------------------------+---------------------------+------------+
| :doc:`harmonic/shift <bond_harmonic_shift>` | k,r0,r1 | type bonds |
+-----------------------------------------------------+---------------------------+------------+
| :doc:`harmonic/shift/cut <bond_harmonic_shift_cut>` | k,r0,r1 | type bonds |
+-----------------------------------------------------+---------------------------+------------+
| :doc:`mm3 <bond_mm3>` | k,r0 | type bonds |
+-----------------------------------------------------+---------------------------+------------+
| :doc:`morse <bond_morse>` | d0,alpha,r0 | type bonds |
+-----------------------------------------------------+---------------------------+------------+
| :doc:`nonlinear <bond_nonlinear>` | lamda,epsilon,r0 | type bonds |
+-----------------------------------------------------+---------------------------+------------+
----------
@ -357,15 +368,40 @@ all types from 1 to :math:`N`. A leading asterisk means all types from
:math:`N` (inclusive). A middle asterisk means all types from m to n
(inclusive).
Currently *angle* does not support angle_style hybrid nor angle_style
hybrid/overlay as angle styles. The angle styles that currently work
with fix_adapt are
If :doc:`angle_style hybrid <angle_hybrid>` is used, *astyle* should be a
sub-style name. The angle styles that currently work with fix adapt are:
+------------------------------------+----------+-------------+
| :doc:`harmonic <angle_harmonic>` | k,theta0 | type angles |
+------------------------------------+----------+-------------+
| :doc:`cosine <angle_cosine>` | k | type angles |
+------------------------------------+----------+-------------+
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`harmonic <angle_harmonic>` | k,theta0 | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`charmm <angle_charmm>` | k,theta0 | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`class2 <angle_class2>` | k2,k3,k4,theta0 | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`cosine <angle_cosine>` | k | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`cosine/delta <angle_cosine_delta>` | k | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`cosine/periodic <angle_cosine_periodic>` | k,b,n | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`cosine/squared <angle_cosine_squared>` | k,theta0 | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`cosine/squared/restricted <angle_cosine_squared_restricted>` | k,theta0 | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`dipole <angle_dipole>` | k,gamma0 | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`fourier <angle_fourier>` | k,c0,c1,c2 | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`fourier/simple <angle_fourier_simple>` | k,c,n | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`gaussian <angle_gaussian>` | alpha,width,theta0 | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`mm3 <angle_mm3>` | k,theta0 | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`quartic <angle_quartic>` | k2,k3,k4,theta0 | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
| :doc:`spica <angle_spica>` | k,theta0 | type angles |
+--------------------------------------------------------------------+--------------------+-------------+
Note that internally, theta0 is stored in radians, so the variable
this fix uses to reset theta0 needs to generate values in radians.

4
doc/src/fix_addforce.rst
View File

@ -115,10 +115,6 @@ correctly, the minimization will not converge properly.
----------
.. include:: accel_styles.rst
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

13
doc/src/fix_atom_swap.rst
View File

@ -119,15 +119,14 @@ groups of atoms that have different charges, these charges will not be
changed when the atom types change.
Since this fix computes total potential energies before and after
proposed swaps, so even complicated potential energy calculations are
OK, including the following:
proposed swaps, even complicated potential energy calculations are
acceptable, including the following:
* long-range electrostatics (:math:`k`-space)
* many body pair styles
* hybrid pair styles
* eam pair styles
* hybrid pair styles (with restrictions)
* EAM pair styles
* triclinic systems
* need to include potential energy contributions from other fixes
Some fixes have an associated potential energy. Examples of such fixes
include: :doc:`efield <fix_efield>`, :doc:`gravity <fix_gravity>`,
@ -181,6 +180,10 @@ This fix is part of the MC package. It is only enabled if LAMMPS was
built with that package. See the :doc:`Build package <Build_package>`
doc page for more info.
When this fix is used with a :doc:`hybrid pair style <pair_hybrid>`
system, only swaps between atom types of the same sub-style (or
combination of sub-styles) are permitted.
This fix cannot be used with systems that do not have per-type masses
(e.g. atom style sphere) since the implemented algorithm pre-computes
velocity rescaling factors from per-type masses and ignores any per-atom

4
doc/src/fix_aveforce.rst
View File

@ -71,10 +71,6 @@ to it.
----------
.. include:: accel_styles.rst
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

13
doc/src/fix_gcmc.rst
View File

@ -50,8 +50,8 @@ Syntax
*intra_energy* value = intramolecular energy (energy units)
*tfac_insert* value = scale up/down temperature of inserted atoms (unitless)
*overlap_cutoff* value = maximum pair distance for overlap rejection (distance units)
*max* value = Maximum number of molecules allowed in the system
*min* value = Minimum number of molecules allowed in the system
*max* value = Maximum number of atoms allowed in the fix group (and region)
*min* value = Minimum number of atoms allowed in the fix group (and region)
Examples
""""""""
@ -380,10 +380,11 @@ an infinite positive energy to all new configurations that place any
pair of atoms closer than the specified overlap cutoff distance.
The *max* and *min* keywords allow for the restriction of the number of
atoms in the simulation. They automatically reject all insertion or
deletion moves that would take the system beyond the set boundaries.
Should the system already be beyond the boundary, only moves that bring
the system closer to the bounds may be accepted.
atoms in the fix group (and region in case the *region* keyword is
used). They automatically reject all insertion or deletion moves that
would take the system beyond the set boundaries. Should the system
already be beyond the boundary, only moves that bring the system closer
to the bounds may be accepted.
The *group* keyword adds all inserted atoms to the :doc:`group <group>`
of the group-ID value. The *grouptype* keyword adds all inserted atoms

2
doc/src/fix_halt.rst
View File

@ -101,7 +101,7 @@ hstyle = bondmax option.
.. code-block:: LAMMPS
compute bdist all bond/local dist
compute bmax all reduce max c_bdist
compute bmax all reduce max c_bdist inputs local
variable bondmax equal c_bmax
Thus these two versions of a fix halt command will do the same thing:

6
doc/src/fix_langevin.rst
View File

@ -231,12 +231,6 @@ the particles. As described below, this energy can then be printed
out or added to the potential energy of the system to monitor energy
conservation.
.. note::
This accumulated energy does NOT include kinetic energy removed
by the *zero* flag. LAMMPS will print a warning when both options are
active.
The keyword *zero* can be used to eliminate drift due to the
thermostat. Because the random forces on different atoms are
independent, they do not sum exactly to zero. As a result, this fix

7
doc/src/fix_nonaffine_displacement.rst
View File

@ -102,7 +102,6 @@ zeroed. The *update* reference style implies the reference state will be updated
*nstep* timesteps. The *offset* reference will update the reference state *nstep*
timesteps before a multiple of *nevery* timesteps.
----------
Restart, fix_modify, output, run start/stop, minimize info
@ -129,6 +128,12 @@ This compute is part of the EXTRA-FIX package. It is only enabled if
LAMMPS was built with that package. See the
:doc:`Build package <Build_package>` page for more info.
As this fix depends on a run including specific reference timesteps, it
currently does not update peratom values if used in conjunction with the
:doc:`rerun command <rerun>` since it cannot ensure the necessary reference
timesteps are included.
Related commands
""""""""""""""""

2
doc/src/fix_nph_body.rst
View File

@ -79,8 +79,6 @@ It also means that changing attributes of *thermo_temp* or
----------
.. include:: accel_styles.rst
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

2
doc/src/fix_npt_body.rst
View File

@ -103,8 +103,6 @@ remaining thermal degrees of freedom, and the bias is added back in.
----------
.. include:: accel_styles.rst
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

2
doc/src/fix_nvt_body.rst
View File

@ -85,8 +85,6 @@ remaining thermal degrees of freedom, and the bias is added back in.
----------
.. include:: accel_styles.rst
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

16
doc/src/fix_pour.rst
View File

@ -155,6 +155,22 @@ many timesteps until the desired # of particles has been inserted.
the :doc:`compute_modify dynamic/dof yes <compute_modify>` command
for the temperature compute you are using.
.. admonition:: Implementation Notes
:class: Hint
The exact insertion procedure depends on many factors (e.g. the range of
diameters inserted or whether molecules are being inserted). However, in
the simplest scenario of monodisperse atoms, the procedure works as
follows. First, the number of timesteps between two insertion events is
calculated as the time for a particle to fall through the insertion region,
accounting for gravity and any region motion. Next, the target number of
particles inserted per event (assuming no failed insertions due to overlaps)
is calculated as the product of the volume fraction and the volume of the
insertion region divided by the volume of a particle (or area in 2D).
Events are repeated until all N particles have been inserted, where
the final event is likely interrupted upon reaching N. Estimates of this
process are printed to the log/screen at the start of a run.
----------
All other keywords are optional with defaults as shown below.

60
doc/src/fix_qeq.rst
View File

@ -1,6 +1,7 @@
.. index:: fix qeq/point
.. index:: fix qeq/shielded
.. index:: fix qeq/slater
.. index:: fix qeq/ctip
.. index:: fix qeq/dynamic
.. index:: fix qeq/fire
@ -13,6 +14,9 @@ fix qeq/shielded command
fix qeq/slater command
======================
fix qeq/ctip command
====================
fix qeq/dynamic command
=======================
@ -27,18 +31,20 @@ Syntax
fix ID group-ID style Nevery cutoff tolerance maxiter qfile keyword ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* style = *qeq/point* or *qeq/shielded* or *qeq/slater* or *qeq/dynamic* or *qeq/fire*
* style = *qeq/point* or *qeq/shielded* or *qeq/slater* or *qeq/ctip* or *qeq/dynamic* or *qeq/fire*
* Nevery = perform charge equilibration every this many steps
* cutoff = global cutoff for charge-charge interactions (distance unit)
* tolerance = precision to which charges will be equilibrated
* maxiter = maximum iterations to perform charge equilibration
* qfile = a filename with QEq parameters or *coul/streitz* or *reaxff*
* qfile = a filename with QEq parameters or *coul/streitz* or *coul/ctip* or *reaxff*
* zero or more keyword/value pairs may be appended
* keyword = *alpha* or *qdamp* or *qstep* or *warn*
* keyword = *alpha* or *cdamp* or *maxrepeat* or *qdamp* or *qstep* or *warn*
.. parsed-literal::
*alpha* value = Slater type orbital exponent (qeq/slater only)
*cdamp* value = damping parameter for Coulomb interactions (qeq/ctip only)
*maxrepeat* value = number of equilibration cycles allowed to ensure no atoms cross charge bounds (qeq/ctip only)
*qdamp* value = damping factor for damped dynamics charge solver (qeq/dynamic and qeq/fire only)
*qstep* value = time step size for damped dynamics charge solver (qeq/dynamic and qeq/fire only)
*warn* value = do (=yes) or do not (=no) print a warning when the maximum number of iterations is reached
@ -51,6 +57,7 @@ Examples
fix 1 all qeq/point 1 10 1.0e-6 200 param.qeq1
fix 1 qeq qeq/shielded 1 8 1.0e-6 100 param.qeq2
fix 1 all qeq/slater 5 10 1.0e-6 100 params alpha 0.2
fix 1 all qeq/ctip 1 12 1.0e-8 100 coul/ctip cdamp 0.30 maxrepeat 10
fix 1 qeq qeq/dynamic 1 12 1.0e-3 100 my_qeq
fix 1 all qeq/fire 1 10 1.0e-3 100 my_qeq qdamp 0.2 qstep 0.1
@ -103,7 +110,7 @@ equalizes the derivative of energy with respect to charge of all the
atoms) by adjusting the partial charge on individual atoms based on
interactions with their neighbors within *cutoff*\ . It requires a few
parameters in the appropriate units for each atom type which are read
from a file specified by *qfile*\ . The file has the following format
from a file specified by *qfile*\ . The file has the following format:
.. parsed-literal::
@ -112,20 +119,32 @@ from a file specified by *qfile*\ . The file has the following format
...
Ntype chi eta gamma zeta qcore
except for fix style *qeq/ctip* where the format is:
.. parsed-literal::
1 chi eta gamma zeta qcore qmin qmax omega
2 chi eta gamma zeta qcore qmin qmax omega
...
Ntype chi eta gamma zeta qcore qmin qmax omega
There have to be parameters given for every atom type. Wildcard entries
are possible using the same type range syntax as for "coeff" commands
(i.e., n\*m, n\*, \*m, \*). Later entries will overwrite previous ones.
Empty lines or any text following the pound sign (#) are ignored.
Each line starts with the atom type followed by five parameters.
Only a subset of the parameters is used by each QEq style as described
below, thus the others can be set to 0.0 if desired, but all five
entries per line are required.
Empty lines or any text following the pound sign (#) are ignored. Each
line starts with the atom type followed by eight parameters. Only a
subset of the parameters is used by each QEq style as described below,
thus the others can be set to 0.0 if desired, but all eight entries per
line are required.
* *chi* = electronegativity in energy units
* *eta* = self-Coulomb potential in energy units
* *gamma* = shielded Coulomb constant defined by :ref:`ReaxFF force field <vanDuin>` in distance units
* *zeta* = Slater type orbital exponent defined by the :ref:`Streitz-Mintmire <Streitz1>` potential in reverse distance units
* *qcore* = charge of the nucleus defined by the :ref:`Streitz-Mintmire potential <Streitz1>` potential in charge units
* *qmin* = lower bound on the allowed charge defined by the :ref:`CTIP <CTIP1>` potential in charge units
* *qmax* = upper bound on the allowed charge defined by the :ref:`CTIP <CTIP1>` potential in charge units
* *omega* = penalty parameter used to enforce charge bounds defined by the :ref:`CTIP <CTIP1>` potential in energy units
The fix qeq styles will print a warning if the charges are not
equilibrated within *tolerance* by *maxiter* steps, unless the
@ -171,6 +190,22 @@ on atoms via the matrix inversion method. A tolerance of 1.0e-6 is
usually a good number. Keyword *alpha* can be used to change the Slater
type orbital exponent.
.. versionadded:: TBD
The *qeq/ctip* style describes partial charges on atoms in the same way
as style *qeq/shielded* but also enables the definition of charge
bounds. Only the *chi*, *eta*, *gamma*, *qmin*, *qmax*, and *omega*
parameters from the *qfile* file are used. When using the string
*coul/ctip* as filename, these parameters are extracted directly from an
active *coul/ctip* pair style. This style solves partial charges on
atoms via the matrix inversion method. Keyword *cdamp* can be used to
change the damping parameter used to calculate Coulomb interactions.
Keyword *maxrepeat* can be used to adjust the number of equilibration
cycles allowed to ensure no atoms have crossed the charge bounds. A
value of 10 is usually a good choice. A tolerance between 1.0e-6 and
1.0e-8 is usually a good choice but should be checked in conjunction
with the timestep for adequate energy conservation during dynamic runs.
The *qeq/dynamic* style describes partial charges on atoms as point
charges that interact through 1/r, but the extended Lagrangian method is
used to solve partial charges on atoms. Only the *chi* and *eta*
@ -186,7 +221,7 @@ minimization algorithm to solve for equilibrium charges. Keyword
*qdamp* can be used to change the damping factor, while keyword *qstep*
can be used to change the time step size.
Note that *qeq/point*, *qeq/shielded*, and *qeq/slater* describe
Note that *qeq/point*, *qeq/shielded*, *qeq/slater*, and *qeq/ctip* describe
different charge models, whereas the matrix inversion method and the
extended Lagrangian method (\ *qeq/dynamic* and *qeq/fire*\ ) are
different solvers.
@ -266,6 +301,11 @@ Chemistry, 95, 3358-3363 (1991).
**(Streitz-Mintmire)** F. H. Streitz, J. W. Mintmire, Physical Review B, 50,
16, 11996 (1994)
.. _CTIP1:
**(CTIP)** G. Plummer, J. P. Tavenner, M. I. Mendelev, Z. Wu, J. W. Lawson,
in preparation
.. _vanDuin:
**(ReaxFF)** A. C. T. van Duin, S. Dasgupta, F. Lorant, W. A. Goddard III, J

3
doc/src/fix_rheo.rst
View File

@ -16,8 +16,7 @@ Syntax
* kstyle = *quintic* or *RK0* or *RK1* or *RK2*
* zmin = minimal number of neighbors for reproducing kernels
* zero or more keyword/value pairs may be appended to args
* keyword = *thermal* or *interface/reconstruct* or *surface/detection* or
*shift* or *rho/sum* or *density* or *self/mass* or *speed/sound*
* keyword = *thermal* or *interface/reconstruct* or *surface/detection* or *shift* or *rho/sum* or *density* or *self/mass* or *speed/sound*
.. parsed-literal::

6
doc/src/fix_wall_flow.rst
View File

@ -123,6 +123,12 @@ also be potentially mitigated by using more multiple walls.
conservative as possible (every timestep if needed). Those are the
default settings.
----------
.. include:: accel_styles.rst
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

8
doc/src/fixes.rst
View File

@ -1,8 +0,0 @@
Fixes
#####
.. toctree::
:maxdepth: 1
:glob:
fix_*

4
doc/src/group.rst
View File

@ -162,7 +162,7 @@ potential energy is above the threshold value :math:`-3.0`.
compute 1 all pe/atom
compute 2 all reduce sum c_1
thermo_style custom step temp pe c_2
run 0
run 0 post no
variable eatom atom "c_1 > -3.0"
group hienergy variable eatom
@ -173,7 +173,7 @@ Note that these lines
compute 2 all reduce sum c_1
thermo_style custom step temp pe c_2
run 0
run 0 post no
are necessary to ensure that the "eatom" variable is current when the
group command invokes it. Because the eatom variable computes the

2
doc/src/group2ndx.rst
View File

@ -51,7 +51,7 @@ index file. When specifying group IDs, only those groups will be
written to the index file. In order to follow the Gromacs conventions,
the group *all* will be renamed to *System* in the index file.
The *ndx2group* command will create of update group definitions from
The *ndx2group* command will create or update group definitions from
those stored in an index file. Without specifying any group IDs, all
groups except *System* will be read from the index file and the
corresponding groups recreated. If a group of the same name already

8
doc/src/impropers.rst
View File

@ -1,8 +0,0 @@
Improper Styles
###############
.. toctree::
:maxdepth: 1
:glob:
improper_*

2
doc/src/min_style.rst
View File

@ -3,6 +3,8 @@
min_style cg command
====================
Accelerator Variant: *cg/kk*
min_style hftn command
======================

35
doc/src/pair_bpm_spring.rst
View File

@ -8,7 +8,14 @@ Syntax
.. code-block:: LAMMPS
pair_style bpm/spring
pair_style bpm/spring keyword value ...
* optional keyword = *anharmonic*
.. parsed-literal::
*anharmonic* value = *yes* or *no*
whether forces include the anharmonic term
Examples
""""""""
@ -17,7 +24,8 @@ Examples
pair_style bpm/spring
pair_coeff * * 1.0 1.0 1.0
pair_coeff 1 1 1.0 1.0 1.0
pair_style bpm/spring anharmonic yes
pair_coeff 1 1 1.0 1.0 1.0 50.0
Description
"""""""""""
@ -28,12 +36,16 @@ Style *bpm/spring* computes pairwise forces with the formula
.. math::
F = k (r - r_c)
F = k (r - r_c) + k_a (r - r_c)^3
where :math:`k` is a stiffness and :math:`r_c` is the cutoff length.
An additional damping force is also applied to interacting
particles. The force is proportional to the difference in the
normal velocity of particles
where :math:`k` is a stiffness, :math:`r_c` is the cutoff
length, and :math:`k_a` is an optional anharmonic cubic prefactor
that can be enabled using the *anharmonic* keyword. The anharmonic
term may be useful in scenarios that need to prevent large particle overlap.
An additional damping force is also applied to interacting particles.
The force is proportional to the difference in the normal velocity of
particles
.. math::
@ -73,6 +85,12 @@ commands, or by mixing as described below:
* :math:`r_c` (distance units)
* :math:`\gamma` (force/velocity units)
.. versionadded:: TBD
Additionally, if *anharmonic* is set to *yes*, a fourth coefficient
must be provided:
* :math:`k_a` (force/distance\^3 units)
----------
@ -117,4 +135,5 @@ Related commands
Default
"""""""
none
The option defaults are *anharmonic* = *no*

3
doc/src/pair_brownian.rst
View File

@ -1,12 +1,13 @@
.. index:: pair_style brownian
.. index:: pair_style brownian/omp
.. index:: pair_style brownian/kk
.. index:: pair_style brownian/poly
.. index:: pair_style brownian/poly/omp
pair_style brownian command
===========================
Accelerator Variants: *brownian/omp*
Accelerator Variants: *brownian/omp*, *brownian/kk*
pair_style brownian/poly command
================================

55
doc/src/pair_coul.rst
View File

@ -4,6 +4,7 @@
.. index:: pair_style coul/cut/omp
.. index:: pair_style coul/cut/global
.. index:: pair_style coul/cut/global/omp
.. index:: pair_style coul/ctip
.. index:: pair_style coul/debye
.. index:: pair_style coul/debye/gpu
.. index:: pair_style coul/debye/kk
@ -38,6 +39,9 @@ pair_style coul/cut/global command
Accelerator Variants: *coul/cut/omp*
pair_style coul/ctip command
============================
pair_style coul/debye command
=============================
@ -79,7 +83,6 @@ pair_style tip4p/long command
Accelerator Variants: *tip4p/long/omp*
Syntax
""""""
@ -87,6 +90,7 @@ Syntax
pair_style coul/cut cutoff
pair_style coul/cut/global cutoff
pair_style coul/ctip alpha cutoff
pair_style coul/debye kappa cutoff
pair_style coul/dsf alpha cutoff
pair_style coul/exclude cutoff
@ -116,6 +120,9 @@ Examples
pair_coeff * *
pair_coeff 2 2 3.5
pair_style coul/ctip 0.30 12.0
pair_coeff * * NiO.ctip Ni O
pair_style coul/debye 1.4 3.0
pair_coeff * *
pair_coeff 2 2 3.5
@ -173,6 +180,33 @@ coulomb styles in :doc:`hybrid pair styles <pair_hybrid>`.
----------
.. versionadded:: TBD
Style *coul/ctip* computes the Coulomb interactions as described in
:ref:`Plummer <Plummer1>`. It uses the the damped shifted model as in
style *coul/dsf* but is further extended to the second derivative of the
potential and incorporates empirical charge shielding meant to
approximate the more expensive Coulomb integrals used in style
*coul/streitz*. More details can be found in the referenced paper. Like
the style *coul/streitz*, style *coul/ctip* is a variable charge
potential and must be hybridized with a short-range potential via the
:doc:`pair_style hybrid/overlay <pair_hybrid>` command. Charge
equilibration must be performed with the :doc:`fix qeq/ctip <fix_qeq>`
command. For example:
.. code-block:: LAMMPS
pair_style hybrid/overlay eam/fs coul/ctip 0.30 12.0
pair_coeff * * eam/fs NiO.eam.fs Ni O
pair_coeff * * coul/ctip NiO.ctip Ni O
fix 1 all qeq/ctip 1 12.0 1.0e-8 100 coul/ctip cdamp 0.30 maxrepeat 10
See the examples/ctip directory for an example input script using the
CTIP potential. An Ni-O CTIP and EAM/FS parameterization are included
for use with the example.
----------
Style *coul/debye* adds an additional exp() damping factor to the
Coulombic term, given by
@ -399,16 +433,18 @@ Restrictions
""""""""""""
The *coul/long*, *coul/msm*, *coul/streitz*, and *tip4p/long* styles are
part of the KSPACE package. The *coul/cut/global*, *coul/exclude* styles are
part of the EXTRA-PAIR package. The *tip4p/cut* style is part of the MOLECULE
package. A pair style is only enabled if LAMMPS was built with its
corresponding package. See the :doc:`Build package <Build_package>`
doc page for more info.
part of the KSPACE package. The *coul/cut/global*, *coul/exclude*, and
*coul/ctip* styles are part of the EXTRA-PAIR package. The *tip4p/cut*
style is part of the MOLECULE package. A pair style is only enabled if
LAMMPS was built with its corresponding package. See the
:doc:`Build package <Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`pair_coeff <pair_coeff>`, :doc:`pair_style, hybrid/overlay <pair_hybrid>`, :doc:`kspace_style <kspace_style>`
:doc:`pair_coeff <pair_coeff>`,
:doc:`pair_style hybrid/overlay <pair_hybrid>`,
:doc:`kspace_style <kspace_style>`
Default
"""""""
@ -432,6 +468,11 @@ Phys, 110, 8254 (1999).
**(Streitz)** F. H. Streitz, J. W. Mintmire, Phys Rev B, 50, 11996-12003
(1994).
.. _Plummer1:
**(Plummer)** G. Plummer, J. P. Tavenner, M. I. Mendelev, Z. Wu, J. W. Lawson,
in preparation
.. _Jorgensen3:
**(Jorgensen)** Jorgensen, Chandrasekhar, Madura, Impey, Klein, J Chem

4
doc/src/pair_coul_diel.rst
View File

@ -71,6 +71,10 @@ The global cutoff (:math:`r_c`) specified in the pair_style command is used.
----------
.. include:: accel_styles.rst
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

4
doc/src/pair_coul_slater.rst
View File

@ -77,6 +77,10 @@ The global decay length of the charge (:math:`\lambda`) specified in the pair_st
----------
.. include:: accel_styles.rst
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

4
doc/src/pair_granular.rst
View File

@ -741,10 +741,6 @@ atom types.
----------
.. include:: accel_styles.rst
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

4
doc/src/pair_mesodpd.rst
View File

@ -287,6 +287,10 @@ concentration profiles of the two chemical species as
----------
.. include:: accel_styles.rst
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

4
doc/src/pair_mie.rst
View File

@ -62,6 +62,10 @@ cutoff specified in the pair_style command is used.
----------
.. include:: accel_styles.rst
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

4
doc/src/pair_sph_heatconduction.rst
View File

@ -39,6 +39,10 @@ above.
----------
.. include:: accel_styles.rst
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

4
doc/src/pair_sph_lj.rst
View File

@ -43,6 +43,10 @@ above.
----------
.. include:: accel_styles.rst
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

4
doc/src/pair_sph_taitwater.rst
View File

@ -52,6 +52,10 @@ above.
----------
.. include:: accel_styles.rst
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

1
doc/src/pair_style.rst
View File

@ -151,6 +151,7 @@ accelerated styles exist.
* :doc:`comb <pair_comb>` - charge-optimized many-body (COMB) potential
* :doc:`comb3 <pair_comb>` - charge-optimized many-body (COMB3) potential
* :doc:`cosine/squared <pair_cosine_squared>` - Cooke-Kremer-Deserno membrane model potential
* :doc:`coul/ctip <pair_coul>` - Charge Transfer Interatomic (Coulomb) Potential
* :doc:`coul/cut <pair_coul>` - cutoff Coulomb potential
* :doc:`coul/cut/dielectric <pair_dielectric>` -
* :doc:`coul/cut/global <pair_coul>` - cutoff Coulomb potential

8
doc/src/pairs.rst
View File

@ -1,8 +0,0 @@
Pair Styles
###########
.. toctree::
:maxdepth: 1
:glob:
pair_*

51
doc/src/read_dump.rst
View File

@ -115,10 +115,11 @@ to tell LAMMPS how many parallel files exist, via its specified
The format of the dump file is selected through the *format* keyword.
If specified, it must be the last keyword used, since all remaining
arguments are passed on to the dump reader. The *native* format is
for native LAMMPS dump files, written with a :doc:`dump atom <dump>`
or :doc:`dump custom <dump>` command. The *xyz* format is for generic XYZ
formatted dump files. These formats take no additional values.
arguments are passed on to the dump reader. The *native* format is for
native LAMMPS dump files, written with a :doc:`dump atom <dump>` or
:doc:`dump custom <dump>` command. The *xyz* format is for generic XYZ
formatted dump files (see details below). These formats take no
additional values.
The *molfile* format supports reading data through using the `VMD <vmd_>`_
molfile plugin interface. This dump reader format is only available,
@ -230,23 +231,39 @@ will then have a label corresponding to the fix-ID rather than "x" or
"xs". The *label* keyword can also be used to specify new column
labels for fields *id* and *type*\ .
For dump files in *xyz* format, only the *x*, *y*, and *z* fields are
supported. The dump file does not store atom IDs, so these are
assigned consecutively to the atoms as they appear in the dump file,
starting from 1. Thus you should ensure that order of atoms is
consistent from snapshot to snapshot in the XYZ dump file. See
the :doc:`dump_modify sort <dump_modify>` command if the XYZ dump file
was written by LAMMPS.
For dump files in *xyz* format, only the *type*, *x*, *y*, and *z*
fields are supported. There are many variants of the XYZ file format.
LAMMPS will read the number of atoms from the first line of each frame,
ignore the second (title) line, and then read one line for each atom in the format:
.. parsed-literal::
<label> <x coordinate> <y coordinate> <z coordinate>
If the atom label is a numeric integer (like with XYZ files created by
created with default settings by :doc:`dump style <dump>` *xyz*), that
number will be used as the atom type. If the atom label is a string,
then a type map must be created using the :doc:`labelmap command
<labelmap>`. This map needs to associate each (numeric) atom type with
a string label. The numeric atom type is stored internally.
The xyz format dump file does not store atom IDs, so these are assigned
consecutively to the atoms as they appear in the dump file, starting
from 1. Thus you should ensure that the order of atoms is consistent
from snapshot to snapshot in the XYZ dump file. See the
:doc:`dump_modify sort <dump_modify>` command if the XYZ dump file was
written by LAMMPS.
For dump files in *molfile* format, the *x*, *y*, *z*, *vx*, *vy*, and
*vz* fields can be specified. However, not all molfile formats store
velocities, or their respective plugins may not support reading of
velocities. The molfile dump files do not store atom IDs, so these
are assigned consecutively to the atoms as they appear in the dump
file, starting from 1. Thus you should ensure that order of atoms are
consistent from snapshot to snapshot in the molfile dump file.
See the :doc:`dump_modify sort <dump_modify>` command if the dump file
was written by LAMMPS.
velocities. The molfile dump files do not store atom IDs, so these are
assigned consecutively to the atoms as they appear in the dump file,
starting from 1. Thus you should ensure that the order of atoms are
consistent from snapshot to snapshot in the molfile dump file. See the
:doc:`dump_modify sort <dump_modify>` command if the dump file was
written by LAMMPS.
The *adios* format supports all fields that the *native* format supports
except for the *q* charge field.

14
doc/src/region.rst
View File

@ -18,13 +18,13 @@ Syntax
*delete* = no args
*block* args = xlo xhi ylo yhi zlo zhi
xlo,xhi,ylo,yhi,zlo,zhi = bounds of block in all dimensions (distance units)
xlo,xhi,ylo,yhi,zlo,zhi can be a variable
xlo,xhi,ylo,yhi,zlo,zhi can be a variable (see below)
*cone* args = dim c1 c2 radlo radhi lo hi
dim = *x* or *y* or *z* = axis of cone
c1,c2 = coords of cone axis in other 2 dimensions (distance units)
radlo,radhi = cone radii at lo and hi end (distance units)
lo,hi = bounds of cone in dim (distance units)
c1,c2,radlo,radhi,lo,hi can be a variable (see below)
c1,c2,radlo,radhi,lo,hi can be a variable (see below)
*cylinder* args = dim c1 c2 radius lo hi
dim = *x* or *y* or *z* = axis of cylinder
c1,c2 = coords of cylinder axis in other 2 dimensions (distance units)
@ -38,6 +38,7 @@ Syntax
*plane* args = px py pz nx ny nz
px,py,pz = point on the plane (distance units)
nx,ny,nz = direction normal to plane (distance units)
px,py,pz can be a variable (see below)
*prism* args = xlo xhi ylo yhi zlo zhi xy xz yz
xlo,xhi,ylo,yhi,zlo,zhi = bounds of untilted prism (distance units)
xy = distance to tilt y in x direction (distance units)
@ -166,7 +167,7 @@ extending in the y-direction from -5.0 to the upper box boundary.
.. versionadded:: 4May2022
For style *ellipsoid*, an axis-aligned ellipsoid is defined. The
For style *ellipsoid*, an axis-aligned ellipsoid is defined. The
ellipsoid has its center at (x,y,z) and is defined by 3 axis-aligned
vectors given by A = (a,0,0); B = (0,b,0); C = (0,0,c). Note that
although the ellipsoid is specified as axis-aligned it can be rotated
@ -206,9 +207,10 @@ parameters a,b,c for style *ellipsoid*, can each be specified as an
equal-style :doc:`variable <variable>`. Likewise, for style *sphere*
and *ellipsoid* the x-, y-, and z- coordinates of the center of the
sphere/ellipsoid can be specified as an equal-style variable. And for
style *cylinder* the two center positions c1 and c2 for the location
of the cylinder axes can be specified as a equal-style variable. For style *cone*
all properties can be defined via equal-style variables.
style *cylinder* the two center positions c1 and c2 for the location of
the cylinder axes can be specified as a equal-style variable. For style
*cone* all properties can be defined via equal-style variables. For
style *plane* the point can be defined via equal-style variables.
If the value is a variable, it should be specified as v_name, where
name is the variable name. In this case, the variable will be