diff --git a/doc/src/accel_styles.rst b/doc/src/accel_styles.rst index 228953335c..11c127794f 100644 --- a/doc/src/accel_styles.rst +++ b/doc/src/accel_styles.rst @@ -6,7 +6,7 @@ page. The accelerated styles take the same arguments and should produce the same results, except for round-off and precision issues. These accelerated styles are part of the GPU, INTEL, KOKKOS, -OPENMP and OPT packages, respectively. They are only enabled if +OPENMP, and OPT packages, respectively. They are only enabled if LAMMPS was built with those packages. See the :doc:`Build package ` page for more info. You can specify the accelerated styles explicitly in your input script diff --git a/doc/src/dump.rst b/doc/src/dump.rst index bd57ef0353..ebf962bc0a 100644 --- a/doc/src/dump.rst +++ b/doc/src/dump.rst @@ -55,13 +55,13 @@ dump command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS dump ID group-ID style N file args * ID = user-assigned name for the dump * group-ID = ID of the group of atoms to be dumped -* style = *atom* or *atom/gz* or *atom/zstd* or *atom/mpiio* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/mpiio* or *cfg/uef* or *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *dcd* or *h5md* or *image* or *local* or *local/gz* or *local/zstd* or *molfile* or *movie* or *netcdf* or *netcdf/mpiio* or *vtk* or *xtc* or *xyz* or *xyz/gz* or *xyz/zstd* or *xyz/mpiio* or *yaml* +* style = *atom* or *atom/adios* or *atom/gz* or *atom/zstd* or *atom/mpiio* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/mpiio* or *cfg/uef* or *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *custom/adios* or *dcd* or *h5md* or *image* or *local* or *local/gz* or *local/zstd* or *molfile* or *movie* or *netcdf* or *netcdf/mpiio* or *vtk* or *xtc* or *xyz* or *xyz/gz* or *xyz/zstd* or *xyz/mpiio* or *yaml* * N = dump every this many timesteps * file = name of file to write dump info to * args = list of arguments for a particular style @@ -69,10 +69,10 @@ Syntax .. parsed-literal:: *atom* args = none + *atom/adios* args = none, discussed on :doc:`dump atom/adios ` page *atom/gz* args = none *atom/zstd* args = none *atom/mpiio* args = none - *atom/adios* args = none, discussed on :doc:`dump atom/adios ` page *cfg* args = same as *custom* args, see below *cfg/gz* args = same as *custom* args, see below *cfg/zstd* args = same as *custom* args, see below @@ -223,7 +223,7 @@ page for details. The *atom/gz*, *cfg/gz*, *custom/gz*, *local/gz*, and *xyz/gz* styles are identical in command syntax to the corresponding styles without -"gz", however, they generate compressed files using the zlib +"gz," however, they generate compressed files using the zlib library. Thus the filename suffix ".gz" is mandatory. This is an alternative approach to writing compressed files via a pipe, as done by the regular dump styles, which may be required on clusters where @@ -287,13 +287,13 @@ where xlo,xhi are the maximum extents of the simulation box in the :math:`x`-dimension, and similarly for :math:`y` and :math:`z`. The "xx yy zz" terms are six characters that encode the style of boundary for each of the six simulation box boundaries (xlo,xhi; ylo,yhi; and zlo,zhi). Each of -the six characters is either p (periodic), f (fixed), s (shrink wrap), -or m (shrink wrapped with a minimum value). See the +the six characters is one of *p* (periodic), *f* (fixed), *s* (shrink wrap), +or *m* (shrink wrapped with a minimum value). See the :doc:`boundary ` command for details. For triclinic simulation boxes (non-orthogonal), an orthogonal bounding box which encloses the triclinic simulation box is output, -along with the 3 tilt factors (*xy*, *xz*, *yz*) of the triclinic box, +along with the three tilt factors (*xy*, *xz*, *yz*) of the triclinic box, formatted as follows: .. parsed-literal:: @@ -332,8 +332,8 @@ added for each atom via dump_modify. Style *custom* allows you to specify a list of atom attributes to be written to the dump file for each atom. Possible attributes are listed above and will appear in the order specified. You cannot -specify a quantity that is not defined for a particular simulation - -such as *q* for atom style *bond*, since that atom style does not +specify a quantity that is not defined for a particular simulation---such as +*q* for atom style *bond*, since that atom style does not assign charges. Dumps occur at the very end of a timestep, so atom attributes will include effects due to fixes that are applied during the timestep. An explanation of the possible dump custom attributes @@ -566,7 +566,7 @@ files. You can use the ".bin" or ".lammpsbin" suffix described below in an MPI-IO dump file; again this file will be written in parallel and have the same binary format as if it were written without MPI-IO. -If the filename ends with ".bin" or ".lammpsbin", the dump file (or files, if +If the filename ends with ".bin" or ".lammpsbin," the dump file (or files, if "\*" or "%" is also used) is written in binary format. A binary dump file will be about the same size as a text version, but will typically write out much faster. Of course, when post-processing, you will need @@ -575,7 +575,7 @@ write your own code to read the binary file. The format of the binary file can be understood by looking at the :file:`tools/binary2txt.cpp` file. This option is only available for the *atom* and *custom* styles. -If the filename ends with ".gz", the dump file (or files, if "\*" or "%" +If the filename ends with ".gz," the dump file (or files, if "\*" or "%" is also used) is written in gzipped format. A gzipped dump file will be about :math:`3\times` smaller than the text version, but will also take longer to write. This option is not available for the *dcd* and *xtc* styles. @@ -683,10 +683,10 @@ of atom velocity and force and atomic charge. There are several options for outputting atom coordinates. The *x*, *y*, and *z* attributes write atom coordinates "unscaled," in the appropriate distance :doc:`units ` (:math:`\mathrm{\mathring A}`, -:math:`\sigma`, etc.). Use *xs*, *ys*, *zs* if you want the coordinates -"scaled" to the box size, so that each value is 0.0 to 1.0. If the simulation +:math:`\sigma`, etc.). Use *xs*, *ys*, and *zs* if you want the coordinates +"scaled" to the box size so that each value is 0.0 to 1.0. If the simulation box is triclinic (tilted), then all atom coords will still be between 0.0 and -1.0. The actual unscaled :math:`(x,y,z)` coordinate is +1.0. The actual unscaled :math:`(x,y,z)` coordinate is :math:`x_s a + y_s b + z_s c`, where :math:`(a,b,c)` are the non-orthogonal vectors of the simulation box edges, as discussed on the :doc:`Howto triclinic ` page. @@ -727,7 +727,7 @@ The *angmomx*, *angmomy*, and *angmomz* attributes are specific to finite-size aspherical particles that have an angular momentum. Only the *ellipsoid* atom style defines this quantity. -The *tqx*, *tqy*, *tqz* attributes are for finite-size particles that +The *tqx*, *tqy*, and *tqz* attributes are for finite-size particles that can sustain a rotational torque due to interactions with other particles. @@ -766,8 +766,8 @@ If *f_ID* is used as a attribute, then the per-atom vector calculated by the fix is printed. If *f_ID[i]* is used, then :math:`i` must be in the range from 1 to :math:`M`, which will print the :math:`i`\ th column of the per-atom array with :math:`M` columns calculated by the fix. See the -discussion above for how :math:`i` can be specified with a wildcard asterisk to -effectively specify multiple values. +discussion above for how :math:`i` can be specified with a wildcard asterisk +to effectively specify multiple values. The *v_name* attribute allows per-atom vectors calculated by a :doc:`variable ` to be output. The name in the attribute diff --git a/doc/src/dump_adios.rst b/doc/src/dump_adios.rst index 750d697e2c..74ade3670d 100644 --- a/doc/src/dump_adios.rst +++ b/doc/src/dump_adios.rst @@ -10,10 +10,9 @@ dump custom/adios command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS dump ID group-ID atom/adios N file.bp - dump ID group-ID custom/adios N file.bp args * ID = user-assigned name for the dump @@ -21,7 +20,7 @@ Syntax * adios = style of dump command (other styles *atom* or *cfg* or *dcd* or *xtc* or *xyz* or *local* or *custom* are discussed on the :doc:`dump ` doc page) * N = dump every this many timesteps * file.bp = name of file/stream to write to -* args = same options as in :doc:`\ *dump custom*\ ` command +* args = same options as in :doc:`dump custom ` command Examples """""""" @@ -35,10 +34,10 @@ Examples Description """"""""""" -Dump a snapshot of atom coordinates every N timesteps in the `ADIOS -`_ based "BP" file format, or using different I/O solutions in +Dump a snapshot of atom coordinates every :math:`N` timesteps in the `ADIOS +`_-based "BP" file format, or using different I/O solutions in ADIOS, to a stream that can be read on-line by another program. -ADIOS-BP files are binary, portable and self-describing. +ADIOS-BP files are binary, portable, and self-describing. .. _adios: https://github.com/ornladios/ADIOS2 @@ -67,7 +66,7 @@ create a new file at each individual dump. Restrictions """""""""""" -The number of atoms per snapshot CAN change with the adios style. +The number of atoms per snapshot **can** change with the adios style. When using the ADIOS tool 'bpls' to list the content of a .bp file, bpls will print *__* for the size of the output table indicating that its size is changing every step. diff --git a/doc/src/dump_cfg_uef.rst b/doc/src/dump_cfg_uef.rst index 7e95d8f30d..2d4424ef38 100644 --- a/doc/src/dump_cfg_uef.rst +++ b/doc/src/dump_cfg_uef.rst @@ -6,7 +6,7 @@ dump cfg/uef command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS dump ID group-ID cfg/uef N file mass type xs ys zs args @@ -32,9 +32,8 @@ Description This command is used to dump atomic coordinates in the reference frame of the applied flow field when -:doc:`fix nvt/uef ` or -:doc:`fix npt/uef ` or is used. Only the atomic -coordinates and frame-invariant scalar quantities +:doc:`fix nvt/uef ` or :doc:`fix npt/uef ` is used. +Only the atomic coordinates and frame-invariant scalar quantities will be in the flow frame. If velocities are selected as output, for example, they will not be in the same reference frame as the atomic positions. @@ -43,7 +42,8 @@ Restrictions """""""""""" This fix is part of the UEF package. It is only enabled if LAMMPS -was built with that package. See the :doc:`Build package ` page for more info. +was built with that package. See the :doc:`Build package ` +page for more info. This command can only be used when :doc:`fix nvt/uef ` or :doc:`fix npt/uef ` is active. diff --git a/doc/src/dump_image.rst b/doc/src/dump_image.rst index a243b0b839..4c5d3b6c92 100644 --- a/doc/src/dump_image.rst +++ b/doc/src/dump_image.rst @@ -12,7 +12,7 @@ dump movie command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS dump ID group-ID style N file color diameter keyword value ... @@ -28,7 +28,7 @@ Syntax .. parsed-literal:: - *atom* = yes/no = do or do not draw atoms + *atom* = *yes* or *no* = do or do not draw atoms *adiam* size = numeric value for atom diameter (distance units) *bond* values = color width = color and width of bonds color = *atom* or *type* or *none* @@ -68,21 +68,20 @@ Syntax *box* values = yes/no diam = draw outline of simulation box yes/no = do or do not draw simulation box lines diam = diameter of box lines as fraction of shortest box length - *axes* values = yes/no length diam = draw xyz axes - yes/no = do or do not draw xyz axes lines next to simulation box + *axes* values = axes length diam = draw xyz axes + axes = *yes* or *no = do or do not draw xyz axes lines next to simulation box length = length of axes lines as fraction of respective box lengths diam = diameter of axes lines as fraction of shortest box length - *subbox* values = yes/no diam = draw outline of processor sub-domains - yes/no = do or do not draw sub-domain lines + *subbox* values = lines diam = draw outline of processor sub-domains + lines = *yes* or *no* = do or do not draw sub-domain lines diam = diameter of sub-domain lines as fraction of shortest box length *shiny* value = sfactor = shinyness of spheres and cylinders sfactor = shinyness of spheres and cylinders from 0.0 to 1.0 - *ssao* value = yes/no seed dfactor = SSAO depth shading - yes/no = turn depth shading on/off + *ssao* value = shading seed dfactor = SSAO depth shading + shading = *yes* or *no* = turn depth shading on/off seed = random # seed (positive integer) dfactor = strength of shading from 0.0 to 1.0 - .. _dump_modify_image: dump_modify options for dump image/movie @@ -162,7 +161,7 @@ Examples Description """"""""""" -Dump a high-quality rendered image of the atom configuration every N +Dump a high-quality rendered image of the atom configuration every :math:`N` timesteps and save the images either as a sequence of JPEG or PNG or PPM files, or as a single movie file. The options for this command as well as the :doc:`dump_modify ` command control what is @@ -179,7 +178,7 @@ has been run, using the :doc:`rerun ` command to read snapshots from an existing dump file, and using these dump commands in the rerun script to generate the images/movie. -Here are two sample images, rendered as 1024x1024 JPEG files. +Here are two sample images, rendered as :math:`1024\times 1024` JPEG files. .. |dump1| image:: img/dump1.jpg :width: 48% @@ -197,8 +196,8 @@ Only atoms in the specified group are rendered in the image. The alter what atoms are included in the image. The filename suffix determines whether a JPEG, PNG, or PPM file is created with the *image* dump style. If the suffix is ".jpg" or -".jpeg", then a `JPEG format `_ file is created, if the -suffix is ".png", then a `PNG format `_ is created, else +".jpeg," then a `JPEG format `_ file is created, if the +suffix is ".png," then a `PNG format `_ is created, else a `PPM (aka NETPBM) format `_ file is created. The JPEG and PNG files are binary; PPM has a text mode header followed by binary data. JPEG images have lossy compression, PNG has lossless @@ -232,22 +231,22 @@ details. ---------- -Dumps are performed on timesteps that are a multiple of N (including +Dumps are performed on timesteps that are a multiple of :math:`N` (including timestep 0) and on the last timestep of a minimization if the minimization converges. Note that this means a dump will not be performed on the initial timestep after the dump command is invoked, -if the current timestep is not a multiple of N. This behavior can be +if the current timestep is not a multiple of :math:`N`. This behavior can be changed via the :doc:`dump_modify first ` command, which can be useful if the dump command is invoked after a minimization -ended on an arbitrary timestep. N can be changed between runs by +ended on an arbitrary timestep. :math:`N` can be changed between runs by using the :doc:`dump_modify every ` command. -Dump *image* filenames must contain a wildcard character "\*", so that +Dump *image* filenames must contain a wildcard character "\*" so that one image file per snapshot is written. The "\*" character is replaced with the timestep value. For example, tmp.dump.\*.jpg becomes tmp.dump.0.jpg, tmp.dump.10000.jpg, tmp.dump.20000.jpg, etc. Note that the :doc:`dump_modify pad ` command can be used to -insure all timestep numbers are the same length (e.g. 00010), which +insure all timestep numbers are the same length (e.g., 00010), which can make it easier to convert a series of images into a movie in the correct ordering. @@ -262,7 +261,7 @@ atoms rendered in the image. They can be any atom attribute defined for the :doc:`dump custom ` command, including *type* and *element*\ . This includes per-atom quantities calculated by a :doc:`compute `, :doc:`fix `, or :doc:`variable `, -which are prefixed by "c\_", "f\_", or "v\_" respectively. Note that the +which are prefixed by "c\_," "f\_," or "v\_," respectively. Note that the *diameter* setting can be overridden with a numeric value applied to all atoms by the optional *adiam* keyword. @@ -277,7 +276,7 @@ to colors is as follows: * type 5 = aqua * type 6 = cyan -and repeats itself for types > 6. This mapping can be changed by the +and repeats itself for types :math:`> 6`. This mapping can be changed by the "dump_modify acolor" command, as described below. If *type* is specified for the *diameter* setting then the diameter of @@ -298,18 +297,18 @@ and sizes used by the `AtomEye `_ visualization package. If other atom attributes are used for the *color* or *diameter* settings, they are interpreted in the following way. -If "vx", for example, is used as the *color* setting, then the color +If "vx," for example, is used as the *color* setting, then the color of the atom will depend on the x-component of its velocity. The association of a per-atom value with a specific color is determined by -a "color map", which can be specified via the dump_modify command, as +a "color map," which can be specified via the dump_modify command, as described below. The basic idea is that the atom-attribute will be within a range of values, and every value within the range is mapped to a specific color. Depending on how the color map is defined, that mapping can take place via interpolation so that a value of -3.2 is -halfway between "red" and "blue", or discretely so that the value of +halfway between "red" and "blue," or discretely so that the value of -3.2 is "orange". -If "vx", for example, is used as the *diameter* setting, then the atom +If "vx," for example, is used as the *diameter* setting, then the atom will be rendered using the x-component of its velocity as the diameter. If the per-atom value <= 0.0, them the atom will not be drawn. Note that finite-size spherical particles, as defined by @@ -773,10 +772,11 @@ the number 5.0 would be used. But for a fractional map, the number The *delta* setting must be specified for all styles, but is only used for the sequential style; otherwise the value is ignored. It specifies the bin size to use within the range for assigning -consecutive colors to. For example, if the range is from -10.0 to -10.0 and a *delta* of 1.0 is used, then 20 colors will be assigned to -the range. The first will be from -10.0 <= color1 < -9.0, then second -from -9.0 <= color2 < -8.0, etc. +consecutive colors to. For example, if the range is from :math:`-10.0` to +:math:`10.0` and a *delta* of :math:`1.0` is used, then 20 colors will be +assigned to the range. The first will be from +:math:`-10.0 \le \text{color1} < -9.0`, then second from +:math:`-9.0 \le color2 < -8.0`, etc. The *N* setting is how many entries follow. The format of the entries depends on whether the color map style is continuous, discrete or @@ -793,13 +793,13 @@ as absolute numbers or as fractions (0.0 to 1.0) of the range, depending on the "a" or "f" in the style setting for the color map. Here is how the entries are used to determine the color of an -individual atom, given the value X of its atom attribute. X will fall -between 2 of the entry values. The color of the atom is linearly -interpolated (in each of the RGB values) between the 2 colors -associated with those entries. For example, if X = -5.0 and the 2 -surrounding entries are "red" at -10.0 and "blue" at 0.0, then the -atom's color will be halfway between "red" and "blue", which happens -to be "purple". +individual atom, given the value :math:`X` of its atom attribute. +:math:`X` will fall between 2 of the entry values. The color of the atom is +linearly interpolated (in each of the RGB values) between the 2 colors +associated with those entries. For example, if :math:`X = -5.0` and the two +surrounding entries are "red" at :math:`-10.0` and "blue" at :math:`0.0`, +then the atom's color will be halfway between "red" and "blue," which happens +to be "purple." For discrete color maps, each entry has a *lo* and *hi* value and a *color*\ . The *lo* and *hi* settings are either numbers within the @@ -864,20 +864,20 @@ The *bcolor* keyword can be used with the dump image command, with its *bond* keyword, when its color setting is *type*, to set the color that bonds of each type will be drawn in the image. -The specified *type* should be an integer from 1 to Nbondtypes = the -number of bond types. A wildcard asterisk can be used in place of or +The specified *type* should be an integer from 1 to :math:`N`, where :math:`N` +is the number of bond types. A wildcard asterisk can be used in place of or in conjunction with the *type* argument to specify a range of bond -types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N = -the number of bond types, then an asterisk with no numeric values -means all types from 1 to N. A leading asterisk means all types from -1 to n (inclusive). A trailing asterisk means all types from n to N +types. This takes the form "\*" or "\*n" or "m\*" or "m\*n." If :math:`N` +is the number of bond types, then an asterisk with no numerical values +means all types from 1 to :math:`N`. A leading asterisk means all types from +1 to n (inclusive). A trailing asterisk means all types from m to :math:`N` (inclusive). A middle asterisk means all types from m to n (inclusive). The specified *color* can be a single color which is any of the 140 pre-defined colors (see below) or a color name defined by the dump_modify color option. Or it can be two or more colors separated -by a "/" character, e.g. red/green/blue. In the former case, that +by a "/" character (e.g., red/green/blue). In the former case, that color is assigned to all the specified bond types. In the latter case, the list of colors are assigned in a round-robin fashion to each of the specified bond types. @@ -885,13 +885,13 @@ of the specified bond types. ---------- The *bdiam* keyword can be used with the dump image command, with its -*bond* keyword, when its diam setting is *type*, to set the diameter +*bond* keyword, when its *diam* setting is *type*, to set the diameter that bonds of each type will be drawn in the image. The specified *type* should be an integer from 1 to Nbondtypes. As with the *bcolor* keyword, a wildcard asterisk can be used as part of the *type* argument to specify a range of bond types. The specified *diam* is the size in whatever distance :doc:`units ` you are -using, e.g. Angstroms. +using (e.g., Angstroms). ---------- @@ -922,7 +922,7 @@ dump_modify color option. ---------- The *color* keyword allows definition of a new color name, in addition -to the 140-predefined colors (see below), and associates 3 +to the 140-predefined colors (see below), and associates three red/green/blue RGB values with that color name. The color name can then be used with any other dump_modify keyword that takes a color name as a value. The RGB values should each be floating point values @@ -959,15 +959,15 @@ PNG library. To write *movie* dumps, you must use the -DLAMMPS_FFMPEG switch when building LAMMPS and have the FFmpeg executable available on the -machine where LAMMPS is being run. Typically it's name is lowercase, -i.e. ffmpeg. +machine where LAMMPS is being run. Typically its name is lowercase +(i.e., "ffmpeg"). See the :doc:`Build settings ` page for details. Note that since FFmpeg is run as an external program via a pipe, LAMMPS has limited control over its execution and no knowledge about errors and warnings printed by it. Those warnings and error messages -will be printed to the screen only. Due to the way image data is +will be printed to the screen only. Due to the way image data are communicated to FFmpeg, it will often print the message .. parsed-literal:: @@ -976,7 +976,7 @@ communicated to FFmpeg, it will often print the message which can be safely ignored. Other warnings and errors have to be addressed according to the FFmpeg documentation. -One known issue is that certain movie file formats (e.g. MPEG level 1 +One known issue is that certain movie file formats (e.g., MPEG level 1 and 2 format streams) have video bandwidth limits that can be crossed when rendering too large of image sizes. Typical warnings look like this: @@ -987,10 +987,9 @@ this: [mpeg @ 0x98b5e0] buffer underflow st=0 bufi=281407 size=285018 [mpeg @ 0x98b5e0] buffer underflow st=0 bufi=283448 size=285018 -In this case it is recommended to either reduce the size of the image -or encode in a different format that is also supported by your copy of -FFmpeg, and which does not have this limitation (e.g. .avi, .mkv, -mp4). +In this case it is recommended either to reduce the size of the image +or to encode in a different format that is also supported by your copy of +FFmpeg and which does not have this limitation (e.g., .avi, .mkv, mp4). Related commands """""""""""""""" diff --git a/doc/src/dump_vtk.rst b/doc/src/dump_vtk.rst index 8eec479292..89437bab76 100644 --- a/doc/src/dump_vtk.rst +++ b/doc/src/dump_vtk.rst @@ -6,13 +6,13 @@ dump vtk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS dump ID group-ID vtk N file args * ID = user-assigned name for the dump * group-ID = ID of the group of atoms to be dumped -* vtk = style of dump command (other styles *atom* or *cfg* or *dcd* or *xtc* or *xyz* or *local* or *custom* are discussed on the :doc:`dump ` doc page) +* vtk = style of dump command (other styles such as *atom* or *cfg* or *dcd* or *xtc* or *xyz* or *local* or *custom* are discussed on the :doc:`dump ` doc page) * N = dump every this many timesteps * file = name of file to write dump info to * args = same as arguments for :doc:`dump_style custom ` @@ -28,17 +28,18 @@ Examples Description """"""""""" -Dump a snapshot of atom quantities to one or more files every N +Dump a snapshot of atom quantities to one or more files every :math:`N` timesteps in a format readable by the `VTK visualization toolkit `_ or other visualization tools that use it, -e.g. `ParaView `_. The timesteps on which dump +such as `ParaView `_. The time steps on which dump output is written can also be controlled by a variable; see the :doc:`dump_modify every ` command for details. This dump style is similar to :doc:`dump_style custom ` but uses -the VTK library to write data to VTK simple legacy or XML format +the VTK library to write data to VTK simple legacy or XML format, depending on the filename extension specified for the dump file. This can be either *\*.vtk* for the legacy format or *\*.vtp* and *\*.vtu*, -respectively, for XML format; see the `VTK homepage `_ for a detailed +respectively, for XML format; see the +`VTK homepage `_ for a detailed description of these formats. Since this naming convention conflicts with the way binary output is usually specified (see below), the :doc:`dump_modify binary ` command allows setting of a diff --git a/doc/src/fix_accelerate_cos.rst b/doc/src/fix_accelerate_cos.rst index 904e853ad8..0b31a88915 100644 --- a/doc/src/fix_accelerate_cos.rst +++ b/doc/src/fix_accelerate_cos.rst @@ -6,8 +6,7 @@ fix accelerate/cos command Syntax """""" - -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID accelerate value @@ -19,7 +18,6 @@ Syntax Examples """""""" - .. code-block:: LAMMPS fix 1 all accelerate/cos 0.02e-5 @@ -34,8 +32,8 @@ The acceleration is a periodic function along the z-direction: a_{x}(z) = A \cos \left(\frac{2 \pi z}{l_{z}}\right) -where :math:`A` is the acceleration amplitude, :math:`l_z` is the z-length -of the simulation box. +where :math:`A` is the acceleration amplitude, :math:`l_z` is the +:math:`z`-length of the simulation box. At steady state, the acceleration generates a velocity profile: .. math:: @@ -49,17 +47,18 @@ shear viscosity :math:`\eta` by: V = \frac{A \rho}{\eta}\left(\frac{l_{z}}{2 \pi}\right)^{2} - and it can be obtained from ensemble average of the velocity profile: .. math:: - V = \frac{\sum_i 2 m_{i} v_{i, x} \cos \left(\frac{2 \pi z_i}{l_{z}}\right)}{\sum_i m_{i}} + V = \frac{\sum\limits_i 2 m_{i} v_{i, x} \cos \left(\frac{2 \pi z_i}{l_{z}}\right)}{\sum\limits_i m_{i}}, -where :math:`m_i`, :math:`v_{i,x}` and :math:`z_i` are the mass, -x-component velocity and z coordinate of a particle. +where :math:`m_i`, :math:`v_{i,x}`, and :math:`z_i` are the mass, +:math:`x`-component velocity, and :math:`z`-coordinate of a particle, +respectively. -The velocity amplitude :math:`V` can be calculated with :doc:`compute viscosity/cos `, +The velocity amplitude :math:`V` can be calculated with +:doc:`compute viscosity/cos `, which enables viscosity calculation with periodic perturbation method, as described by :ref:`Hess`. Because the applied acceleration drives the system away from equilibration, @@ -79,15 +78,17 @@ Restart, fix_modify, output, run start/stop, minimize info No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix. -No global or per-atom quantities are stored by this fix for access by various output commands. -No parameter of this fix can be used with the start/stop keywords of the run command. +No global or per-atom quantities are stored by this fix for access by various +output commands. No parameter of this fix can be used with the start/stop +keywords of the run command. This fix is not invoked during energy minimization. Restrictions """""""""""" This command is only available when LAMMPS was built with the MISC package. -Since this fix depends on the z-coordinate of atoms, it cannot be used in 2d simulations. +Since this fix depends on the :math:`z`-coordinate of atoms, it cannot be used +in 2d simulations. Related commands """""""""""""""" @@ -96,10 +97,10 @@ Related commands Default """"""" - none +none ---------- .. _Hess2: -**(Hess)** Hess, B. The Journal of Chemical Physics 2002, 116 (1), 209-217. +**(Hess)** Hess, B. Journal of Chemical Physics 2002, 116 (1), 209--217. diff --git a/doc/src/fix_acks2_reaxff.rst b/doc/src/fix_acks2_reaxff.rst index c8804497e7..9f7cc5303d 100644 --- a/doc/src/fix_acks2_reaxff.rst +++ b/doc/src/fix_acks2_reaxff.rst @@ -9,7 +9,7 @@ Accelerator Variants: *acks2/reaxff/kk* Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID acks2/reaxff Nevery cutlo cuthi tolerance params args @@ -37,10 +37,10 @@ Examples Description """"""""""" -Perform the atom-condensed Kohn-Sham DFT to second order (ACKS2) charge +Perform the atom-condensed Kohn--Sham DFT to second order (ACKS2) charge equilibration method as described in :ref:`(Verstraelen) `. ACKS2 impedes unphysical long-range charge transfer sometimes seen with -QEq (e.g. for dissociation of molecules), at increased computational +QEq (e.g., for dissociation of molecules), at increased computational cost. It is typically used in conjunction with the ReaxFF force field model as implemented in the :doc:`pair_style reaxff ` command, but it can be used with any potential in LAMMPS, so long as it @@ -71,7 +71,8 @@ potential in eV, *gamma*, the valence orbital exponent, and *bcut*, the bond cutoff distance. Note that these 4 quantities are also in the ReaxFF potential file, except that eta is defined here as twice the eta value in the ReaxFF file. Note that unlike the rest of LAMMPS, the units -of this fix are hard-coded to be A, eV, and electronic charge. +of this fix are hard-coded to be :math:`\mathrm{\mathring{A}}`, eV, and +electronic charge. The optional *maxiter* keyword allows changing the max number of iterations in the linear solver. The default value is 200. @@ -110,7 +111,7 @@ LAMMPS was built with that package. See the :doc:`Build package This fix does not correctly handle interactions involving multiple periodic images of the same atom. Hence, it should not be used for -periodic cell dimensions less than 10 angstroms. +periodic cell dimensions less than :math:`10~\mathrm{\mathring{A}}`. This fix may be used in combination with :doc:`fix efield ` and will apply the external electric field during charge equilibration, @@ -132,7 +133,7 @@ maxiter 200 .. _O'Hearn: -**(O'Hearn)** O'Hearn, Alperen, Aktulga, SIAM J. Sci. Comput., 42(1), C1-C22 (2020). +**(O'Hearn)** O'Hearn, Alperen, Aktulga, SIAM J. Sci. Comput., 42(1), C1--C22 (2020). .. _Verstraelen: diff --git a/doc/src/fix_adapt.rst b/doc/src/fix_adapt.rst index 6007cea2d4..a782f32331 100644 --- a/doc/src/fix_adapt.rst +++ b/doc/src/fix_adapt.rst @@ -6,7 +6,7 @@ fix adapt command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID adapt N attribute args ... keyword value ... @@ -19,22 +19,22 @@ Syntax .. parsed-literal:: *pair* args = pstyle pparam I J v_name - pstyle = pair style name, e.g. lj/cut + pstyle = pair style name (e.g., lj/cut) pparam = parameter to adapt over time I,J = type pair(s) to set parameter for v_name = variable with name that calculates value of pparam *bond* args = bstyle bparam I v_name - bstyle = bond style name, e.g. harmonic + bstyle = bond style name (e.g., harmonic) bparam = parameter to adapt over time I = type bond to set parameter for v_name = variable with name that calculates value of bparam *angle* args = astyle aparam I v_name - astyle = angle style name, e.g. harmonic + astyle = angle style name (e.g., harmonic) aparam = parameter to adapt over time I = type angle to set parameter for v_name = variable with name that calculates value of aparam *kspace* arg = v_name - v_name = variable with name that calculates scale factor on K-space terms + v_name = variable with name that calculates scale factor on :math:`k`-space terms *atom* args = atomparam v_name atomparam = *charge* or *diameter* or *diameter/disc* = parameter to adapt over time v_name = variable with name that calculates value of atomparam @@ -70,22 +70,22 @@ Examples Description """"""""""" -Change or adapt one or more specific simulation attributes or settings -over time as a simulation runs. Pair potential and K-space and atom -attributes which can be varied by this fix are discussed below. Many -other fixes can also be used to time-vary simulation parameters, -e.g. the "fix deform" command will change the simulation box -size/shape and the "fix move" command will change atom positions and -velocities in a prescribed manner. Also note that many commands allow -variables as arguments for specific parameters, if described in that +Change or adapt one or more specific simulation attributes or settings over +time as a simulation runs. Pair potential and :math:`k`-space and atom +attributes which can be varied by this fix are discussed below. Many other +fixes can also be used to time-vary simulation parameters (e.g., the +:doc:`fix deform ` command will change the simulation box +size/shape and the :doc:`fix move ` command will change atom +positions and velocities in a prescribed manner). Also note that many commands +allow variables as arguments for specific parameters, if described in that manner on their doc pages. An equal-style variable can calculate a -time-dependent quantity, so this is another way to vary a simulation -parameter over time. +time-dependent quantity, so this is another way to vary a simulation parameter +over time. -If *N* is specified as 0, the specified attributes are only changed +If :math:`N` is specified as 0, the specified attributes are only changed once, before the simulation begins. This is all that is needed if the -associated variables are not time-dependent. If *N* > 0, then changes -are made every *N* steps during the simulation, presumably with a +associated variables are not time-dependent. If :math:`N > 0`, then changes +are made every :math:`N` steps during the simulation, presumably with a variable that is time-dependent. Depending on the value of the *reset* keyword, attributes changed by @@ -98,9 +98,9 @@ If the *scale* keyword is set to *no*, which is the default, then the value of the altered parameter will be whatever the variable generates. If the *scale* keyword is set to *yes*, then the value of the altered parameter will be the initial value of that parameter -multiplied by whatever the variable generates. I.e. the variable is +multiplied by whatever the variable generates (i.e., the variable is now a "scale factor" applied in (presumably) a time-varying fashion to -the parameter. +the parameter). Note that whether scale is *no* or *yes*, internally, the parameters themselves are actually altered by this fix. Make sure you use the @@ -120,9 +120,9 @@ The *pstyle* argument is the name of the pair style. If :doc:`pair_style hybrid or hybrid/overlay ` is used, *pstyle* should be a sub-style name. If there are multiple sub-styles using the same pair style, then *pstyle* should be specified -as "style:N" where N is which instance of the pair style you wish to -adapt, e.g. the first, second, etc. For example, *pstyle* could be -specified as "soft" or "lubricate" or "lj/cut:1" or "lj/cut:2". The +as "style:N", where :math:`N` is which instance of the pair style you wish to +adapt (e.g., the first or second). For example, *pstyle* could be +specified as "soft" or "lubricate" or "lj/cut:1" or "lj/cut:2." The *pparam* argument is the name of the parameter to change. This is the current list of pair styles and parameters that can be varied by this fix. See the doc pages for individual pair styles and their energy @@ -216,45 +216,46 @@ formulas for the meaning of these parameters: to this list. All it typically takes is adding an extract() method to the pair\_\*.cpp file associated with the potential. -Some parameters are global settings for the pair style, e.g. the -viscosity setting "mu" for :doc:`pair_style lubricate `. -Other parameters apply to atom type pairs within the pair style, -e.g. the prefactor "a" for :doc:`pair_style soft `. +Some parameters are global settings for the pair style (e.g., the +viscosity setting "mu" for :doc:`pair_style lubricate `). +Other parameters apply to atom type pairs within the pair style (e.g., the +prefactor :math:`a` for :doc:`pair_style soft `). Note that for many of the potentials, the parameter that can be varied is effectively a prefactor on the entire energy expression for the -potential, e.g. the lj/cut epsilon. The parameters listed as "scale" +potential (e.g., the lj/cut epsilon). The parameters listed as "scale" are exactly that, since the energy expression for the :doc:`coul/cut ` potential (for example) has no labeled prefactor in its formula. To apply an effective prefactor to some potentials, multiple parameters need to be altered. For example, the -:doc:`Buckingham potential ` needs both the A and C terms -altered together. To scale the Buckingham potential, you should thus -list the pair style twice, once for A and once for C. +:doc:`Buckingham potential ` needs both the :math:`A` and +:math:`C` terms altered together. To scale the Buckingham potential, you +should thus list the pair style twice, once for :math:`A` and once for +:math:`C`. -If a type pair parameter is specified, the *I* and *J* settings should -be specified to indicate which type pairs to apply it to. If a global -parameter is specified, the *I* and *J* settings still need to be +If a type pair parameter is specified, the :math:`I` and :math:`J` settings +should be specified to indicate which type pairs to apply it to. If a global +parameter is specified, the :math:`I` and :math:`J` settings still need to be specified, but are ignored. -Similar to the :doc:`pair_coeff command `, I and J can be -specified in one of two ways. Explicit numeric values can be used for -each, as in the first example above. I <= J is required. LAMMPS sets -the coefficients for the symmetric J,I interaction to the same values. +Similar to the :doc:`pair_coeff command `, :math:`I` and :math:`J` +can be specified in one of two ways. Explicit numeric values can be used for +each, as in the first example above. :math:`I \le J` is required. LAMMPS sets +the coefficients for the symmetric :math:`J,I` interaction to the same values. A wild-card asterisk can be used in place of or in conjunction with -the I,J arguments to set the coefficients for multiple pairs of atom -types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N = -the number of atom types, then an asterisk with no numeric values -means all types from 1 to N. A leading asterisk means all types from -1 to n (inclusive). A trailing asterisk means all types from n to N +the :math:`I,J` arguments to set the coefficients for multiple pairs of atom +types. This takes the form "\*" or "\*n" or "m\*" or "m\*n." If :math:`N` +is the number of atom types, then an asterisk with no numeric values +means all types from 1 to :math:`N`. A leading asterisk means all types from +1 to n (inclusive). A trailing asterisk means all types from m to :math:`N` (inclusive). A middle asterisk means all types from m to n -(inclusive). Note that only type pairs with I <= J are considered; if -asterisks imply type pairs where J < I, they are ignored. +(inclusive). Note that only type pairs with :math:`I \le J` are considered; if +asterisks imply type pairs where :math:`J < I`, they are ignored. -IMPROTANT NOTE: If :doc:`pair_style hybrid or hybrid/overlay +IMPORTANT NOTE: If :doc:`pair_style hybrid or hybrid/overlay ` is being used, then the *pstyle* will be a sub-style -name. You must specify I,J arguments that correspond to type pair +name. You must specify :math:`I,J` arguments that correspond to type pair values defined (via the :doc:`pair_coeff ` command) for that sub-style. @@ -289,12 +290,11 @@ given bond type is adapted. A wild-card asterisk can be used in place of or in conjunction with the bond type argument to set the coefficients for multiple bond -types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N = -the number of bond types, then an asterisk with no numeric values -means all types from 1 to N. A leading asterisk means all types from -1 to n (inclusive). A trailing asterisk means all types from n to N -(inclusive). A middle asterisk means all types from m to n -(inclusive). +types. This takes the form "\*" or "\*n" or "m\*" or "m\*n." If :math:`N` +is the number of bond types, then an asterisk with no numeric values +means all types from 1 to :math:`N`. A leading asterisk means all types from +1 to n (inclusive). A trailing asterisk means all types from m to :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 @@ -325,12 +325,11 @@ given angle type is adapted. A wild-card asterisk can be used in place of or in conjunction with the angle type argument to set the coefficients for multiple angle -types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N = -the number of angle types, then an asterisk with no numeric values -means all types from 1 to N. A leading asterisk means all types from -1 to n (inclusive). A trailing asterisk means all types from n to N -(inclusive). A middle asterisk means all types from m to n -(inclusive). +types. This takes the form "\*" or "\*n" or "m\*" or "m\*n." If :math:`N` +is the number of angle types, then an asterisk with no numeric values +means all types from 1 to :math:`N`. A leading asterisk means all types from +1 to n (inclusive). A trailing asterisk means all types from m to :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 @@ -348,7 +347,7 @@ this fix uses to reset theta0 needs to generate values in radians. ---------- The *kspace* keyword used the specified variable as a scale factor on -the energy, forces, virial calculated by whatever K-Space solver is +the energy, forces, virial calculated by whatever :math:`k`-space solver is defined by the :doc:`kspace_style ` command. If the variable has a value of 1.0, then the solver is unaltered. @@ -373,17 +372,17 @@ with equal-style variables. The new value is assigned to the corresponding attribute for all atoms in the fix group. If the atom parameter is *diameter* and per-atom density and per-atom -mass are defined for particles (e.g. :doc:`atom_style granular +mass are defined for particles (e.g., :doc:`atom_style granular `), then the mass of each particle is, by default, also changed when the diameter changes. The mass is set from the particle volume for 3d systems (density is assumed to stay constant). For 2d, the default is for LAMMPS to model particles with a radius attribute as spheres. However, if the atom parameter is *diameter/disc*, then the mass is set from the particle area (the density is assumed to be in -mass/distance^2 units). The mass of the particle may also be kept constant -if the *mass* keyword is set to *no*. This can be useful to account for -diameter changes that do not involve mass changes, e.g., thermal expansion. - +mass/distance\ :math:`^2` units). The mass of the particle may also be kept +constant if the *mass* keyword is set to *no*. This can be useful to account +for diameter changes that do not involve mass changes (e.g., thermal +expansion). For example, these commands would shrink the diameter of all granular particles in the "center" group from 1.0 to 0.1 in a linear fashion @@ -405,11 +404,11 @@ their original values at the end of the last restarted run. Note that all the parameters changed by this fix are written into a restart file in their current changed state. A new restarted -simulation does not know their original time=0 values, unless the +simulation does not know the original time=0 values, unless the input script explicitly resets the parameters (after the restart file -is read), to their original values. +is read) to the original values. -Also note, that the time-dependent variable(s) used in the restart +Also note that the time-dependent variable(s) used in the restart script should typically be written as a function of time elapsed since the original simulation began. @@ -430,8 +429,8 @@ the one used in the original script. In a restarted run, if the *reset* keyword is set to *yes*, and the run ends in this script (as opposed to just writing more restart -files, parameters will be restored to the values they were at the -beginning of the run command in the restart script. Which as +files), parameters will be restored to the values they were at the +beginning of the run command in the restart script, which as explained above, may or may not be the original values of the parameters. Again, an exception is if the *atom* keyword is being used with *reset yes* (in all the runs). In that case, the original diff --git a/doc/src/fix_adapt_fep.rst b/doc/src/fix_adapt_fep.rst index affb893117..2f8a1a9475 100644 --- a/doc/src/fix_adapt_fep.rst +++ b/doc/src/fix_adapt_fep.rst @@ -6,7 +6,7 @@ fix adapt/fep command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID adapt/fep N attribute args ... keyword value ... @@ -19,7 +19,7 @@ Syntax .. parsed-literal:: *pair* args = pstyle pparam I J v_name - pstyle = pair style name, e.g. lj/cut + pstyle = pair style name (e.g., lj/cut) pparam = parameter to adapt over time I,J = type pair(s) to set parameter for v_name = variable with name that calculates value of pparam @@ -66,12 +66,12 @@ Change or adapt one or more specific simulation attributes or settings over time as a simulation runs. This is an enhanced version of the :doc:`fix adapt ` command -with two differences, +with two differences: * It is possible to modify the charges of chosen atom types only, instead of scaling all the charges in the system. -* There is a new option *after* for better compatibility with "fix - ave/time". +* There is a new option *after* for better compatibility with + :doc:`fix ave/time `. This version is suited for free energy calculations using :doc:`compute ti ` or :doc:`compute fep `. @@ -92,8 +92,8 @@ If the *scale* keyword is set to *no*, then the value the parameter is set to will be whatever the variable generates. If the *scale* keyword is set to *yes*, then the value of the altered parameter will be the initial value of that parameter multiplied by whatever the -variable generates. I.e. the variable is now a "scale factor" applied -in (presumably) a time-varying fashion to the parameter. Internally, +variable generates (i.e., the variable is now a "scale factor" applied +in (presumably) a time-varying fashion to the parameter). Internally, the parameters themselves are actually altered; make sure you use the *reset yes* option if you want the parameters to be restored to their initial values after the run. @@ -115,7 +115,7 @@ overrides the parameters. The *pstyle* argument is the name of the pair style. If :doc:`pair_style hybrid or hybrid/overlay ` is used, *pstyle* should be a sub-style name. For example, *pstyle* could be specified as "soft" -or "lubricate". The *pparam* argument is the name of the parameter to +or "lubricate." The *pparam* argument is the name of the parameter to change. This is the current list of pair styles and parameters that can be varied by this fix. See the doc pages for individual pair styles and their energy formulas for the meaning of these parameters: @@ -188,7 +188,7 @@ styles and their energy formulas for the meaning of these parameters: Note that for many of the potentials, the parameter that can be varied is effectively a prefactor on the entire energy expression for the -potential, e.g. the lj/cut epsilon. The parameters listed as "scale" +potential (e.g., the lj/cut epsilon). The parameters listed as "scale" are exactly that, since the energy expression for the :doc:`coul/cut ` potential (for example) has no labeled prefactor in its formula. To apply an effective prefactor to some @@ -204,23 +204,23 @@ specified, but are ignored. Similar to the :doc:`pair_coeff command `, I and J can be specified in one of two ways. Explicit numeric values can be used for -each, as in the first example above. I <= J is required. LAMMPS sets +each, as in the first example above. :math:`I \le J` is required. LAMMPS sets the coefficients for the symmetric J,I interaction to the same values. A wild-card asterisk can be used in place of or in conjunction with -the I,J arguments to set the coefficients for multiple pairs of atom -types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N = the -number of atom types, then an asterisk with no numeric values means -all types from 1 to N. A leading asterisk means all types from 1 to n -(inclusive). A trailing asterisk means all types from n to N +the :math:`I,J` arguments to set the coefficients for multiple pairs of atom +types. This takes the form "\*" or "\*n" or "m\*" or "m\*n." If :math:`N` is +the number of atom types, then an asterisk with no numeric values means +all types from 1 to :math:`N`. A leading asterisk means all types from 1 to n +(inclusive). A trailing asterisk means all types from m to :math:`N` (inclusive). A middle asterisk means all types from m to n -(inclusive). Note that only type pairs with I <= J are considered; if -asterisks imply type pairs where J < I, they are ignored. +(inclusive). Note that only type pairs with :math:`I \le J` are considered; if +asterisks imply type pairs where :math:`J < I`, they are ignored. -IMPROTANT NOTE: If :doc:`pair_style hybrid or hybrid/overlay ` is being used, then the *pstyle* will -be a sub-style name. You must specify I,J arguments that correspond -to type pair values defined (via the :doc:`pair_coeff ` -command) for that sub-style. +IMPROTANT NOTE: If :doc:`pair_style hybrid or hybrid/overlay ` is +being used, then the *pstyle* will be a sub-style name. You must specify +:math:`I,J` arguments that correspond to type pair values defined (via the +:doc:`pair_coeff ` command) for that sub-style. The *v_name* argument for keyword *pair* is the name of an :doc:`equal-style variable ` which will be evaluated each time @@ -232,8 +232,7 @@ simulation box parameters and timestep and elapsed time. Thus it is easy to specify parameters that change as a function of time or span consecutive runs in a continuous fashion. For the latter, see the *start* and *stop* keywords of the :doc:`run ` command and the -*elaplong* keyword of :doc:`thermo_style custom ` for -details. +*elaplong* keyword of :doc:`thermo_style custom ` for details. For example, these commands would change the prefactor coefficient of the :doc:`pair_style soft ` potential from 10.0 to 30.0 in a @@ -247,7 +246,7 @@ linear fashion over the course of a simulation: ---------- The *kspace* keyword used the specified variable as a scale factor on -the energy, forces, virial calculated by whatever K-Space solver is +the energy, forces, virial calculated by whatever :math:`k`-space solver is defined by the :doc:`kspace_style ` command. If the variable has a value of 1.0, then the solver is unaltered. @@ -263,8 +262,8 @@ current list of atom parameters that can be varied by this fix: * charge = charge on particle * diameter = diameter of particle -The *I* argument indicates which atom types are affected. A wild-card -asterisk can be used in place of or in conjunction with the I argument +The :math:`I` argument indicates which atom types are affected. A wild-card +asterisk can be used in place of or in conjunction with the :math:`I` argument to set the coefficients for multiple atom types. The *v_name* argument of the *atom* keyword is the name of an @@ -276,9 +275,9 @@ variables. The new value is assigned to the corresponding attribute for all atoms in the fix group. If the atom parameter is *diameter* and per-atom density and per-atom -mass are defined for particles (e.g. :doc:`atom_style granular `), then the mass of each particle is also -changed when the diameter changes (density is assumed to stay -constant). +mass are defined for particles (e.g., :doc:`atom_style granular `), +then the mass of each particle is also changed when the diameter changes +(density is assumed to stay constant). For example, these commands would shrink the diameter of all granular particles in the "center" group from 1.0 to 0.1 in a linear fashion @@ -297,11 +296,14 @@ parameters on the outermost rRESPA level. Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" -No information about this fix is written to :doc:`binary restart files `. None of the :doc:`fix_modify ` options +No information about this fix is written to +:doc:`binary restart files `. +None of the :doc:`fix_modify ` options are relevant to this fix. No global or per-atom quantities are stored by this fix for access by various :doc:`output commands `. No parameter of this fix can be used with the *start/stop* keywords of -the :doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. +the :doc:`run ` command. This fix is not invoked during +:doc:`energy minimization `. Restrictions """""""""""" @@ -310,7 +312,8 @@ Restrictions Related commands """""""""""""""" -:doc:`compute fep `, :doc:`fix adapt `, :doc:`compute ti `, :doc:`pair_style \*/soft ` +:doc:`compute fep `, :doc:`fix adapt `, +:doc:`compute ti `, :doc:`pair_style \*/soft ` Default """"""" diff --git a/doc/src/fix_addforce.rst b/doc/src/fix_addforce.rst index 15f433f520..8734593b58 100644 --- a/doc/src/fix_addforce.rst +++ b/doc/src/fix_addforce.rst @@ -6,7 +6,7 @@ fix addforce command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID addforce fx fy fz keyword value ... @@ -24,7 +24,7 @@ Syntax .. parsed-literal:: *every* value = Nevery - Nevery = add force every this many timesteps + Nevery = add force every this many time steps *region* value = region-ID region-ID = ID of region atoms must be in to have added force *energy* value = v_name @@ -42,31 +42,31 @@ Examples Description """"""""""" -Add fx,fy,fz to the corresponding component of force for each atom in -the group. This command can be used to give an additional push to +Add :math:`(f_x,f_y,f_z)` to the corresponding component of the force for each +atom in the group. This command can be used to give an additional push to atoms in a simulation, such as for a simulation of Poiseuille flow in a channel. -Any of the 3 quantities defining the force components can be specified -as an equal-style or atom-style :doc:`variable `, namely *fx*, -*fy*, *fz*\ . 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 evaluated each timestep, and its value(s) used to determine -the force component. +Any of the three quantities defining the force components, namely :math:`f_x`, +:math:`f_y`, and :math:`f_z`, can be specified as an equal-style or atom-style +:doc:`variable `. 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 evaluated each time step, and its value(s) will be used to determine +the force component(s). Equal-style variables can specify formulas with various mathematical -functions, and include :doc:`thermo_style ` command -keywords for the simulation box parameters and timestep and elapsed -time. Thus it is easy to specify a time-dependent force field. +functions and include :doc:`thermo_style ` command +keywords for the simulation box parameters, time step, and elapsed time. +Thus, it is easy to specify a time-dependent force field. Atom-style variables can specify the same formulas as equal-style variables but can also include per-atom values, such as atom -coordinates. Thus it is easy to specify a spatially-dependent force +coordinates. Thus, it is easy to specify a spatially-dependent force field with optional time-dependence as well. If the *every* keyword is used, the *Nevery* setting determines how often the forces are applied. The default value is 1, for every -timestep. +time step. If the *region* keyword is used, the atom must also be in the specified geometric :doc:`region ` in order to have force added @@ -83,10 +83,14 @@ potential energy to formulate a self-consistent minimization problem (see below). The *energy* keyword is not allowed if the added force is a constant -vector F = (fx,fy,fz), with all components defined as numeric +vector :math:`\vec F = (f_x,f_y,f_z)`, with all components defined as numeric constants and not as variables. This is because LAMMPS can compute -the energy for each atom directly as E = -x dot F = -(x\*fx + y\*fy + -z\*fz), so that -Grad(E) = F. +the energy for each atom directly as + +.. math:: + E = -\vec x \cdot \vec F = -(x f_x + y f_y + z f_z), + +so that :math:`-\vec\nabla E = \vec F`. The *energy* keyword is optional if the added force is defined with one or more variables, and if you are performing dynamics via the @@ -98,16 +102,16 @@ one or more variables, and you are performing energy minimization via the "minimize" command. The keyword specifies the name of an atom-style :doc:`variable ` which is used to compute the energy of each atom as function of its position. Like variables used -for *fx*, *fy*, *fz*, the energy variable is specified as v_name, -where name is the variable name. +for :math:`f_x`, :math:`f_y`, :math:`f_z`, the energy variable is specified as +v_name, where name is the variable name. Note that when the *energy* keyword is used during an energy minimization, you must insure that the formula defined for the atom-style :doc:`variable ` is consistent with the force -variable formulas, i.e. that -Grad(E) = F. For example, if the force -were a spring-like F = kx, then the energy formula should be E = --0.5kx\^2. If you don't do this correctly, the minimization will not -converge properly. +variable formulas (i.e., that :math:`-\vec\nabla E = \vec F`). +For example, if the force were a spring-like, :math:`\vec F = -k\vec x`, then +the energy formula should be :math:`E = \frac12 kx^2`. If you do not do this +correctly, the minimization will not converge properly. ---------- @@ -128,8 +132,8 @@ the global potential energy of the system as part of this fix is :doc:`fix_modify energy no `. Note that this energy is a fictitious quantity but is needed so that the :doc:`minimize ` command can include the forces added by -this fix in a consistent manner. I.e. there is a decrease in -potential energy when atoms move in the direction of the added force. +this fix in a consistent manner (i.e., there is a decrease in +potential energy when atoms move in the direction of the added force). The :doc:`fix_modify ` *virial* option is supported by this fix to add the contribution due to the added forces on atoms to @@ -144,12 +148,12 @@ fix. This allows to set at which level of the :doc:`r-RESPA ` integrator the fix is adding its forces. Default is the outermost level. -This fix computes a global scalar and a global 3-vector of forces, +This fix computes a global scalar and a global three-vector of forces, which can be accessed by various :doc:`output commands `. The scalar is the potential energy discussed above. The vector is the total force on the group of atoms before the forces on individual atoms are changed by the fix. The scalar and vector -values calculated by this fix are "extensive". +values calculated by this fix are "extensive." No parameter of this fix can be used with the *start/stop* keywords of the :doc:`run ` command. @@ -157,7 +161,7 @@ the :doc:`run ` command. The forces due to this fix are imposed during an energy minimization, invoked by the :doc:`minimize ` command. You should not specify force components with a variable that has time-dependence for -use with a minimizer, since the minimizer increments the timestep as +use with a minimizer, since the minimizer increments the time step as the iteration count during the minimization. .. note:: diff --git a/doc/src/fix_addtorque.rst b/doc/src/fix_addtorque.rst index 73af4ae571..e90e70a8d3 100644 --- a/doc/src/fix_addtorque.rst +++ b/doc/src/fix_addtorque.rst @@ -6,7 +6,7 @@ fix addtorque command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID addtorque Tx Ty Tz @@ -30,13 +30,13 @@ Add a set of forces to each atom in the group such that: * the components of the total torque applied on the group (around its - center of mass) are Tx,Ty,Tz + center of mass) are :math:`T_x`, :math:`T_y`, and :math:`T_z` * the group would move as a rigid body in the absence of other forces. This command can be used to drive a group of atoms into rotation. -Any of the 3 quantities defining the torque components can be specified +Any of the three quantities defining the torque components can be specified as an equal-style :doc:`variable `, namely *Tx*, *Ty*, *Tz*\ . If the value is a variable, it should be specified as v_name, where name is the variable name. In this case, the variable @@ -53,7 +53,8 @@ time. Thus it is easy to specify a time-dependent torque. Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" -No information about this fix is written to :doc:`binary restart files `. +No information about this fix is written to +:doc:`binary restart files `. The :doc:`fix_modify ` *energy* option is supported by this fix to add the potential "energy" inferred by the added torques @@ -62,8 +63,8 @@ to the global potential energy of the system as part of this fix is :doc:`fix_modify energy no `. Note that this is a fictitious quantity but is needed so that the :doc:`minimize ` command can include the forces added by this fix in a -consistent manner. I.e. there is a decrease in potential energy when -atoms move in the direction of the added forces. +consistent manner (i.e., there is a decrease in potential energy when +atoms move in the direction of the added forces). The :doc:`fix_modify ` *respa* option is supported by this fix. This allows to set at which level of the :doc:`r-RESPA ` @@ -74,7 +75,7 @@ accessed by various :doc:`output commands `. The scalar is the potential energy discussed above. The vector is the total torque on the group of atoms before the forces on individual atoms are changed by the fix. The scalar and vector values calculated by this -fix are "extensive". +fix are "extensive." No parameter of this fix can be used with the *start/stop* keywords of the :doc:`run ` command. @@ -99,9 +100,9 @@ invoked by the :doc:`minimize ` command. Restrictions """""""""""" -This fix is part of the EXTRA-FIX package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package -` page for more info. +This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was +built with that package. See the :doc:`Build package ` page for +more info. Related commands """""""""""""""" diff --git a/doc/src/fix_amoeba_bitorsion.rst b/doc/src/fix_amoeba_bitorsion.rst index 74b3aced49..ebfcf7ad40 100644 --- a/doc/src/fix_amoeba_bitorsion.rst +++ b/doc/src/fix_amoeba_bitorsion.rst @@ -6,7 +6,7 @@ fix amoeba/bitorsion command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID ameoba/bitorsion filename @@ -55,8 +55,8 @@ should have a line like this in its header section: N bitorsions -where N is the number of bitorsion 5-body interactions. It should -also have a section in the body of the data file like this with N +where :math:`N` is the number of bitorsion 5-body interactions. It should +also have a section in the body of the data file like this with :math:`N` lines: .. parsed-literal:: @@ -68,7 +68,7 @@ lines: [...] N 3 314 315 317 318 330 -The first column is an index from 1 to N to enumerate the bitorsion +The first column is an index from 1 to :math:`N` to enumerate the bitorsion 5-atom tuples; it is ignored by LAMMPS. The second column is the *type* of the interaction; it is an index into the bitorsion force field file. The remaining 5 columns are the atom IDs of the atoms in @@ -124,7 +124,7 @@ setting for this fix is :doc:`fix_modify virial yes `. This fix computes a global scalar which can be accessed by various :doc:`output commands `. The scalar is the potential energy discussed above. The scalar value calculated by this fix is -"extensive". +"extensive." No parameter of this fix can be used with the *start/stop* keywords of the :doc:`run ` command. diff --git a/doc/src/fix_amoeba_pitorsion.rst b/doc/src/fix_amoeba_pitorsion.rst index 9653807143..e20324fa0d 100644 --- a/doc/src/fix_amoeba_pitorsion.rst +++ b/doc/src/fix_amoeba_pitorsion.rst @@ -6,7 +6,7 @@ fix amoeba/pitorsion command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID ameoba/pitorsion @@ -29,14 +29,16 @@ Description This command enables 6-body pitorsion interactions to be added to simulations which use the AMOEBA and HIPPO force fields. It matches how the Tinker MD code computes its pitorsion interactions for the -AMOEBA and HIPPO force fields. See the :doc:`Howto amoeba -` doc page for more information about the implementation -of AMOEBA and HIPPO in LAMMPS. +AMOEBA and HIPPO force fields. See the :doc:`Howto amoeba ` +doc page for more information about the implementation of AMOEBA and HIPPO in +LAMMPS. Pitorsion interactions add additional potential energy contributions -to 6-tuples of atoms IJKLMN which have a bond between atoms K and L, -where both K and L are additionally bonded to exactly two other atoms. -Namely K is also bonded to I and J. And L is also bonded to M and N. +to 6-tuples of atoms :math:`IJKLMN` that have a bond between atoms +:math:`K` and :math:`L`, where both :math:`K` and :math:`L` are additionally +bonded to exactly two other atoms. Namely, :math:`K` is also bonded to +:math:`I` and :math:`J`, and :math:`L` is also bonded to :math:`M` and +:math:`N`. The examples/amoeba directory has a sample input script and data file for ubiquitin, which illustrates use of the fix amoeba/pitorsion @@ -47,7 +49,7 @@ file that contains a listing of pitorsion interactions. The data file read by the :doc:`read_data ` command must contain the topology of all the pitorsion interactions, similar to the -topology data for bonds, angles, dihedrals, etc. Specifically it +topology data for bonds, angles, dihedrals, etc. Specifically, it should have two lines like these in its header section: .. parsed-literal:: @@ -55,9 +57,9 @@ should have two lines like these in its header section: M pitorsion types N pitorsions -where N is the number of pitorsion 5-body interactions and M is the -number of pitorsion types. It should also have two sections in the body -of the data file like these with M and N lines each: +where :math:`N` is the number of pitorsion 5-body interactions and :math:`M` is +the number of pitorsion types. It should also have two sections in the body +of the data file like these with :math:`M` and :math:`N` lines each: .. parsed-literal:: @@ -77,11 +79,11 @@ of the data file like these with M and N lines each: [...] N 3 314 315 317 318 330 -For PiTorsion Coeffs, the first column is an index from 1 to M to +For PiTorsion Coeffs, the first column is an index from 1 to :math:`M` to enumerate the pitorsion types. The second column is the single prefactor coefficient needed for each type. -For PiTorsions, the first column is an index from 1 to N to enumerate +For PiTorsions, the first column is an index from 1 to :math:`N` to enumerate the pitorsion 5-atom tuples; it is ignored by LAMMPS. The second column is the "type" of the interaction; it is an index into the PiTorsion Coeffs. The remaining 5 columns are the atom IDs of the @@ -90,8 +92,8 @@ atoms in the two 4-atom dihedrals that overlap to create the pitorsion Note that the *pitorsion types* and *pitorsions* and *PiTorsion Coeffs* and *PiTorsions* keywords for the header and body sections of -the data file match those specified in the :doc:`read_data -` command following the data file name. +the data file match those specified in the :doc:`read_data ` +command following the data file name. The data file should be generated by using the tools/tinker/tinker2lmp.py conversion script which creates a LAMMPS @@ -136,7 +138,7 @@ setting for this fix is :doc:`fix_modify virial yes `. This fix computes a global scalar which can be accessed by various :doc:`output commands `. The scalar is the potential energy discussed above. The scalar value calculated by this fix is -"extensive". +"extensive." No parameter of this fix can be used with the *start/stop* keywords of the :doc:`run ` command. @@ -161,8 +163,8 @@ Restrictions """""""""""" To function as expected this fix command must be issued *before* a -:doc:`read_data ` command but *after* a :doc:`read_restart -` command. +:doc:`read_data ` command but *after* a +:doc:`read_restart ` command. This fix can only be used if LAMMPS was built with the AMOEBA package. See the :doc:`Build package ` page for more info. diff --git a/doc/src/fix_append_atoms.rst b/doc/src/fix_append_atoms.rst index c175fa429f..7c52d9b431 100644 --- a/doc/src/fix_append_atoms.rst +++ b/doc/src/fix_append_atoms.rst @@ -6,7 +6,7 @@ fix append/atoms command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID append/atoms face ... keyword value ... @@ -66,7 +66,7 @@ specific basis atoms as they are created. See the defined for the unit cell of the lattice. By default, all created atoms are assigned type = 1 unless this keyword specifies differently. -The *size* keyword defines the size in z of the chunk of material to +The *size* keyword defines the size in :math:`z` of the chunk of material to be added. The *random* keyword will give the atoms random displacements around @@ -79,7 +79,8 @@ measured from zhi and is set with the *extent* argument. The *units* keyword determines the meaning of the distance units used to define a wall position, but only when a numeric constant is used. A *box* value selects standard distance units as defined by the -:doc:`units ` command, e.g. Angstroms for units = real or metal. +:doc:`units ` command (e.g., :math:`\mathrm{\mathring A}` +for units = real or metal. A *lattice* value means the distance units are in lattice spacings. The :doc:`lattice ` command must have been previously used to define the lattice spacings. @@ -89,17 +90,21 @@ define the lattice spacings. Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" -No information about this fix is written to :doc:`binary restart files `. None of the :doc:`fix_modify ` options +No information about this fix is written to +:doc:`binary restart files `. None of the +:doc:`fix_modify ` options are relevant to this fix. No global or per-atom quantities are stored by this fix for access by various :doc:`output commands `. No parameter of this fix can be used with the *start/stop* keywords of -the :doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. +the :doc:`run ` command. This fix is not invoked during +:doc:`energy minimization `. Restrictions """""""""""" This fix style is part of the SHOCK package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +LAMMPS was built with that package. See the +:doc:`Build package ` page for more info. The boundary on which atoms are added with append/atoms must be shrink/minimum. The opposite boundary may be any boundary type other diff --git a/doc/utils/sphinx-config/LAMMPSLexer.py b/doc/utils/sphinx-config/LAMMPSLexer.py index 6e611f9f74..116cdb7388 100644 --- a/doc/utils/sphinx-config/LAMMPSLexer.py +++ b/doc/utils/sphinx-config/LAMMPSLexer.py @@ -6,7 +6,7 @@ LAMMPS_COMMANDS = ("angle_coeff", "angle_style", "atom_modify", "atom_style", "clear", "comm_modify", "comm_style", "compute_modify", "create_atoms", "create_bonds", "create_box", "delete_atoms", "delete_bonds", "dielectric", "dihedral_coeff", "dihedral_style", "dimension", -"displace_atoms", "dump_modify", "dynamical_matrix", "echo", +"displace_atoms", "dump_modify", "dynamical_matrix", "echo", "elif", "else", "fix_modify", "group2ndx", "hyper", "if", "improper_coeff", "improper_style", "include", "info", "jump", "kim", "kspace_modify", "kspace_style", "label", "lattice", @@ -16,8 +16,8 @@ LAMMPS_COMMANDS = ("angle_coeff", "angle_style", "atom_modify", "atom_style", "partition", "prd", "print", "processors", "python", "quit", "read_data", "read_dump", "read_restart", "replicate", "rerun", "reset_ids", "reset_timestep", "restart", "run", "run_style", "server", "set", "shell", -"special_bonds", "suffix", "tad", "temper", "temper/grem", "temper/npt", -"thermo", "thermo_modify", "thermo_style", "then", "third_order", "timer", "timestep", +"special_bonds", "suffix", "tad", "temper", "temper/grem", "temper/npt", "then", +"thermo", "thermo_modify", "thermo_style", "third_order", "timer", "timestep", "units", "velocity", "write_coeff", "write_data", "write_restart")