From e3c0b04c39763ff7e33348766684b39edc1d695b Mon Sep 17 00:00:00 2001 From: Karl Hammond Date: Tue, 30 Aug 2022 00:09:18 -0500 Subject: [PATCH 1/7] Doc tweaks to make it easier to parse for a non-human --- doc/src/fix_adapt.rst | 20 ++++++++++---------- doc/src/fix_ave_atom.rst | 4 ++-- doc/src/fix_ave_chunk.rst | 2 +- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/doc/src/fix_adapt.rst b/doc/src/fix_adapt.rst index 625a5b01d0..6007cea2d4 100644 --- a/doc/src/fix_adapt.rst +++ b/doc/src/fix_adapt.rst @@ -36,7 +36,7 @@ Syntax *kspace* arg = v_name v_name = variable with name that calculates scale factor on K-space terms *atom* args = atomparam v_name - atomparam = parameter to adapt over time + atomparam = *charge* or *diameter* or *diameter/disc* = parameter to adapt over time v_name = variable with name that calculates value of atomparam * zero or more keyword/value pairs may be appended @@ -44,15 +44,15 @@ Syntax .. parsed-literal:: - *scale* value = *no* or *yes* - *no* = the variable value is the new setting - *yes* = the variable value multiplies the original setting - *reset* value = *no* or *yes* - *no* = values will remain altered at the end of a run - *yes* = reset altered values to their original values at the end of a run - *mass* value = *no* or *yes* - *no* = mass is not altered by changes in diameter - *yes* = mass is altered by changes in diameter + *scale* value = *no* or *yes* + *no* = the variable value is the new setting + *yes* = the variable value multiplies the original setting + *reset* value = *no* or *yes* + *no* = values will remain altered at the end of a run + *yes* = reset altered values to their original values at the end of a run + *mass* value = *no* or *yes* + *no* = mass is not altered by changes in diameter + *yes* = mass is altered by changes in diameter Examples """""""" diff --git a/doc/src/fix_ave_atom.rst b/doc/src/fix_ave_atom.rst index 7719dfa7e1..63952a291f 100644 --- a/doc/src/fix_ave_atom.rst +++ b/doc/src/fix_ave_atom.rst @@ -15,8 +15,8 @@ Syntax * Nevery = use input values every this many timesteps * Nrepeat = # of times to use input values for calculating averages * Nfreq = calculate averages every this many timesteps - one or more input values can be listed -* value = x, y, z, vx, vy, vz, fx, fy, fz, c_ID, c_ID[i], f_ID, f_ID[i], v_name +* one or more input values can be listed +* value = *x*, *y*, *z*, *vx*, *vy*, *vz*, *fx*, *fy*, *fz*, c_ID, c_ID[i], f_ID, f_ID[i], v_name .. parsed-literal:: diff --git a/doc/src/fix_ave_chunk.rst b/doc/src/fix_ave_chunk.rst index 8165083a83..bd25ea6649 100644 --- a/doc/src/fix_ave_chunk.rst +++ b/doc/src/fix_ave_chunk.rst @@ -17,7 +17,7 @@ Syntax * Nfreq = calculate averages every this many timesteps * chunkID = ID of :doc:`compute chunk/atom ` command * one or more input values can be listed -* value = vx, vy, vz, fx, fy, fz, density/mass, density/number, mass, temp, c_ID, c_ID[I], f_ID, f_ID[I], v_name +* value = *vx*, *vy*, *vz*, *fx*, *fy*, *fz*, *density/mass*, *density/number*, *mass*, *temp*, c_ID, c_ID[I], f_ID, f_ID[I], v_name .. parsed-literal:: From c03ef56965d7a91c7cf4867bd9bc98979fd5695d Mon Sep 17 00:00:00 2001 From: Karl Hammond Date: Thu, 1 Sep 2022 01:01:46 -0500 Subject: [PATCH 2/7] Math replacements and cosmetic edits to documentation --- doc/src/accel_styles.rst | 2 +- doc/src/dump.rst | 34 +++--- doc/src/dump_adios.rst | 13 ++- doc/src/dump_cfg_uef.rst | 10 +- doc/src/dump_image.rst | 105 +++++++++---------- doc/src/dump_vtk.rst | 13 +-- doc/src/fix_accelerate_cos.rst | 31 +++--- doc/src/fix_acks2_reaxff.rst | 13 +-- doc/src/fix_adapt.rst | 139 ++++++++++++------------- doc/src/fix_adapt_fep.rst | 67 ++++++------ doc/src/fix_addforce.rst | 62 +++++------ doc/src/fix_addtorque.rst | 21 ++-- doc/src/fix_amoeba_bitorsion.rst | 10 +- doc/src/fix_amoeba_pitorsion.rst | 38 +++---- doc/src/fix_append_atoms.rst | 17 +-- doc/utils/sphinx-config/LAMMPSLexer.py | 6 +- 16 files changed, 298 insertions(+), 283 deletions(-) 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") From af168d5f8042e3a4cdcff89c577101bd0ff584ba Mon Sep 17 00:00:00 2001 From: Karl Hammond Date: Thu, 1 Sep 2022 16:15:18 -0500 Subject: [PATCH 3/7] Math and other minor edits to some fix style doc pages --- doc/src/fix_atc.rst | 20 ++--- doc/src/fix_atom_swap.rst | 19 +++-- doc/src/fix_ave_atom.rst | 99 ++++++++++++++----------- doc/src/fix_ave_chunk.rst | 152 +++++++++++++++++++------------------- 4 files changed, 151 insertions(+), 139 deletions(-) diff --git a/doc/src/fix_atc.rst b/doc/src/fix_atc.rst index 6095f4fa87..0aa91dbc6f 100644 --- a/doc/src/fix_atc.rst +++ b/doc/src/fix_atc.rst @@ -6,7 +6,7 @@ fix atc command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix atc @@ -40,8 +40,8 @@ This fix is the beginning to creating a coupled FE/MD simulation and/or an on-the-fly estimation of continuum fields. The coupled versions of this fix do Verlet integration and the post-processing does not. After instantiating this fix, several other fix_modify commands will be -needed to set up the problem, e.g. define the finite element mesh and -prescribe initial and boundary conditions. +needed to set up the problem (i.e., define the finite element mesh and +prescribe initial and boundary conditions). .. image:: JPG/atc_nanotube.jpg :align: center @@ -135,7 +135,7 @@ fix are listed below. This fix computes a global scalar which can be accessed by various :doc:`output commands `. The scalar is the energy -discussed in the previous paragraph. The scalar value is "extensive". +discussed in the previous paragraph. The scalar value is "extensive." No parameter of this fix can be used with the *start/stop* keywords of the :doc:`run ` command. This fix is not @@ -147,7 +147,7 @@ Restrictions Thermal and two_temperature (coupling) types use a Verlet time-integration algorithm. The hardy type does not contain its own time-integrator and must be used with a separate fix that does contain -one, e.g. nve, nvt, etc. In addition, currently: +one (e.g., nve, nvt). In addition, currently: * the coupling is restricted to thermal physics * the FE computations are done in serial on each processor. @@ -159,8 +159,8 @@ Related commands After specifying this fix in your input script, several :doc:`fix_modify AtC ` commands are used to setup the -problem, e.g. define the finite element mesh and prescribe initial and -boundary conditions. Each of these options has its own doc page. +problem (e.g., define the finite element mesh and prescribe initial and +boundary conditions). Each of these options has its own doc page. *fix_modify* commands for setup: @@ -311,6 +311,6 @@ and Computation (2011), 7:1736. as a field variable from molecular dynamics simulations." Journal of Chemical Physics (2013), 139:054115. -Please refer to the standard finite element (FE) texts, e.g. T.J.R -Hughes " The finite element method ", Dover 2003, for the basics of FE -simulation. +Please refer to the standard finite element (FE) texts (e.g., T.J.R. +Hughes, *The Finite Element Method,* Dover 2003) for the basics of FE +simulations. diff --git a/doc/src/fix_atom_swap.rst b/doc/src/fix_atom_swap.rst index 8a81e32818..5948f675c2 100644 --- a/doc/src/fix_atom_swap.rst +++ b/doc/src/fix_atom_swap.rst @@ -6,7 +6,7 @@ fix atom/swap command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID atom/swap N X seed T keyword values ... @@ -48,7 +48,7 @@ This fix performs Monte Carlo swaps of atoms of one given atom type with atoms of the other given atom types. The specified T is used in the Metropolis criterion dictating swap probabilities. -Perform X swaps of atoms of one type with atoms of another type +Perform :math:`X` swaps of atoms of one type with atoms of another type according to a Monte Carlo probability. Swap candidates must be in the fix group, must be in the region (if specified), and must be of one of the listed types. Swaps are attempted between candidates that are @@ -57,7 +57,7 @@ atoms. Swaps are not attempted between atoms of the same type since nothing would happen. All atoms in the simulation domain can be moved using regular time -integration displacements, e.g. via :doc:`fix nvt `, resulting +integration displacements (e.g., via :doc:`fix nvt `), resulting in a hybrid MC+MD simulation. A smaller-than-usual timestep size may be needed when running such a hybrid simulation, especially if the swapped atoms are not well equilibrated. @@ -83,9 +83,8 @@ canonical ensemble, the composition of the system can change. Note that when using *semi-grand*, atoms in the fix group whose type is not listed in the *types* keyword are ineligible for attempted conversion. An attempt is made to switch the selected atom (if -eligible) to one of the other listed types with equal -probability. Acceptance of each attempt depends upon the Metropolis -criterion. +eligible) to one of the other listed types with equal probability. +Acceptance of each attempt depends upon the Metropolis criterion. The *mu* keyword allows users to specify chemical potentials. This is required and allowed only when using *semi-grand*\ . All chemical @@ -97,8 +96,8 @@ amount will have no effect on the simulation. This command may optionally use the *region* keyword to define swap volume. The specified region must have been previously defined with a -:doc:`region ` command. It must be defined with side = *in*\ -. Swap attempts occur only between atoms that are both within the +:doc:`region ` command. It must be defined with side = *in*\ . +Swap attempts occur only between atoms that are both within the specified region. Swaps are not otherwise attempted. You should ensure you do not swap atoms belonging to a molecule, or @@ -147,7 +146,7 @@ Restart, fix_modify, output, run start/stop, minimize info This fix writes the state of the fix to :doc:`binary restart files `. This includes information about the random number generator seed, the next timestep for MC exchanges, the number of -exchange attempts and successes etc. See the :doc:`read_restart +exchange attempts and successes, etc. See the :doc:`read_restart ` command for info on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues in an uninterrupted fashion. @@ -168,7 +167,7 @@ the following global cumulative quantities: * 1 = swap attempts * 2 = swap accepts -The vector values calculated by this fix are "extensive". +The vector 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. This fix is not invoked during diff --git a/doc/src/fix_ave_atom.rst b/doc/src/fix_ave_atom.rst index 63952a291f..1c483e75e1 100644 --- a/doc/src/fix_ave_atom.rst +++ b/doc/src/fix_ave_atom.rst @@ -6,7 +6,7 @@ fix ave/atom command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID ave/atom Nevery Nrepeat Nfreq value1 value2 ... @@ -41,7 +41,9 @@ Description Use one or more per-atom vectors as inputs every few timesteps, and average them atom by atom over longer timescales. The resulting -per-atom averages can be used by other :doc:`output commands ` such as the :doc:`fix ave/chunk ` or :doc:`dump custom ` commands. +per-atom averages can be used by other :doc:`output commands ` +such as the :doc:`fix ave/chunk ` or :doc:`dump custom ` +commands. The group specified with the command means only atoms within the group have their averages computed. Results are set to 0.0 for atoms not in @@ -53,7 +55,8 @@ component) or can be the result of a :doc:`compute ` or :doc:`variable `. In the latter cases, the compute, fix, or variable must produce a per-atom vector, not a global quantity or local quantity. If you wish to time-average global quantities from a -compute, fix, or variable, then see the :doc:`fix ave/time ` command. +compute, fix, or variable, then see the :doc:`fix ave/time ` +command. Each per-atom value of each input vector is averaged independently. @@ -66,18 +69,18 @@ per-atom vectors. Note that for values from a compute or fix, the bracketed index I can be specified using a wildcard asterisk with the index to effectively -specify multiple values. This takes the form "\*" or "\*n" or "n\*" or -"m\*n". If N = the size of the vector (for *mode* = scalar) or the +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 N. A leading +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 N (inclusive). A middle asterisk +asterisk means all indices from m 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. E.g. these 2 fix ave/atom commands are +had been listed one by one. For example, these two fix ave/atom commands are equivalent, since the :doc:`compute stress/atom ` -command creates a per-atom array with 6 columns: +command creates a per-atom array with six columns: .. code-block:: LAMMPS @@ -96,54 +99,58 @@ that are a multiple of *Nfreq*\ . The average is over *Nrepeat* quantities, computed in the preceding portion of the simulation every *Nevery* timesteps. *Nfreq* must be a multiple of *Nevery* and *Nevery* must be non-zero even if *Nrepeat* is 1. Also, the timesteps -contributing to the average value cannot overlap, -i.e. Nrepeat\*Nevery can not exceed Nfreq. +contributing to the average value cannot overlap; +that is, :math:`N_\text{repeat} N_\text{every}` cannot exceed +:math:`N_\text{freq}`. -For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on -timesteps 90,92,94,96,98,100 will be used to compute the final average -on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on -timestep 200, etc. +For example, if :math:`N_\text{every}=2`, :math:`N_\text{repeat}=6`, and +:math:`N_\text{freq}=100`, then values on timesteps 90, 92, 94, 96, 98, and 100 +will be used to compute the final average on time step 100. Similarly for +timesteps 190, 192, 194, 196, 198, and 200 on time step 200, etc. ---------- -The atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are -self-explanatory. Note that other atom attributes can be used as -inputs to this fix by using the :doc:`compute property/atom ` command and then specifying -an input value from that compute. +The atom attribute values (*x*, *y*, *z*, *vx*, *vy*, *vz*, *fx*, *fy*, and +*fz*) are self-explanatory. Note that other atom attributes can be used as +inputs to this fix by using the +:doc:`compute property/atom ` command and then +specifying an input value from that compute. .. note:: - The x,y,z attributes are values that are re-wrapped inside the - periodic box whenever an atom crosses a periodic boundary. Thus if - you time average an atom that spends half its time on either side of + The *x*,*y*,*z* attributes are values that are re-wrapped inside the + periodic box whenever an atom crosses a periodic boundary. Thus, if + you time-average an atom that spends half of its time on either side of the periodic box, you will get a value in the middle of the box. If this is not what you want, consider averaging unwrapped coordinates, - which can be provided by the :doc:`compute property/atom ` command via its xu,yu,zu - attributes. + which can be provided by the + :doc:`compute property/atom ` + command via its *xu*, *yu*, and *zu* attributes. If a value begins with "c\_", a compute ID must follow which has been previously defined in the input script. If no bracketed term is appended, the per-atom vector calculated by the compute is used. If a -bracketed term containing an index I is appended, the Ith column of -the per-atom array calculated by the compute is used. Users can also -write code for their own compute styles and :doc:`add them to LAMMPS `. See the discussion above for how I can +bracketed term containing an index :math:`I` is appended, the +:math:`I^\text{th}` column of the per-atom array calculated by the compute is +used. Users can also write code for their own compute styles and +:doc:`add them to LAMMPS `. See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values. -If a value begins with "f\_", a fix ID must follow which has been -previously defined in the input script. If no bracketed term is -appended, the per-atom vector calculated by the fix is used. If a -bracketed term containing an index I is appended, the Ith column of -the per-atom array calculated by the fix is used. Note that some -fixes only produce their values on certain timesteps, which must be -compatible with *Nevery*, else an error will result. Users can also -write code for their own fix styles and :doc:`add them to LAMMPS `. See the discussion above for how I can be -specified with a wildcard asterisk to effectively specify multiple -values. +If a value begins with "f\_," a fix ID must follow which has been previously +defined in the input script. If no bracketed term is appended, the per-atom +vector calculated by the fix is used. If a bracketed term containing an index +:math:`I` is appended, the :math:`I^\text{th}` column of the per-atom array +calculated by the fix is used. Note that some fixes only produce their values +on certain timesteps, which must be compatible with *Nevery*, else an error +will result. Users can also write code for their own fix styles and +:doc:`add them to LAMMPS `. See the discussion above for how I can be +specified with a wildcard asterisk to effectively specify multiple values. If a value begins with "v\_", a variable name must follow which has -been previously defined in the input script as an :doc:`atom-style variable ` Variables of style *atom* can reference -thermodynamic keywords, or invoke other computes, fixes, or variables +been previously defined in the input script as an +:doc:`atom-style variable `. Variables of style *atom* can reference +thermodynamic keywords or invoke other computes, fixes, or variables when they are evaluated, so this is a very general means of generating per-atom quantities to time average. @@ -152,9 +159,11 @@ per-atom quantities to time average. 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 -are relevant to this fix. No global scalar or vector quantities are -stored by this fix for access by various :doc:`output commands `. +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 scalar or vector quantities are stored by this fix for access by +various :doc:`output commands `. This fix produces a per-atom vector or array which can be accessed by various :doc:`output commands `. A vector is produced if @@ -164,7 +173,8 @@ per-atom values can only be accessed on timesteps that are multiples of *Nfreq* since that is when averaging is performed. 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 """""""""""" @@ -173,7 +183,8 @@ Restrictions Related commands """""""""""""""" -:doc:`compute `, :doc:`fix ave/histo `, :doc:`fix ave/chunk `, :doc:`fix ave/time `, +:doc:`compute `, :doc:`fix ave/histo `, +:doc:`fix ave/chunk `, :doc:`fix ave/time `, :doc:`variable `, Default diff --git a/doc/src/fix_ave_chunk.rst b/doc/src/fix_ave_chunk.rst index bd25ea6649..2ea3bce905 100644 --- a/doc/src/fix_ave_chunk.rst +++ b/doc/src/fix_ave_chunk.rst @@ -143,19 +143,19 @@ produce global quantities. Note that for values from a compute or fix, the bracketed index I can be specified using a wildcard asterisk with the index to effectively -specify multiple values. This takes the form "\*" or "\*n" or "n\*" or -"m\*n". If N = the size of the vector (for *mode* = scalar) or the +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 N. A leading +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 N (inclusive). A middle asterisk +asterisk means all indices from m 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. E.g. these 2 fix ave/chunk commands are +had been listed one by one. For example, these two fix ave/chunk commands are equivalent, since the :doc:`compute property/atom ` command creates, in this case, a per-atom -array with 3 columns: +array with three columns: .. code-block:: LAMMPS @@ -178,25 +178,26 @@ array with 3 columns: ---------- The *Nevery*, *Nrepeat*, and *Nfreq* arguments specify on what -timesteps the input values will be accessed and contribute to the -average. The final averaged quantities are generated on timesteps +time steps the input values will be accessed and contribute to the +average. The final averaged quantities are generated on time steps that are a multiples of *Nfreq*\ . The average is over *Nrepeat* quantities, computed in the preceding portion of the simulation every -*Nevery* timesteps. *Nfreq* must be a multiple of *Nevery* and -*Nevery* must be non-zero even if *Nrepeat* is 1. Also, the timesteps -contributing to the average value cannot overlap, i.e. Nrepeat\*Nevery -can not exceed Nfreq. +*Nevery* time steps. *Nfreq* must be a multiple of *Nevery* and +*Nevery* must be non-zero even if *Nrepeat* is 1. Also, the time steps +contributing to the average value cannot overlap (i.e., +:math:`N_\text{repeat}N_\text{every}` cannot exceed :math:`N_\text{freq}`). -For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on -timesteps 90,92,94,96,98,100 will be used to compute the final average -on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on -timestep 200, etc. If Nrepeat=1 and Nfreq = 100, then no time -averaging is done; values are simply generated on timesteps -100,200,etc. +For example, if :math:`N_\text{every}=2`, :math:`N_\text{repeat}=6`, and +:math:`N_\text{freq}=100`, then values on +time steps 90, 92, 94, 96, 98, 100 will be used to compute the final average +on time step 100. Similarly for time steps 190, 192, 194, 196, 198, 200 on +time step 200, etc. If :math:`N_\text{repeat}=1` and +:math:`N_\text{freq} = 100`, then no time averaging is done; values are simply +generated on time steps 100, 200, etc. Each input value can also be averaged over the atoms in each chunk. -The way the averaging is done across the *Nrepeat* timesteps to -produce output on the *Nfreq* timesteps, and across multiple *Nfreq* +The way the averaging is done across the *Nrepeat* time steps to +produce output on the *Nfreq* time steps, and across multiple *Nfreq* outputs, is determined by the *norm* and *ave* keyword settings, as discussed below. @@ -218,52 +219,53 @@ discussed below. window, which can affect which atoms are discarded if the simulation box size changes. If its *units* keyword is set to *reduced*, then the number of bins *Nchunk* will still be fixed, - but the size of each bin can vary at each timestep if the - simulation box size changes, e.g. for an NPT simulation. + but the size of each bin can vary at each time step if the + simulation box size changes (e.g., for an NPT simulation). ---------- -The atom attribute values (vx,vy,vz,fx,fy,fz,mass) are +The atom attribute values (*vx*, *vy*, *vz*, *fx*, *fy*, *fz*, *mass*) are self-explanatory. As noted above, any other atom attributes can be used as input values to this fix by using the :doc:`compute property/atom ` command and then specifying an input value from that compute. The *density/number* value means the number density is computed for -each chunk, i.e. number/volume. The *density/mass* value means the -mass density is computed for each chunk, i.e. total-mass/volume. The -output values are in units of 1/volume or density (mass/volume). See +each chunk (i.e., number/volume). The *density/mass* value means the +mass density is computed for each chunk (i.e., total-mass/volume). The +output values are in units of 1/volume or mass density (mass/volume). See the :doc:`units ` command page for the definition of density -for each choice of units, e.g. gram/cm\^3. If the chunks defined by +for each choice of units (e.g., g/cm\ :math:`^3`). If the chunks defined by the :doc:`compute chunk/atom ` command are spatial -bins, the volume is the bin volume. Otherwise it is the volume of the +bins, the volume is the bin volume. Otherwise, it is the volume of the entire simulation box. -The *temp* value means the temperature is computed for each chunk, by -the formula +The *temp* value means the temperature is computed for each chunk, +by the formula .. math:: \text{KE} = \frac{\text{DOF}}{2} k_B T, -where KE = total kinetic energy of the chunk of atoms (sum of -:math:`\frac{1}{2} m v^2`), DOF = the total number of degrees of freedom -for all atoms in the chunk, :math:`k_B` = Boltzmann constant, and -:math:`T` = temperature. +where KE is the total kinetic energy of the chunk of atoms (sum of +:math:`\frac{1}{2} m v^2`), DOF is the the total number of degrees of freedom +for all atoms in the chunk, :math:`k_B` is the Boltzmann constant, and +:math:`T` is the absolute temperature. -The DOF is calculated as N\*adof + cdof, where N = number of atoms in -the chunk, adof = degrees of freedom per atom, and cdof = degrees of -freedom per chunk. By default adof = 2 or 3 = dimensionality of -system, as set via the :doc:`dimension ` command, and cdof = -0.0. This gives the usual formula for temperature. +The DOF is calculated as :math:`N`\ \*adof + cdof, where :math:`N` is the +number of atoms in the chunk, adof is the number of degrees of freedom per +atom, and cdof is the number of degrees of freedom per chunk. By default, +adof = 2 or 3 = dimensionality of system, +as set via the :doc:`dimension ` command, and cdof = 0.0. +This gives the usual formula for temperature. Note that currently this temperature only includes translational degrees of freedom for each atom. No rotational degrees of freedom -are included for finite-size particles. Also no degrees of freedom +are included for finite-size particles. Also, no degrees of freedom are subtracted for any velocity bias or constraints that are applied, -such as :doc:`compute temp/partial `, or -:doc:`fix shake ` or :doc:`fix rigid `. This is -because those degrees of freedom (e.g. a constrained bond) could apply +such as :doc:`compute temp/partial `, +:doc:`fix shake `, or :doc:`fix rigid `. This is +because those degrees of freedom (e.g., a constrained bond) could apply to sets of atoms that are both included and excluded from a specific chunk, and hence the concept is somewhat ill-defined. In some cases, you can use the *adof* and *cdof* keywords to adjust the calculated @@ -279,7 +281,7 @@ Note that the per-chunk temperature calculated by this fix and the different. The compute calculates the temperature for each chunk for a single snapshot. This fix can do that but can also time average those values over many snapshots, or it can compute a temperature as -if the atoms in the chunk on different timesteps were collected +if the atoms in the chunk on different time steps were collected together as one set of atoms to calculate their temperature. The compute allows the center-of-mass velocity of each chunk to be subtracted before calculating the temperature; this fix does not. @@ -289,8 +291,8 @@ previously defined in the input script. If no bracketed integer is appended, the per-atom vector calculated by the compute is used. If a bracketed integer is appended, the Ith column of the per-atom array calculated by the compute is used. Users can also write code for -their own compute styles and :doc:`add them to LAMMPS `. See -the discussion above for how I can be specified with a wildcard +their own compute styles and :doc:`add them to LAMMPS `. +See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values. If a value begins with "f\_", a fix ID must follow which has been @@ -298,7 +300,7 @@ previously defined in the input script. If no bracketed integer is appended, the per-atom vector calculated by the fix is used. If a bracketed integer is appended, the Ith column of the per-atom array calculated by the fix is used. Note that some fixes only produce -their values on certain timesteps, which must be compatible with +their values on certain time steps, which must be compatible with *Nevery*, else an error results. Users can also write code for their own fix styles and :doc:`add them to LAMMPS `. See the discussion above for how I can be specified with a wildcard asterisk @@ -317,16 +319,16 @@ Additional optional keywords also affect the operation of this fix and its outputs. The *norm* keyword affects how averaging is done for the per-chunk -values that are output every *Nfreq* timesteps. +values that are output every *Nfreq* time steps. It the *norm* setting is *all*, which is the default, a chunk value is summed over all atoms in all *Nrepeat* samples, as is the count of atoms in the chunk. The averaged output value for the chunk on the -*Nfreq* timesteps is Total-sum / Total-count. In other words it is an +*Nfreq* time steps is Total-sum / Total-count. In other words it is an average over atoms across the entire *Nfreq* timescale. For the *density/number* and *density/mass* values, the volume (bin volume or system volume) used in the final normalization will be the volume at -the final *Nfreq* timestep. For the *temp* values, degrees of freedom +the final *Nfreq* time step. For the *temp* values, degrees of freedom and kinetic energy are summed separately across the entire *Nfreq* timescale, and the output value is calculated by dividing those two sums. @@ -334,9 +336,9 @@ sums. If the *norm* setting is *sample*, the chunk value is summed over atoms for each sample, as is the count, and an "average sample value" is computed for each sample, i.e. Sample-sum / Sample-count. The -output value for the chunk on the *Nfreq* timesteps is the average of -the *Nrepeat* "average sample values", i.e. the sum of *Nrepeat* -"average sample values" divided by *Nrepeat*\ . In other words it is an +output value for the chunk on the *Nfreq* time steps is the average of +the *Nrepeat* "average sample values" (i.e., the sum of *Nrepeat* +"average sample values" divided by *Nrepeat*\ ). In other words, it is an average of an average. For the *density/number* and *density/mass* values, the volume (bin volume or system volume) used in the per-sample normalization will be the current volume at each sampling @@ -348,8 +350,8 @@ values" are "summed sample values". A summed sample value is simply the chunk value summed over atoms in the sample, without dividing by the number of atoms in the sample. The output value for the chunk on the *Nfreq* timesteps is the average of the *Nrepeat* "summed sample -values", i.e. the sum of *Nrepeat* "summed sample values" divided by -*Nrepeat*\ . For the *density/number* and *density/mass* values, the +values" (i.e., the sum of *Nrepeat* "summed sample values" divided by +*Nrepeat*\ ). For the *density/number* and *density/mass* values, the volume (bin volume or system volume) used in the per-sample sum normalization will be the current volume at each sampling step. @@ -360,8 +362,7 @@ command or written to a file. If the *ave* setting is *one*, which is the default, then the chunk values produced on timesteps that are multiples of *Nfreq* are -independent of each other; they are output as-is without further -averaging. +independent of each other; they are output as-is without further averaging. If the *ave* setting is *running*, then the chunk values produced on timesteps that are multiples of *Nfreq* are summed and averaged in a @@ -369,48 +370,49 @@ cumulative sense before being output. Each output chunk value is thus the average of the chunk value produced on that timestep with all preceding values for the same chunk. This running average begins when the fix is defined; it can only be restarted by deleting the fix via -the :doc:`unfix ` command, or re-defining the fix by -re-specifying it. +the :doc:`unfix ` command, or re-defining the fix by re-specifying it. If the *ave* setting is *window*, then the chunk values produced on timesteps that are multiples of *Nfreq* are summed and averaged within -a moving "window" of time, so that the last M values for the same -chunk are used to produce the output. E.g. if M = 3 and Nfreq = 1000, -then the output on step 10000 will be the average of the individual -chunk values on steps 8000,9000,10000. Outputs on early steps will -average over less than M values if they are not available. +a moving "window" of time, so that the last :math:`M` values for the same +chunk are used to produce the output. For example, if :math:`M = 3` and +:math:`N_\text{freq} = 1000`, then the output on step 10000 will be the average +of the individual chunk values on steps 8000,9000,10000. Outputs on early +steps will average over less than :math:`M` values if they are not available. The *bias* keyword specifies the ID of a temperature compute that -removes a "bias" velocity from each atom, specified as *bias-ID*\ . It -is only used when the *temp* value is calculated, to compute the +removes a "bias" velocity from each atom, specified as *bias-ID*\ . +It is only used when the *temp* value is calculated, to compute the thermal temperature of each chunk after the translational kinetic -energy components have been altered in a prescribed way, e.g. to -remove a flow velocity profile. See the doc pages for individual -computes that calculate a temperature to see which ones implement a -bias. +energy components have been altered in a prescribed way, (e.g., to +remove a flow velocity profile). See the doc pages for individual +computes that calculate a temperature to see which ones implement a bias. The *adof* and *cdof* keywords define the values used in the degree of freedom (DOF) formula described above for temperature calculation for each chunk. They are only used when the *temp* value is calculated. They can be used to calculate a more appropriate -temperature for some kinds of chunks. Here are 3 examples: +temperature for some kinds of chunks. Here are three examples: If spatially binned chunks contain some number of water molecules and :doc:`fix shake ` is used to make each molecule rigid, then -you could calculate a temperature with 6 degrees of freedom (DOF) (3 -translational, 3 rotational) per molecule by setting *adof* to 2.0. +you could calculate a temperature with 6 degrees of freedom (DOF) (three +translational, three rotational) per molecule by setting *adof* to 2.0. If :doc:`compute temp/partial ` is used with the -*bias* keyword to only allow the x component of velocity to contribute +*bias* keyword to only allow the :math:`x` component of velocity to contribute to the temperature, then *adof* = 1.0 would be appropriate. If each chunk consists of a large molecule, with some number of its bonds constrained by :doc:`fix shake ` or the entire molecule by :doc:`fix rigid/small `, *adof* = 0.0 and *cdof* could be set to the remaining degrees of freedom for the entire molecule -(entire chunk in this case), e.g. 6 for 3d, or 3 for 2d, for a rigid +(entire chunk in this case), that is, 6 for 3d or 3 for 2d for a rigid molecule. +.. + FIXME need to make *Nfreq* vs. :math:`N_\text{freq}` consistent. + The *file* keyword allows a filename to be specified. Every *Nfreq* timesteps, a section of chunk info will be written to a text file in the following format. A line with the timestep and number of chunks From 51f9972f83ecdc6a562129bc20dc460e4ab71ae8 Mon Sep 17 00:00:00 2001 From: Karl Hammond Date: Thu, 1 Sep 2022 22:09:03 -0500 Subject: [PATCH 4/7] Math and other edits to several fix style doc pages --- doc/src/fix_atom_swap.rst | 6 +- doc/src/fix_ave_atom.rst | 45 ++--- doc/src/fix_ave_chunk.rst | 209 +++++++++++------------ doc/src/fix_ave_correlate.rst | 307 ++++++++++++++++++---------------- 4 files changed, 295 insertions(+), 272 deletions(-) diff --git a/doc/src/fix_atom_swap.rst b/doc/src/fix_atom_swap.rst index 5948f675c2..d6779925a5 100644 --- a/doc/src/fix_atom_swap.rst +++ b/doc/src/fix_atom_swap.rst @@ -45,7 +45,7 @@ Description """"""""""" This fix performs Monte Carlo swaps of atoms of one given atom type -with atoms of the other given atom types. The specified T is used in +with atoms of the other given atom types. The specified :math:`T` is used in the Metropolis criterion dictating swap probabilities. Perform :math:`X` swaps of atoms of one type with atoms of another type @@ -122,7 +122,7 @@ Since this fix computes total potential energies before and after proposed swaps, so even complicated potential energy calculations are OK, including the following: -* long-range electrostatics (kspace) +* long-range electrostatics (:math:`k`-space) * many body pair styles * hybrid pair styles * eam pair styles @@ -136,7 +136,7 @@ include: :doc:`efield `, :doc:`gravity `, `, :doc:`temp/rescale `, and :doc:`wall fixes `. For that energy to be included in the total potential energy of the system (the quantity used when -performing GCMC moves), you MUST enable the :doc:`fix_modify +performing GCMC moves), you **must** enable the :doc:`fix_modify ` *energy* option for that fix. The doc pages for individual :doc:`fix ` commands specify if this should be done. diff --git a/doc/src/fix_ave_atom.rst b/doc/src/fix_ave_atom.rst index 1c483e75e1..711aa653e4 100644 --- a/doc/src/fix_ave_atom.rst +++ b/doc/src/fix_ave_atom.rst @@ -92,16 +92,16 @@ command creates a per-atom array with six columns: ---------- -The *Nevery*, *Nrepeat*, and *Nfreq* arguments specify on what -timesteps the input values will be used in order to contribute to the -average. The final averaged quantities are generated on timesteps -that are a multiple of *Nfreq*\ . The average is over *Nrepeat* -quantities, computed in the preceding portion of the simulation every -*Nevery* timesteps. *Nfreq* must be a multiple of *Nevery* and -*Nevery* must be non-zero even if *Nrepeat* is 1. Also, the timesteps -contributing to the average value cannot overlap; -that is, :math:`N_\text{repeat} N_\text{every}` cannot exceed -:math:`N_\text{freq}`. +The :math:`N_\text{every}`, :math:`N_\text{repeat}`, and :math:`N_\text{freq}` +arguments specify on what timesteps the input values will be used in order to +contribute to the average. The final averaged quantities are generated on +timesteps that are a multiple of :math:`N_\text{freq}`\ . The average is over +:math:`N_\text{repeat}` quantities, computed in the preceding portion of the +simulation every :math:`N_\text{every}` timesteps. :math:`N_\text{freq}` must +be a multiple of :math:`N_\text{every}` and :math:`N_\text{every}` must be +non-zero even if :math:`N_\text{repeat}` is 1. Also, the timesteps +contributing to the average value cannot overlap; that is, +:math:`N_\text{repeat} N_\text{every}` cannot exceed :math:`N_\text{freq}`. For example, if :math:`N_\text{every}=2`, :math:`N_\text{repeat}=6`, and :math:`N_\text{freq}=100`, then values on timesteps 90, 92, 94, 96, 98, and 100 @@ -118,8 +118,8 @@ specifying an input value from that compute. .. note:: - The *x*,*y*,*z* attributes are values that are re-wrapped inside the - periodic box whenever an atom crosses a periodic boundary. Thus, if + The *x*\ , *y*\ , and *z* attributes are values that are re-wrapped inside + the periodic box whenever an atom crosses a periodic boundary. Thus, if you time-average an atom that spends half of its time on either side of the periodic box, you will get a value in the middle of the box. If this is not what you want, consider averaging unwrapped coordinates, @@ -127,27 +127,28 @@ specifying an input value from that compute. :doc:`compute property/atom ` command via its *xu*, *yu*, and *zu* attributes. -If a value begins with "c\_", a compute ID must follow which has been +If a value begins with "c\_," a compute ID must follow which has been previously defined in the input script. If no bracketed term is appended, the per-atom vector calculated by the compute is used. If a bracketed term containing an index :math:`I` is appended, the :math:`I^\text{th}` column of the per-atom array calculated by the compute is used. Users can also write code for their own compute styles and -:doc:`add them to LAMMPS `. See the discussion above for how I can -be specified with a wildcard asterisk to effectively specify multiple -values. +:doc:`add them to LAMMPS `. See the discussion above for how +:math:`I` can be specified with a wildcard asterisk to effectively specify +multiple values. If a value begins with "f\_," a fix ID must follow which has been previously defined in the input script. If no bracketed term is appended, the per-atom vector calculated by the fix is used. If a bracketed term containing an index :math:`I` is appended, the :math:`I^\text{th}` column of the per-atom array calculated by the fix is used. Note that some fixes only produce their values -on certain timesteps, which must be compatible with *Nevery*, else an error -will result. Users can also write code for their own fix styles and -:doc:`add them to LAMMPS `. See the discussion above for how I can be -specified with a wildcard asterisk to effectively specify multiple values. +on certain timesteps, which must be compatible with :math:`N_\text{every}`, +else an error will result. Users can also write code for their own fix styles +and :doc:`add them to LAMMPS `. See the discussion above for how +:math:`I` can be specified with a wildcard asterisk to effectively specify +multiple values. -If a value begins with "v\_", a variable name must follow which has +If a value begins with "v\_," a variable name must follow which has been previously defined in the input script as an :doc:`atom-style variable `. Variables of style *atom* can reference thermodynamic keywords or invoke other computes, fixes, or variables @@ -170,7 +171,7 @@ various :doc:`output commands `. A vector is produced if only a single quantity is averaged by this fix. If two or more quantities are averaged, then an array of values is produced. The per-atom values can only be accessed on timesteps that are multiples -of *Nfreq* since that is when averaging is performed. +of :math:`N_\text{freq}` since that is when averaging is performed. No parameter of this fix can be used with the *start/stop* keywords of the :doc:`run ` command. This fix is not invoked during diff --git a/doc/src/fix_ave_chunk.rst b/doc/src/fix_ave_chunk.rst index 2ea3bce905..a014e587eb 100644 --- a/doc/src/fix_ave_chunk.rst +++ b/doc/src/fix_ave_chunk.rst @@ -6,7 +6,7 @@ fix ave/chunk command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID ave/chunk Nevery Nrepeat Nfreq chunkID value1 value2 ... keyword args ... @@ -165,25 +165,27 @@ array with three columns: .. note:: - This fix works by creating an array of size *Nchunk* by Nvalues - on each processor. *Nchunk* is the number of chunks which is defined - by the :doc:`compute chunk/atom ` command. - Nvalues is the number of input values specified. Each processor loops - over its atoms, tallying its values to the appropriate chunk. Then - the entire array is summed across all processors. This means that - using a large number of chunks will incur an overhead in memory and + This fix works by creating an array of size + :math:`N_\text{chunk} \times N_\text{values}` on each processor. + :math:`N_\text{chunk}` is the number of chunks, which is defined by the + :doc:`compute chunk/atom ` command. + :math:`N_\text{values}` is the number of input values specified. + Each processor loops over its atoms, tallying its values to the appropriate + chunk. Then the entire array is summed across all processors. This means + that using a large number of chunks will incur an overhead in memory and computational cost (summing across processors), so be careful to define a reasonable number of chunks. ---------- -The *Nevery*, *Nrepeat*, and *Nfreq* arguments specify on what -time steps the input values will be accessed and contribute to the -average. The final averaged quantities are generated on time steps -that are a multiples of *Nfreq*\ . The average is over *Nrepeat* -quantities, computed in the preceding portion of the simulation every -*Nevery* time steps. *Nfreq* must be a multiple of *Nevery* and -*Nevery* must be non-zero even if *Nrepeat* is 1. Also, the time steps +The :math:`N_\text{every}`, :math:`N_\text{repeat}`, and :math:`N_\text{freq}` +arguments specify on what time steps the input values will be accessed and +contribute to the average. The final averaged quantities are generated on time +steps that are a multiples of :math:`N_\text{freq}`\ . The average is over +:math:`N_\text{repeat}` quantities, computed in the preceding portion of the +simulation every :math:`N_\text{every}` time steps. :math:`N_\text{freq}` +must be a multiple of :math:`N_\text{every}` and :math:`N_\text{every}` must be +non-zero even if :math:`N_\text{repeat} = 1`\ . Also, the time steps contributing to the average value cannot overlap (i.e., :math:`N_\text{repeat}N_\text{every}` cannot exceed :math:`N_\text{freq}`). @@ -196,30 +198,30 @@ time step 200, etc. If :math:`N_\text{repeat}=1` and generated on time steps 100, 200, etc. Each input value can also be averaged over the atoms in each chunk. -The way the averaging is done across the *Nrepeat* time steps to -produce output on the *Nfreq* time steps, and across multiple *Nfreq* -outputs, is determined by the *norm* and *ave* keyword settings, as -discussed below. +The way the averaging is done across the :math:`N_\text{repeat}` time steps to +produce output on the :math:`N_\text{freq}` time steps, and across multiple +:math:`N_\text{freq}` outputs, is determined by the *norm* and *ave* keyword +settings, as discussed below. .. note:: - To perform per-chunk averaging within a *Nfreq* time window, the - number of chunks *Nchunk* defined by the :doc:`compute chunk/atom - ` command must remain constant. If the *ave* - keyword is set to *running* or *window* then *Nchunk* must remain - constant for the duration of the simulation. This fix forces the - chunk/atom compute specified by chunkID to hold *Nchunk* constant - for the appropriate time windows, by not allowing it to - re-calculate *Nchunk*, which can also affect how it assigns chunk - IDs to atoms. This is particularly important to understand if the - chunks defined by the :doc:`compute chunk/atom + To perform per-chunk averaging within a :math:`N_\text{freq}` time window, + the number of chunks :math:`N_\text{chunk}` defined by the + :doc:`compute chunk/atom ` command must remain + constant. If the *ave* keyword is set to *running* or *window* then + :math:`N_\text{chunk}` must remain constant for the duration of the + simulation. This fix forces the chunk/atom compute specified by chunkID to + hold :math:`N_\text{chunk}` constant for the appropriate time windows, + by not allowing it to re-calculate :math:`N_\text{chunk}`, which can also + affect how it assigns chunk IDs to atoms. This is particularly important to + understand if the chunks defined by the :doc:`compute chunk/atom ` command are spatial bins. If its *units* keyword is set to *box* or *lattice*, then the number of bins - *Nchunk* and size of each bin will be fixed over the *Nfreq* time - window, which can affect which atoms are discarded if the - simulation box size changes. If its *units* keyword is set to - *reduced*, then the number of bins *Nchunk* will still be fixed, - but the size of each bin can vary at each time step if the + :math:`N_\text{chunk}` and size of each bin will be fixed over the + :math:`N_\text{freq}` time window, which can affect which atoms are + discarded if the simulation box size changes. If its *units* keyword is set + to *reduced*, then the number of bins :math:`N_\text{chunk}` will still be + fixed, but the size of each bin can vary at each time step if the simulation box size changes (e.g., for an NPT simulation). ---------- @@ -286,7 +288,7 @@ together as one set of atoms to calculate their temperature. The compute allows the center-of-mass velocity of each chunk to be subtracted before calculating the temperature; this fix does not. -If a value begins with "c\_", a compute ID must follow which has been +If a value begins with "c\_," a compute ID must follow which has been previously defined in the input script. If no bracketed integer is appended, the per-atom vector calculated by the compute is used. If a bracketed integer is appended, the Ith column of the per-atom array @@ -295,18 +297,18 @@ their own compute styles and :doc:`add them to LAMMPS `. See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values. -If a value begins with "f\_", a fix ID must follow which has been +If a value begins with "f\_," a fix ID must follow which has been previously defined in the input script. If no bracketed integer is appended, the per-atom vector calculated by the fix is used. If a bracketed integer is appended, the Ith column of the per-atom array calculated by the fix is used. Note that some fixes only produce their values on certain time steps, which must be compatible with -*Nevery*, else an error results. Users can also write code for their -own fix styles and :doc:`add them to LAMMPS `. See the +:math:`N_\text{every}`, else an error results. Users can also write code for +their own fix styles and :doc:`add them to LAMMPS `. See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values. -If a value begins with "v\_", a variable name must follow which has +If a value begins with "v\_," a variable name must follow which has been previously defined in the input script. Variables of style *atom* can reference thermodynamic keywords and various per-atom attributes, or invoke other computes, fixes, or variables when they @@ -319,72 +321,75 @@ Additional optional keywords also affect the operation of this fix and its outputs. The *norm* keyword affects how averaging is done for the per-chunk -values that are output every *Nfreq* time steps. +values that are output every :math:`N_\text{freq}` time steps. -It the *norm* setting is *all*, which is the default, a chunk value is -summed over all atoms in all *Nrepeat* samples, as is the count of +It the *norm* setting is *all*, which is the default, a chunk value is summed +over all atoms in all :math:`N_\text{repeat}` samples, as is the count of atoms in the chunk. The averaged output value for the chunk on the -*Nfreq* time steps is Total-sum / Total-count. In other words it is an -average over atoms across the entire *Nfreq* timescale. For the -*density/number* and *density/mass* values, the volume (bin volume or +:math:`N_\text{freq}` time steps is Total-sum / Total-count. In other words it +is an average over atoms across the entire :math:`N_\text{freq}` timescale. +For the *density/number* and *density/mass* values, the volume (bin volume or system volume) used in the final normalization will be the volume at -the final *Nfreq* time step. For the *temp* values, degrees of freedom -and kinetic energy are summed separately across the entire *Nfreq* -timescale, and the output value is calculated by dividing those two -sums. +the final :math:`N_\text{freq}` time step. For the *temp* values, degrees of +freedom and kinetic energy are summed separately across the entire +:math:`N_\text{freq}` timescale, and the output value is calculated by dividing +those two sums. If the *norm* setting is *sample*, the chunk value is summed over atoms for each sample, as is the count, and an "average sample value" -is computed for each sample, i.e. Sample-sum / Sample-count. The -output value for the chunk on the *Nfreq* time steps is the average of -the *Nrepeat* "average sample values" (i.e., the sum of *Nrepeat* -"average sample values" divided by *Nrepeat*\ ). In other words, it is an -average of an average. For the *density/number* and *density/mass* -values, the volume (bin volume or system volume) used in the -per-sample normalization will be the current volume at each sampling -step. +is computed for each sample (i.e., Sample-sum / Sample-count). The +output value for the chunk on the :math:`N_\text{freq}` time steps is the +average of the :math:`N_\text{repeat}` "average sample values" (i.e., the sum +of :math:`N_\text{repeat}` "average sample values" divided by +:math:`N_\text{repeat}`\ ). In other words, it is an average of an average. +For the *density/number* and *density/mass* values, the volume (bin volume or +system volume) used in the per-sample normalization will be the current volume +at each sampling step. If the *norm* setting is *none*, a similar computation as for the *sample* setting is done, except the individual "average sample -values" are "summed sample values". A summed sample value is simply +values" are "summed sample values." A summed sample value is simply the chunk value summed over atoms in the sample, without dividing by the number of atoms in the sample. The output value for the chunk on -the *Nfreq* timesteps is the average of the *Nrepeat* "summed sample -values" (i.e., the sum of *Nrepeat* "summed sample values" divided by -*Nrepeat*\ ). For the *density/number* and *density/mass* values, the +the :math:`N_\text{freq}` timesteps is the average of the +:math:`N_\text{repeat}` "summed sample values" (i.e., the sum of +:math:`N_\text{repeat}` "summed sample values" divided by +:math:`N_\text{repeat}`\ ). +For the *density/number* and *density/mass* values, the volume (bin volume or system volume) used in the per-sample sum normalization will be the current volume at each sampling step. The *ave* keyword determines how the per-chunk values produced every -*Nfreq* steps are averaged with values produced on previous steps that -were multiples of *Nfreq*, before they are accessed by another output -command or written to a file. +:math:`N_\text{freq}` steps are averaged with values produced on previous steps +that were multiples of :math:`N_\text{freq}`, before they are accessed by +another output command or written to a file. If the *ave* setting is *one*, which is the default, then the chunk -values produced on timesteps that are multiples of *Nfreq* are +values produced on timesteps that are multiples of :math:`N_\text{freq}` are independent of each other; they are output as-is without further averaging. If the *ave* setting is *running*, then the chunk values produced on -timesteps that are multiples of *Nfreq* are summed and averaged in a -cumulative sense before being output. Each output chunk value is thus +timesteps that are multiples of :math:`N_\text{freq}` are summed and averaged +in a cumulative sense before being output. Each output chunk value is thus the average of the chunk value produced on that timestep with all preceding values for the same chunk. This running average begins when the fix is defined; it can only be restarted by deleting the fix via the :doc:`unfix ` command, or re-defining the fix by re-specifying it. If the *ave* setting is *window*, then the chunk values produced on -timesteps that are multiples of *Nfreq* are summed and averaged within -a moving "window" of time, so that the last :math:`M` values for the same -chunk are used to produce the output. For example, if :math:`M = 3` and +timesteps that are multiples of :math:`N_\text{freq}` are summed and averaged +within a moving "window" of time, so that the last :math:`M` values for the +same chunk are used to produce the output. For example, if :math:`M = 3` and :math:`N_\text{freq} = 1000`, then the output on step 10000 will be the average -of the individual chunk values on steps 8000,9000,10000. Outputs on early -steps will average over less than :math:`M` values if they are not available. +of the individual chunk values on time steps 8000, 9000, and 10000. Outputs on +early steps will average over less than :math:`M` values if they are not +available. The *bias* keyword specifies the ID of a temperature compute that removes a "bias" velocity from each atom, specified as *bias-ID*\ . It is only used when the *temp* value is calculated, to compute the thermal temperature of each chunk after the translational kinetic -energy components have been altered in a prescribed way, (e.g., to +energy components have been altered in a prescribed way (e.g., to remove a flow velocity profile). See the doc pages for individual computes that calculate a temperature to see which ones implement a bias. @@ -396,7 +401,7 @@ temperature for some kinds of chunks. Here are three examples: If spatially binned chunks contain some number of water molecules and :doc:`fix shake ` is used to make each molecule rigid, then -you could calculate a temperature with 6 degrees of freedom (DOF) (three +you could calculate a temperature with six degrees of freedom (DOF) (three translational, three rotational) per molecule by setting *adof* to 2.0. If :doc:`compute temp/partial ` is used with the @@ -410,16 +415,13 @@ set to the remaining degrees of freedom for the entire molecule (entire chunk in this case), that is, 6 for 3d or 3 for 2d for a rigid molecule. -.. - FIXME need to make *Nfreq* vs. :math:`N_\text{freq}` consistent. - -The *file* keyword allows a filename to be specified. Every *Nfreq* -timesteps, a section of chunk info will be written to a text file in -the following format. A line with the timestep and number of chunks -is written. Then one line per chunk is written, containing the chunk -ID (1-Nchunk), an optional original ID value, optional coordinate -values for chunks that represent spatial bins, the number of atoms in -the chunk, and one or more calculated values. More explanation of the +The *file* keyword allows a filename to be specified. Every +:math:`N_\text{freq}` timesteps, a section of chunk info will be written to a +text file in the following format. A line with the timestep and number of +chunks is written. Then one line per chunk is written, containing the chunk +ID :math:`(1-N_\text{chunk}),` an optional original ID value, optional +coordinate values for chunks that represent spatial bins, the number of atoms +in the chunk, and one or more calculated values. More explanation of the optional values is given below. The number of values in each line corresponds to the number of values specified in the fix ave/chunk command. The number of atoms and the value(s) are summed or average @@ -432,10 +434,10 @@ output. This option can only be used with the *ave running* setting. The *format* keyword sets the numeric format of each value when it is printed to a file via the *file* keyword. Note that all values are floating point quantities. The default format is %g. You can specify -a higher precision if desired, e.g. %20.16g. +a higher precision if desired (e.g., %20.16g). The *title1* and *title2* and *title3* keywords allow specification of -the strings that will be printed as the first 3 lines of the output +the strings that will be printed as the first three lines of the output file, assuming the *file* keyword was used. LAMMPS uses default values for each of these, so they do not need to be specified. @@ -450,34 +452,33 @@ By default, these header lines are as follows: In the first line, ID and name are replaced with the fix-ID and group name. The second line describes the two values that are printed at the first of each section of output. In the third line the values are -replaced with the appropriate value names, e.g. fx or c_myCompute[2]. +replaced with the appropriate value names (e.g., *fx* or c_myCompute[2]). The words in parenthesis only appear with corresponding columns if the chunk style specified for the :doc:`compute chunk/atom ` command supports them. The OrigID column is only used if the *compress* keyword was set to *yes* for the :doc:`compute chunk/atom ` command. This means -that the original chunk IDs (e.g. molecule IDs) will have been +that the original chunk IDs (e.g., molecule IDs) will have been compressed to remove chunk IDs with no atoms assigned to them. Thus a compressed chunk ID of 3 may correspond to an original chunk ID or -molecule ID of -415. The OrigID column will list 415 for the third chunk. +molecule ID of 415. The OrigID column will list 415 for the third chunk. The CoordN columns only appear if a *binning* style was used in the :doc:`compute chunk/atom ` command. For *bin/1d*, *bin/2d*, and *bin/3d* styles the column values are the center point of the bin in the corresponding dimension. Just Coord1 is used for -*bin/1d*, Coord2 is added for *bin/2d*, Coord3 is added for *bin/3d*\ -. For *bin/sphere*, just Coord1 is used, and it is the radial +*bin/1d*, Coord2 is added for *bin/2d*, Coord3 is added for *bin/3d*\ . +For *bin/sphere*, just Coord1 is used, and it is the radial coordinate. For *bin/cylinder*, Coord1 and Coord2 are used. Coord1 is the radial coordinate (away from the cylinder axis), and coord2 is the coordinate along the cylinder axis. Note that if the value of the *units* keyword used in the :doc:`compute chunk/atom command ` is *box* or -*lattice*, the coordinate values will be in distance :doc:`units -`. If the value of the *units* keyword is *reduced*, the -coordinate values will be in unitless reduced units (0-1). This is +*lattice*, the coordinate values will be in distance :doc:`units `. +If the value of the *units* keyword is *reduced*, the +coordinate values will be in unitless reduced units (0--1). This is not true for the Coord1 value of style *bin/sphere* or *bin/cylinder* which both represent radial dimensions. Those values are always in distance :doc:`units `. @@ -493,20 +494,21 @@ relevant to this fix. This fix computes a global array of values which can be accessed by various :doc:`output commands `. The values can only be -accessed on timesteps that are multiples of *Nfreq* since that is when -averaging is performed. The global array has # of rows = the number -of chunks *Nchunk* as calculated by the specified :doc:`compute -chunk/atom ` command. The # of columns = -M+1+Nvalues, where M = 1 to 4, depending on whether the optional +accessed on timesteps that are multiples of :math:`N_\text{freq}`, since that +is when averaging is performed. The global array has # of rows = the number +of chunks :math:`N_\text{chunk}`, as calculated by the specified +:doc:`compute chunk/atom ` command. The # of columns is +:math:`M+1+N_\text{values}`, where :math:`M \in \{1,\dotsc,4\}`, +depending on whether the optional columns for OrigID and CoordN are used, as explained above. Following the optional columns, the next column contains the count of atoms in the chunk, and the remaining columns are the Nvalue quantities. When -the array is accessed with a row I that exceeds the current number of +the array is accessed with a row :math:`I` that exceeds the current number of chunks, than a 0.0 is returned by the fix instead of an error, since the number of chunks can vary as a simulation runs depending on how that value is computed by the compute chunk/atom command. -The array values calculated by this fix are treated as "intensive", +The array values calculated by this fix are treated as "intensive," since they are typically already normalized by the count of atoms in each chunk. @@ -521,7 +523,8 @@ Restrictions Related commands """""""""""""""" -:doc:`compute `, :doc:`fix ave/atom `, :doc:`fix ave/histo `, :doc:`fix ave/time `, +:doc:`compute `, :doc:`fix ave/atom `, +:doc:`fix ave/histo `, :doc:`fix ave/time `, :doc:`variable `, :doc:`fix ave/correlate ` Default diff --git a/doc/src/fix_ave_correlate.rst b/doc/src/fix_ave_correlate.rst index 6653b91d91..a5098af398 100644 --- a/doc/src/fix_ave_correlate.rst +++ b/doc/src/fix_ave_correlate.rst @@ -6,7 +6,7 @@ fix ave/correlate command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID ave/correlate Nevery Nrepeat Nfreq value1 value2 ... keyword args ... @@ -73,10 +73,12 @@ Description Use one or more global scalar values as inputs every few timesteps, calculate time correlations between them at varying time intervals, -and average the correlation data over longer timescales. The -resulting correlation values can be time integrated by -:doc:`variables ` or used by other :doc:`output commands ` such as :doc:`thermo_style custom `, and can also be written to a file. See the -:doc:`fix ave/correlate/long ` command for an +and average the correlation data over longer timescales. The resulting +correlation values can be time integrated by +:doc:`variables ` or used by other +:doc:`output commands ` such as +:doc:`thermo_style custom `, and can also be written to a file. +See the :doc:`fix ave/correlate/long ` command for an alternate method for computing correlation functions efficiently over very long time windows. @@ -89,9 +91,11 @@ Each listed value can be the result of a :doc:`compute ` or :doc:`variable `. In each case, the compute, fix, or variable must produce a global quantity, not a per-atom or local quantity. If you wish to spatial- or time-average or histogram per-atom quantities -from a compute, fix, or variable, then see the :doc:`fix ave/chunk `, :doc:`fix ave/atom `, or +from a compute, fix, or variable, then see the +:doc:`fix ave/chunk `, :doc:`fix ave/atom `, or :doc:`fix ave/histo ` commands. If you wish to convert a -per-atom quantity into a single global value, see the :doc:`compute reduce ` command. +per-atom quantity into a single global value, see the +:doc:`compute reduce ` command. The input values must be all scalars. What kinds of correlations between input values are calculated is determined by the @@ -110,16 +114,16 @@ be used, since they produce per-atom values. For input values from a compute or fix or variable , the bracketed index I can be specified using a wildcard asterisk with the index to effectively specify multiple values. This takes the form "\*" or -"\*n" or "n\*" or "m\*n". If N = the size of the vector, then an -asterisk with no numeric values means all indices from 1 to N. A +"\*n" or "m\*" or "m\*n". If :math:`N` is the size of the 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 N (inclusive). A middle -asterisk means all indices from m to n (inclusive). +trailing asterisk means all indices from m 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 elements of the -vector had been listed one by one. E.g. these 2 fix ave/correlate -commands are equivalent, since the :doc:`compute pressure -` command creates a global vector with 6 values. +vector had been listed one by one. For example, the following two fix +ave/correlate commands are equivalent, since the :doc:`compute pressure +` command creates a global vector with six values: .. code-block:: LAMMPS @@ -139,151 +143,161 @@ commands are equivalent, since the :doc:`compute pressure ---------- -The *Nevery*, *Nrepeat*, and *Nfreq* arguments specify on what -timesteps the input values will be used to calculate correlation data. -The input values are sampled every *Nevery* timesteps. The -correlation data for the preceding samples is computed on timesteps -that are a multiple of *Nfreq*\ . Consider a set of samples from some -initial time up to an output timestep. The initial time could be the -beginning of the simulation or the last output time; see the *ave* +The :math:`N_\text{every}`, :math:`N_\text{repeat}`, and :math:`N_\text{freq}` +arguments specify on what timesteps the input values will be used to calculate +correlation data. The input values are sampled every :math:`N_\text{every}` +time steps. The correlation data for the preceding samples is computed on +time steps that are a multiple of :math:`N_\text{freq}`\ . Consider a set of +samples from some initial time up to an output timestep. The initial time +could be the beginning of the simulation or the last output time; see the *ave* keyword for options. For the set of samples, the correlation value -Cij is calculated as: +:math:`C_{ij}` is calculated as: -.. parsed-literal:: +.. math:: - Cij(delta) = ave(Vi(t)\*Vj(t+delta)) + C_{ij}(\Delta t) = \left\langle V_i(t) V_j(t+\Delta t)\right\rangle, -which is the correlation value between input values Vi and Vj, -separated by time delta. Note that the second value Vj in the pair is -always the one sampled at the later time. The ave() represents an -average over every pair of samples in the set that are separated by -time delta. The maximum delta used is of size (\ *Nrepeat*\ -1)\*\ *Nevery*\ . -Thus the correlation between a pair of input values yields *Nrepeat* -correlation datums: +which is the correlation value between input values :math:`V_i` and +:math:`V_j`, separated by time :math:`\Delta t`. Note that the second value +:math:`V_j` in the pair is always the one sampled at the later time. The +average is an average over every pair of samples in the set that are separated +by time :math:`\Delta t`. The maximum :math:`\Delta t` used is of size +:math:`(N_\text{repeat} - 1) N_\text{every}`\ . +Thus the correlation between a pair of input values yields +:math:`N_\text{repeat}` correlation data: -.. parsed-literal:: +.. math:: - Cij(0), Cij(Nevery), Cij(2\*Nevery), ..., Cij((Nrepeat-1)\*Nevery) + C_{ij}(0), C_{ij}(N_\text{every}), C_{ij}(2N_\text{every}), \dotsc, + C_{ij}\bigl((N_\text{repeat}-1) N_\text{every}\bigr) -For example, if Nevery=5, Nrepeat=6, and Nfreq=100, then values on -timesteps 0,5,10,15,...,100 will be used to compute the final averages -on timestep 100. Six averages will be computed: Cij(0), Cij(5), -Cij(10), Cij(15), Cij(20), and Cij(25). Cij(10) on timestep 100 will -be the average of 19 samples, namely Vi(0)\*Vj(10), Vi(5)\*Vj(15), -Vi(10)\*V j20), Vi(15)\*Vj(25), ..., Vi(85)\*Vj(95), Vi(90)\*Vj(100). +For example, if :math:`N_\text{every}=5`, :math:`N_\text{repeat}=6`, and +:math:`N_\text{freq}=100`, then values on time steps +:math:`0, 5, 10, 15,\dotsc,100` will be used to compute the final averages +on time step 100. Six averages will be computed: :math:`C_{ij}(0)`, +:math:`C_{ij}(5)`, :math:`C_{ij}(10)`, :math:`C_{ij}(15)`, :math:`C_{ij}(20)`, +and :math:`C_{ij}(25)`. :math:`C_{ij}(10)` on time step 100 will +be the average of 19 samples, namely :math:`V_i(0) V_j(10)`, +:math:`V_i(5) V_j(15)`, :math:`V_i(10) V_j(20)`, +:math:`V_i(15) V_j(25), \dotsc,` +:math:`V_i(85) V_j(95)`, and :math:`V_i(90) V_j(100)`. -*Nfreq* must be a multiple of *Nevery*\ ; *Nevery* and *Nrepeat* must be -non-zero. Also, if the *ave* keyword is set to *one* which is the -default, then *Nfreq* >= (\ *Nrepeat*\ -1)\*\ *Nevery* is required. +:math:`N_\text{freq}` must be a multiple of :math:`N_\text{every}`; +:math:`N_\text{every}` and :math:`N_\text{repeat}` must be non-zero. +Also, if the *ave* keyword is set to *one* which is the default, then +:math:`N_\text{freq} \ge (N_\text{repeat} -1) N_\text{every}` is required. ---------- -If a value begins with "c\_", a compute ID must follow which has been +If a value begins with "c\_," a compute ID must follow which has been previously defined in the input script. If no bracketed term is appended, the global scalar calculated by the compute is used. If a -bracketed term is appended, the Ith element of the global vector -calculated by the compute is used. See the discussion above for how I -can be specified with a wildcard asterisk to effectively specify +bracketed term is appended, the :math:`I^\text{th}` element of the global +vector calculated by the compute is used. See the discussion above for how +:math:`I` can be specified with a wildcard asterisk to effectively specify multiple values. Note that there is a :doc:`compute reduce ` command -which can sum per-atom quantities into a global scalar or vector which -can thus be accessed by fix ave/correlate. Or it can be a compute -defined not in your input script, but by :doc:`thermodynamic output ` or other fixes such as :doc:`fix nvt ` +that can sum per-atom quantities into a global scalar or vector which +can then be accessed by fix ave/correlate. It can also be a compute defined +not in your input script, but by :doc:`thermodynamic output ` +or other fixes such as :doc:`fix nvt ` or :doc:`fix temp/rescale `. See the doc pages for these commands which give the IDs of these computes. Users can also write code for their own compute styles and :doc:`add them to LAMMPS `. -If a value begins with "f\_", a fix ID must follow which has been +If a value begins with "f\_," a fix ID must follow which has been previously defined in the input script. If no bracketed term is appended, the global scalar calculated by the fix is used. If a -bracketed term is appended, the Ith element of the global vector -calculated by the fix is used. See the discussion above for how I can -be specified with a wildcard asterisk to effectively specify multiple -values. +bracketed term is appended, the :math:`I^\text{th}` element of the global +vector calculated by the fix is used. See the discussion above for how +:math:`I` can be specified with a wildcard asterisk to effectively specify +multiple values. Note that some fixes only produce their values on certain timesteps, -which must be compatible with *Nevery*, else an error will result. -Users can also write code for their own fix styles and :doc:`add them to LAMMPS `. +which must be compatible with :math:`N_\text{every}`, else an error will +result. Users can also write code for their own fix styles and +:doc:`add them to LAMMPS `. -If a value begins with "v\_", a variable name must follow which has -been previously defined in the input script. Only equal-style or -vector-style variables can be referenced; the latter requires a -bracketed term to specify the Ith element of the vector calculated by -the variable. See the :doc:`variable ` command for details. -Note that variables of style *equal* or *vector* define a formula -which can reference individual atom properties or thermodynamic -keywords, or they can invoke other computes, fixes, or variables when -they are evaluated, so this is a very general means of specifying -quantities to time correlate. +If a value begins with "v\_," a variable name must follow which has been +previously defined in the input script. Only equal-style or vector-style +variables can be referenced; the latter requires a bracketed term to specify +the :math:`I^\text{th}` element of the vector calculated by the variable. +See the :doc:`variable ` command for details. Note that variables of +style *equal* or *vector* define a formula which can reference individual atom +properties or thermodynamic keywords, or they can invoke other computes, fixes, +or variables when they are evaluated, so this is a very general means of +specifying quantities to time correlate. ---------- Additional optional keywords also affect the operation of this fix. The *type* keyword determines which pairs of input values are -correlated with each other. For N input values Vi, for i = 1 to N, -let the number of pairs = Npair. Note that the second value in the -pair Vi(t)\*Vj(t+delta) is always the one sampled at the later time. +correlated with each other. For :math:`N` input values :math:`V_i`, +with :math:`i \in \{1,\dotsc,N\}`, let the number of pairs be +:math:`N_\text{pair}`. Note that the second value in the +pair, :math:`V_i(t) V_j(t+\Delta t)`, is always the one sampled at the later +time. * If *type* is set to *auto* then each input value is correlated with - itself. I.e. Cii = Vi\*Vi, for i = 1 to N, so Npair = N. -* If *type* is set - to *upper* then each input value is correlated with every succeeding - value. I.e. Cij = Vi\*Vj, for i < j, so Npair = N\*(N-1)/2. -* If *type* is set - to *lower* then each input value is correlated with every preceding - value. I.e. Cij = Vi\*Vj, for i > j, so Npair = N\*(N-1)/2. + itself (i.e., :math:`C_{ii} = V_i^2` for :math:`i \in \{1,\dotsc,N\}`, + so :math:`N_\text{pair} = N`). +* If *type* is set to *upper* then each input value is correlated with every + succeeding value (i.e., :math:`C_{ij} = V_i V_j` for :math:`i < j`, so + :math:`N_\text{pair} = N (N-1)/2`). +* If *type* is set to *lower* then each input value is correlated with every + preceding value (i.e., :math:`C_{ij} = V_i V_j` for :math:`i > j`, so + :math:`N_\text{pair} = N(N-1)/2`). * If *type* is set to *auto/upper* then each input value is correlated - with itself and every succeeding value. I.e. Cij = Vi\*Vj, for i >= j, - so Npair = N\*(N+1)/2. + with itself and every succeeding value (i.e., :math:`C_{ij} = V_i V_j` + for :math:`i \ge j`, so :math:`N_\text{pair} = N(N+1)/2`). * If *type* is set to *auto/lower* then each input value is correlated - with itself and every preceding value. I.e. Cij = Vi\*Vj, for i <= j, - so Npair = N\*(N+1)/2. + with itself and every preceding value (i.e., :math:`C_{ij} = V_i V_j` + for :math:`i \le j`, so :math:`N_\text{pair} = N(N+1)/2`). * If *type* is set to *full* then each input value is correlated with - itself and every other value. I.e. Cij = Vi\*Vj, for i,j = 1,N so - Npair = N\^2. + itself and every other value (i.e., :math:`C_{ij} = V_i V_j` for + :math:`\{i,j\} = \{1,N\}`, so :math:`N_\text{pair} = N^2`). -The *ave* keyword determines what happens to the accumulation of -correlation samples every *Nfreq* timesteps. If the *ave* setting is -*one*, then the accumulation is restarted or zeroed every *Nfreq* -timesteps. Thus the outputs on successive *Nfreq* timesteps are +The *ave* keyword determines what happens to the accumulation of correlation +samples every :math:`N_\text{freq}` timesteps. If the *ave* setting is *one*, +then the accumulation is restarted or zeroed every :math:`N_\text{freq}` +timesteps. Thus the outputs on successive :math:`N_\text{freq}` timesteps are essentially independent of each other. The exception is that the -Cij(0) = Vi(T)\*Vj(T) value at a timestep T, where T is a multiple of -*Nfreq*, contributes to the correlation output both at time T and at -time T+Nfreq. +:math:`C_{ij}(0) = V_i(t) V_j(t)` value at a time step :math:`t`, where +:math:`t` is a multiple of :math:`N_\text{freq}`, contributes to the +correlation output both at time :math:`t` and at time :math:`t+N_\text{freq}`. -If the *ave* setting is *running*, then the accumulation is never -zeroed. Thus the output of correlation data at any timestep is the -average over samples accumulated every *Nevery* steps since the fix -was defined. it can only be restarted by deleting the fix via the -:doc:`unfix ` command, or by re-defining the fix by re-specifying -it. +If the *ave* setting is *running*, then the accumulation is never zeroed. +Thus the output of correlation data at any timestep is the average over samples +accumulated every :math:`N_\text{every}` steps since the fix was defined. +It can only be restarted by deleting the fix via the :doc:`unfix ` +command, or by re-defining the fix by re-specifying it. -The *start* keyword specifies what timestep the accumulation of +The *start* keyword specifies what time step the accumulation of correlation samples will begin on. The default is step 0. Setting it to a larger value can avoid adding non-equilibrated data to the correlation averages. -The *prefactor* keyword specifies a constant which will be used as a -multiplier on the correlation data after it is averaged. It is -effectively a scale factor on Vi\*Vj, which can be used to account for -the size of the time window or other unit conversions. +The *prefactor* keyword specifies a constant which will be used as a multiplier +on the correlation data after it is averaged. It is effectively a scale factor +on :math:`V_i V_j`, which can be used to account for the size of the time +window or other unit conversions. -The *file* keyword allows a filename to be specified. Every *Nfreq* -steps, an array of correlation data is written to the file. The -number of rows is *Nrepeat*, as described above. The number of -columns is the Npair+2, also as described above. Thus the file ends -up to be a series of these array sections. +The *file* keyword allows a filename to be specified. Every +:math:`N_\text{freq}` steps, an array of correlation data is written to the +file. The number of rows is :math:`N_\text{repeat}`, as described above. +The number of columns is the :math:`N_\text{pair}+2`, also as described above. +Thus the file ends up to be a series of these array sections. The *overwrite* keyword will continuously overwrite the output file with the latest output, so that it only contains one timestep worth of output. This option can only be used with the *ave running* setting. -The *title1* and *title2* and *title3* keywords allow specification of -the strings that will be printed as the first 3 lines of the output -file, assuming the *file* keyword was used. LAMMPS uses default -values for each of these, so they do not need to be specified. +The *title1*, *title2*, and *title3* keywords allow specification of +the strings that will be printed as the first three lines of the output file, +assuming the *file* keyword was used. LAMMPS uses default values for each of +these, so they do not need to be specified. By default, these header lines are as follows: @@ -300,18 +314,19 @@ appropriate fields from the fix ave/correlate command. ---------- -Let Sij = a set of time correlation data for input values I and J, -namely the *Nrepeat* values: +Let :math:`S_{ij}` be a set of time correlation data for input values +:math:`I` and :math:`J`, namely the :math:`N_\text{repeat}` values: -.. parsed-literal:: +.. math:: - Sij = Cij(0), Cij(Nevery), Cij(2\*Nevery), ..., Cij(\*Nrepeat-1)\*Nevery) + S_{ij} = C_{ij}(0), C_{ij}(N_\text{every}), C_{ij}(2N_\text{every}), + \dotsc, C_{ijI}\bigl((N_\text{repeat}-1) N_\text{every}\bigr) -As explained below, these datums are output as one column of a global +As explained below, these data are output as one column of a global array, which is effectively the correlation matrix. The *trap* function defined for :doc:`equal-style variables ` -can be used to perform a time integration of this vector of datums, +can be used to perform a time integration of this vector of data, using a trapezoidal rule. This is useful for calculating various quantities which can be derived from time correlation data. If a normalization factor is needed for the time integration, it can be @@ -322,40 +337,43 @@ included in the variable formula or via the *prefactor* keyword. 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 -are relevant to this fix. +No information about this fix is written to +:doc:`binary restart files `. None of the +:doc:`fix_modify ` options are relevant to this fix. This fix computes a global array of values which can be accessed by various :doc:`output commands `. The values can only be -accessed on timesteps that are multiples of *Nfreq* since that is when -averaging is performed. The global array has # of rows = *Nrepeat* -and # of columns = Npair+2. The first column has the time delta (in -timesteps) between the pairs of input values used to calculate the -correlation, as described above. The second column has the number of -samples contributing to the correlation average, as described above. -The remaining Npair columns are for I,J pairs of the N input values, -as determined by the *type* keyword, as described above. +accessed on timesteps that are multiples of :math:`N_\text{freq}` since that is +when averaging is performed. The global array has # of rows +:math:`N_\text{repeat}` and # of columns :math:`N_\text{pair}+2`. The first +column has the time :math:`\Delta t` (in time steps) between the pairs of input +values used to calculate the correlation, as described above. The second +column has the number of samples contributing to the correlation average, as +described above. The remaining Npair columns are for :math:`I,J` pairs of the +:math:`N` input values, as determined by the *type* keyword, as described +above. -* For *type* = *auto*, the Npair = N columns are ordered: C11, C22, ..., - CNN. -* For *type* = *upper*, the Npair = N\*(N-1)/2 columns are ordered: C12, - C13, ..., C1N, C23, ..., C2N, C34, ..., CN-1N. -* For *type* = *lower*, the Npair = N\*(N-1)/2 columns are ordered: C21, - C31, C32, C41, C42, C43, ..., CN1, CN2, ..., CNN-1. -* For *type* = *auto/upper*, the Npair = N\*(N+1)/2 columns are ordered: - C11, C12, C13, ..., C1N, C22, C23, ..., C2N, C33, C34, ..., CN-1N, - CNN. -* For *type* = *auto/lower*, the Npair = N\*(N+1)/2 columns are ordered: - C11, C21, C22, C31, C32, C33, C41, ..., C44, CN1, CN2, ..., CNN-1, - CNN. -* For *type* = *full*, the Npair = N\^2 columns are ordered: C11, C12, - ..., C1N, C21, C22, ..., C2N, C31, ..., C3N, ..., CN1, ..., CNN-1, - CNN. +* For *type* = *auto*, the :math:`N_\text{pair} = N` columns are ordered: + :math:`C_{11}, C_{22}, \dotsc, C_{NN}` +* For *type* = *upper*, the :math:`N_\text{pair} = N(N-1)/2` columns are + ordered: :math:`C_{12}, C_{13}, \dotsc, C_{1N}, C_{23}, \dotsc, C_{2N}, + C_{34}, \dotsc, C_{N-1,N}` +* For *type* = *lower*, the :math:`N_\text{pair} = N(N-1)/2` columns are + ordered: :math:`C_{21}, C_{31}, C_{32}, C_{41}, C_{42}, C_{43I}, \dotsc, + C_{N1}, C_{N2}, \dotsc, C_{N,N-1}` +* For *type* = *auto/upper*, the :math:`N_\text{pair} = N(N+1)/2` columns are + ordered: :math:`C_{11}, C_{12}, C_{13}, \dotsc, C_{1N}, C_{22}, C_{23}, + \dotsc, C_{2N}, C_{33}, C_{34}, \dotsc, C_{N-1,N}, C_{NN}` +* For *type* = *auto/lower*, the :math:`N_\text{pair} = N(N+1)/2` columns are + ordered: :math:`C_{11}, C_{21}, C_{22}, C_{31}, C_{32}, C_{33}, C_{41}, + \dotsc, C_{44}, C_{N1}, C_{N2}, \dotsc, C_{N,N-1}, C_{NN}` +* For *type* = *full*, the :math:`N_\text{pair} = N^2` columns are ordered: + :math:`C_{11}, C_{12}, \dotsc, C_{1N}, C_{21}, C_{22}, \dotsc, C_{2N}, + C_{31}, \dotsc, C_{3N}, \dotsc, C_{N1}, \dotsc, C_{N,N-1}, C_{NN}` -The array values calculated by this fix are treated as intensive. If +The array values calculated by this fix are treated as extensive. If you need to divide them by the number of atoms, you must do this in a -later processing step, e.g. when using them in a -:doc:`variable `. +later processing step (e.g., when using them in a :doc:`variable `). 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 `. @@ -368,7 +386,8 @@ Related commands """""""""""""""" :doc:`fix ave/correlate/long `, -:doc:`compute `, :doc:`fix ave/time `, :doc:`fix ave/atom `, :doc:`fix ave/chunk `, +:doc:`compute `, :doc:`fix ave/time `, +:doc:`fix ave/atom `, :doc:`fix ave/chunk `, :doc:`fix ave/histo `, :doc:`variable ` Default From d548c02a9e7fcd9d86f5749103836dba543a61f9 Mon Sep 17 00:00:00 2001 From: Karl Hammond Date: Fri, 2 Sep 2022 17:44:45 -0500 Subject: [PATCH 5/7] Math-related edits and code-block swaps; checkd builds for pdf and html docs --- doc/src/dump_image.rst | 2 +- doc/src/fix_ave_correlate.rst | 4 +- doc/src/fix_ave_correlate_long.rst | 59 +++++---- doc/src/fix_ave_histo.rst | 189 +++++++++++++++-------------- doc/src/fix_ave_time.rst | 130 ++++++++++---------- doc/src/fix_aveforce.rst | 18 +-- doc/src/fix_balance.rst | 119 +++++++++--------- doc/src/pair_mesocnt.rst | 2 +- 8 files changed, 277 insertions(+), 246 deletions(-) diff --git a/doc/src/dump_image.rst b/doc/src/dump_image.rst index 4c5d3b6c92..257f7a87a8 100644 --- a/doc/src/dump_image.rst +++ b/doc/src/dump_image.rst @@ -775,7 +775,7 @@ specifies the bin size to use within the range for assigning 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:`-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 diff --git a/doc/src/fix_ave_correlate.rst b/doc/src/fix_ave_correlate.rst index a5098af398..82046990e0 100644 --- a/doc/src/fix_ave_correlate.rst +++ b/doc/src/fix_ave_correlate.rst @@ -264,7 +264,7 @@ samples every :math:`N_\text{freq}` timesteps. If the *ave* setting is *one*, then the accumulation is restarted or zeroed every :math:`N_\text{freq}` timesteps. Thus the outputs on successive :math:`N_\text{freq}` timesteps are essentially independent of each other. The exception is that the -:math:`C_{ij}(0) = V_i(t) V_j(t)` value at a time step :math:`t`, where +:math:`C_{ij}(0) = V_i(t) V_j(t)` value at a time step :math:`t,` where :math:`t` is a multiple of :math:`N_\text{freq}`, contributes to the correlation output both at time :math:`t` and at time :math:`t+N_\text{freq}`. @@ -287,7 +287,7 @@ window or other unit conversions. The *file* keyword allows a filename to be specified. Every :math:`N_\text{freq}` steps, an array of correlation data is written to the file. The number of rows is :math:`N_\text{repeat}`, as described above. -The number of columns is the :math:`N_\text{pair}+2`, also as described above. +The number of columns is :math:`N_\text{pair}+2`, also as described above. Thus the file ends up to be a series of these array sections. The *overwrite* keyword will continuously overwrite the output file diff --git a/doc/src/fix_ave_correlate_long.rst b/doc/src/fix_ave_correlate_long.rst index a69d8f5695..d5120b1af5 100644 --- a/doc/src/fix_ave_correlate_long.rst +++ b/doc/src/fix_ave_correlate_long.rst @@ -6,14 +6,14 @@ fix ave/correlate/long command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID ave/correlate/long Nevery Nfreq value1 value2 ... keyword args ... * ID, group-ID are documented in :doc:`fix ` command * ave/correlate/long = style name of this fix command -* Nevery = use input values every this many timesteps -* Nfreq = save state of the time correlation functions every this many timesteps +* Nevery = use input values every this many time steps +* Nfreq = save state of the time correlation functions every this many time steps * one or more input values can be listed * value = c_ID, c_ID[N], f_ID, f_ID[N], v_name @@ -38,7 +38,7 @@ Syntax auto/lower = auto + lower full = correlate each value with every other value, including itself = auto + upper + lower *start* args = Nstart - Nstart = start accumulating correlations on this timestep + Nstart = start accumulating correlations on this time step *file* arg = filename filename = name of file to output correlation data to *overwrite* arg = none = overwrite output file with only latest output @@ -66,10 +66,11 @@ Examples Description """"""""""" -This fix is similar in spirit and syntax to the :doc:`fix ave/correlate `. +This fix is similar in spirit and syntax to the +:doc:`fix ave/correlate `. However, this fix allows the efficient calculation of time correlation functions on-the-fly over extremely long time windows with little -additional CPU overhead, using a multiple-tau method +additional CPU overhead, using a multiple-:math:`\tau` method :ref:`(Ramirez) ` that decreases the resolution of the stored correlation function with time. It is not a full drop-in replacement. @@ -78,37 +79,41 @@ specified values may represent calculations performed by computes and fixes which store their own "group" definitions. Each listed value can be the result of a compute or fix or the -evaluation of an equal-style variable. See the :doc:`fix ave/correlate ` page for details. +evaluation of an equal-style variable. See the +:doc:`fix ave/correlate ` page for details. -The *Nevery* and *Nfreq* arguments specify on what timesteps the input -values will be used to calculate correlation data, and the frequency -with which the time correlation functions will be output to a file. -Note that there is no *Nrepeat* argument, unlike the :doc:`fix ave/correlate ` command. +The *Nevery* and *Nfreq* arguments specify on what time steps the input +values will be used to calculate correlation data and the frequency +with which the time correlation functions will be output to a file, +respectively. +Note that there is no *Nrepeat* argument, unlike the +:doc:`fix ave/correlate ` command. The optional keywords *ncorr*, *nlen*, and *ncount* are unique to this command and determine the number of correlation points calculated and the memory and CPU overhead used by this calculation. *Nlen* and *ncount* determine the amount of averaging done at longer correlation -times. The default values *nlen=16*, *ncount=2* ensure that the -systematic error of the multiple-tau correlator is always below the +times. The default values *nlen* = 16 and *ncount* = 2 ensure that the +systematic error of the multiple-:math:`\tau` correlator is always below the level of the statistical error of a typical simulation (which depends on the ensemble size and the simulation length). The maximum correlation time (in time steps) that can be reached is -given by the formula (nlen-1) \* ncount\^(ncorr-1). Longer correlation +given by the formula :math:`(nlen-1) ncount^{(ncorr-1)}`. Longer correlation times are discarded and not calculated. With the default values of -the parameters (ncorr=20, nlen=16 and ncount=2), this corresponds to -7864320 time steps. If longer correlation times are needed, the value -of ncorr should be increased. Using nlen=16 and ncount=2, with -ncorr=30, the maximum number of steps that can be correlated is -80530636808. If ncorr=40, correlation times in excess of 8e12 time -steps can be calculated. +the parameters (:math:`ncorr=20`, :math:`nlen=16` and :math:`ncount=2`), +this corresponds to 7864320 time steps. If longer correlation times are +needed, the value of ncorr should be increased. Using :math:`nlen=16` and +:math:`ncount=2`, with :math:`ncorr=30`, the maximum number of steps that can +be correlated is 80530636808. If :math:`ncorr=40`, correlation times in excess +of :math:`8\times 10^{12}` time steps can be calculated. The total memory needed for each correlation pair is roughly -4\*ncorr\*nlen\*8 bytes. With the default values of the parameters, this -corresponds to about 10 KB. +:math:`4 \times ncorr\times nlen \times 8` bytes. +With the default values of the parameters, this corresponds to about 10 KB. -For the meaning of the additional optional keywords, see the :doc:`fix ave/correlate ` doc page. +For the meaning of the additional optional keywords, see the +:doc:`fix ave/correlate ` doc page. Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -128,7 +133,8 @@ Restrictions """""""""""" 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 ` page for more info. +LAMMPS was built with that package. See the +:doc:`Build package ` page for more info. Related commands """""""""""""""" @@ -140,8 +146,9 @@ Default none -The option defaults for keywords that are also keywords for the :doc:`fix ave/correlate ` command are as follows: type = -auto, start = 0, no file output, title 1,2 = strings as described on +The option defaults for keywords that are also keywords for the +:doc:`fix ave/correlate ` command are as follows: +type = auto, start = 0, no file output, title 1,2 = strings as described on the :doc:`fix ave/correlate ` doc page. The option defaults for keywords unique to this command are as diff --git a/doc/src/fix_ave_histo.rst b/doc/src/fix_ave_histo.rst index 5d36a372c3..56671c30f5 100644 --- a/doc/src/fix_ave_histo.rst +++ b/doc/src/fix_ave_histo.rst @@ -10,7 +10,7 @@ fix ave/histo/weight command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID style Nevery Nrepeat Nfreq lo hi Nbin value1 value2 ... keyword args ... @@ -22,7 +22,7 @@ Syntax * lo,hi = lo/hi bounds within which to histogram * Nbin = # of histogram bins * one or more input values can be listed -* value = x, y, z, vx, vy, vz, fx, fy, fz, c_ID, c_ID[N], f_ID, f_ID[N], v_name +* value = *x*, *y*, *z*, *vx*, *vy*, *vz*, *fx*, *fy*, *fz*, c_ID, c_ID[N], f_ID, f_ID[N], v_name .. parsed-literal:: @@ -126,26 +126,27 @@ length. The first value (a scalar or vector) is what is histogrammed into bins, in the same manner the fix ave/histo command operates. The second value (a scalar or vector) is used as a "weight". This means that instead of each value tallying a "1" to its bin, the -corresponding weight is tallied. E.g. The Nth entry (weight) in the -second vector is tallied to the bin corresponding to the Nth entry in -the first vector. +corresponding weight is tallied. For example, the :math:`N^\text{th}` entry +(weight) in the second vector is tallied to the bin corresponding to the +:math:`N^\text{th}` entry in the first vector. ---------- For input values from a compute or fix or variable, the bracketed index I can be specified using a wildcard asterisk with the index to effectively specify multiple values. This takes the form "\*" or -"\*n" or "n\*" or "m\*n". If N = the size of the vector (for *mode* = -scalar) or the number of columns in the array (for *mode* = vector), -then an asterisk with no numeric values means all indices from 1 to N. +"\*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 N (inclusive). A middle +trailing asterisk means all indices from m 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 elements of the -vector or columns of the array had been listed one by one. E.g. these -2 fix ave/histo commands are equivalent, since the :doc:`compute -com/chunk ` command creates a global array with 3 +vector or columns of the array had been listed one by one. For example, the +following two fix ave/histo commands are equivalent, since the :doc:`compute +com/chunk ` command creates a global array with three columns: .. code-block:: LAMMPS @@ -164,31 +165,35 @@ columns: ---------- -The *Nevery*, *Nrepeat*, and *Nfreq* arguments specify on what -timesteps the input values will be used in order to contribute to the -histogram. The final histogram is generated on timesteps that are -multiple of *Nfreq*\ . It is averaged over *Nrepeat* histograms, -computed in the preceding portion of the simulation every *Nevery* -timesteps. *Nfreq* must be a multiple of *Nevery* and *Nevery* must -be non-zero even if *Nrepeat* is 1. Also, the timesteps -contributing to the histogram value cannot overlap, -i.e. Nrepeat\*Nevery can not exceed Nfreq. +The :math:`N_\text{every}`, :math:`N_\text{repeat}`, and :math:`N_\text{freq}` +arguments specify on what time steps the input values will be used in order to +contribute to the histogram. The final histogram is generated on time steps +that are multiple of :math:`N_\text{freq}`\ . It is averaged over +:math:`N_\text{repeat}` histograms, computed in the preceding portion of the +simulation every :math:`N_\text{every}` time steps. +:math:`N_\text{freq}` must be a multiple of :math:`N_\text{every}` and +:math:`N_\text{every}` must be non-zero even if :math:`N_\text{repeat}` is 1. +Also, the time steps contributing to the histogram value cannot overlap +(i.e., :math:`N_\text{repeat}\times N_\text{every}` cannot exceed +:math:`N_\text{freq}`). -For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then input values -on timesteps 90,92,94,96,98,100 will be used to compute the final -histogram on timestep 100. Similarly for timesteps -190,192,194,196,198,200 on timestep 200, etc. If Nrepeat=1 and Nfreq -= 100, then no time averaging of the histogram is done; a histogram is -simply generated on timesteps 100,200,etc. +For example, if :math:`N_\text{every}=2`, :math:`N_\text{repeat}=6`, and +:math:`N_\text{freq}=100`, then input values on time steps 90, 92, 94, 96, 98, +and 100 will be used to compute the final histogram on timestep 100. +Similarly for timesteps 190, 192, 194, 196, 198, and 200 on timestep 200, etc. +If :math:`N_\text{repeat}=1` and :math:`N_\text{freq} = 100`, then no time +averaging of the histogram is done; a histogram is simply generated on +timesteps 100, 200, etc. ---------- -The atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are -self-explanatory. Note that other atom attributes can be used as -inputs to this fix by using the :doc:`compute property/atom ` command and then specifying -an input value from that compute. +The atom attribute values (*x*, *y*, *z*, *vx*, *vy*, *vz*, *fx*, *fy*, and +*fz*) are self-explanatory. Note that other atom attributes can be used as +inputs to this fix by using the +:doc:`compute property/atom ` command and then +specifying an input value from that compute. -If a value begins with "c\_", a compute ID must follow which has been +If a value begins with "c\_," a compute ID must follow which has been previously defined in the input script. If *mode* = scalar, then if no bracketed term is appended, the global scalar calculated by the compute is used. If a bracketed term is appended, the Ith element of @@ -201,35 +206,38 @@ how I can be specified with a wildcard asterisk to effectively specify multiple values. Note that there is a :doc:`compute reduce ` command -which can sum per-atom quantities into a global scalar or vector which -can thus be accessed by fix ave/histo. Or it can be a compute defined -not in your input script, but by :doc:`thermodynamic output ` or other fixes such as :doc:`fix nvt ` +that can sum per-atom quantities into a global scalar or vector, which +can then be accessed by fix ave/histo. It can also be a compute defined +not in your input script, but by :doc:`thermodynamic output ` +or other fixes such as :doc:`fix nvt ` or :doc:`fix temp/rescale `. See the doc pages for these commands which give the IDs of these computes. Users can also -write code for their own compute styles and :doc:`add them to LAMMPS `. +write code for their own compute styles and +:doc:`add them to LAMMPS `. -If a value begins with "f\_", a fix ID must follow which has been +If a value begins with "f\_," a fix ID must follow which has been previously defined in the input script. If *mode* = scalar, then if no bracketed term is appended, the global scalar calculated by the fix is used. If a bracketed term is appended, the Ith element of the global vector calculated by the fix is used. If *mode* = vector, then if no bracketed term is appended, the global or per-atom or local vector calculated by the fix is used. If a bracketed term is -appended, the Ith column of the global or per-atom or local array -calculated by the fix is used. See the discussion above for how I can -be specified with a wildcard asterisk to effectively specify multiple -values. +appended, the :math:`I^\text{th}` column of the global or per-atom or local +array calculated by the fix is used. See the discussion above for how +:math:`I` can be specified with a wildcard asterisk to effectively specify +multiple values. Note that some fixes only produce their values on certain timesteps, -which must be compatible with *Nevery*, else an error will result. -Users can also write code for their own fix styles and :doc:`add them to LAMMPS `. +which must be compatible with :math:`N_\text{every}`, else an error will +result. Users can also write code for their own fix styles and +:doc:`add them to LAMMPS `. -If a value begins with "v\_", a variable name must follow which has +If a value begins with "v\_," a variable name must follow which has been previously defined in the input script. If *mode* = scalar, then only equal-style or vector-style variables can be used, which both produce global values. In this mode, a vector-style variable requires -a bracketed term to specify the Ith element of the vector calculated -by the variable. If *mode* = vector, then only vector-style or +a bracketed term to specify the :math:`I^\text{th}` element of the vector +calculated by the variable. If *mode* = vector, then only vector-style or atom-style variables can be used, which produce a global or per-atom vector respectively. The vector-style variable must be used without a bracketed term. See the :doc:`variable ` command for details. @@ -259,44 +267,44 @@ keyword should be used to specify which output will be used. The remaining input arguments must still be consistent. The *beyond* keyword determines how input values that fall outside the -*lo* to *hi* bounds are treated. Values such that *lo* <= value <= -*hi* are assigned to one bin. Values on a bin boundary are assigned -to the lower of the 2 bins. If *beyond* is set to *ignore* then -values < *lo* and values > *hi* are ignored, i.e. they are not binned. -If *beyond* is set to *end* then values < *lo* are counted in the -first bin and values > *hi* are counted in the last bin. If *beyond* -is set to *extend* then two extra bins are created, so that there are -Nbins+2 total bins. Values < *lo* are counted in the first bin and -values > *hi* are counted in the last bin (Nbins+2). Values between -*lo* and *hi* (inclusive) are counted in bins 2 through Nbins+1. The -"coordinate" stored and printed for these two extra bins is *lo* and -*hi*\ . +*lo* to *hi* bounds are treated. Values such that *lo* :math:`\le` value +:math:`\le` *hi* are assigned to one bin. Values on a bin boundary are +assigned to the lower of the two bins. If *beyond* is set to *ignore* then +values :math:`<` *lo* and values :math:`>` *hi* are ignored (i.e., they are not +binned). If *beyond* is set to *end*, then values :math:`<` *lo* are counted in +the first bin and values :math:`>` *hi* are counted in the last bin. +If *beyond* is set to *extend*, then two extra bins are created so that there +are :math:`N_\text{bins}+2` total bins. Values :math:`<` *lo* are counted in +the first bin and values :math:`>` *hi* are counted in the last bin +:math:`(N_\text{bins}+2)`\ . Values between +*lo* and *hi* (inclusive) are counted in bins 2 through +:math:`N_\text{bins}+1`\ . The "coordinate" stored and printed for these two +extra bins is *lo* and *hi*\ . -The *ave* keyword determines how the histogram produced every *Nfreq* -steps are averaged with histograms produced on previous steps that -were multiples of *Nfreq*, before they are accessed by another output -command or written to a file. +The *ave* keyword determines how the histogram produced every +:math:`N_\text{freq}` steps are averaged with histograms produced on previous +steps that were multiples of :math:`N_\text{freq}`, before they are accessed by +another output command or written to a file. If the *ave* setting is *one*, then the histograms produced on -timesteps that are multiples of *Nfreq* are independent of each other; -they are output as-is without further averaging. +timesteps that are multiples of :math:`N_\text{freq}` are independent of each +other; they are output as-is without further averaging. If the *ave* setting is *running*, then the histograms produced on -timesteps that are multiples of *Nfreq* are summed and averaged in a -cumulative sense before being output. Each bin value in the histogram -is thus the average of the bin value produced on that timestep with -all preceding values for the same bin. This running average begins -when the fix is defined; it can only be restarted by deleting the fix -via the :doc:`unfix ` command, or by re-defining the fix by -re-specifying it. +timesteps that are multiples of :math:`N_\text{freq}` are summed and averaged +in a cumulative sense before being output. Each bin value in the histogram +is thus the average of the bin value produced on that timestep with all +preceding values for the same bin. This running average begins when the fix is +defined; it can only be restarted by deleting the fix via the +:doc:`unfix ` command, or by re-defining the fix by re-specifying it. If the *ave* setting is *window*, then the histograms produced on -timesteps that are multiples of *Nfreq* are summed within a moving -"window" of time, so that the last M histograms are used to produce -the output. E.g. if M = 3 and Nfreq = 1000, then the output on step -10000 will be the combined histogram of the individual histograms on -steps 8000,9000,10000. Outputs on early steps will be sums over less -than M histograms if they are not available. +timesteps that are multiples of :math:`N_\text{freq}` are summed within a +moving "window" of time, so that the last :math:`M` histograms are used to +produce the output (e.g., if :math:`M = 3` and :math:`N_\text{freq} = 1000`, +then the output on step 10000 will be the combined histogram of the individual +histograms on steps 8000, 9000, and 10000. Outputs on early steps will be sums +over less than :math:`M` histograms if they are not available. The *start* keyword specifies what timestep histogramming will begin on. The default is step 0. Often input values can be 0.0 at time 0, @@ -321,8 +329,8 @@ The *overwrite* keyword will continuously overwrite the output file with the latest output, so that it only contains one timestep worth of output. This option can only be used with the *ave running* setting. -The *title1* and *title2* and *title3* keywords allow specification of -the strings that will be printed as the first 3 lines of the output +The *title1*, *title2*, and *title3* keywords allow specification of +the strings that will be printed as the first three lines of the output file, assuming the *file* keyword was used. LAMMPS uses default values for each of these, so they do not need to be specified. @@ -336,7 +344,7 @@ By default, these header lines are as follows: In the first line, ID is replaced with the fix-ID. The second line describes the six values that are printed at the first of each section -of output. The third describes the 4 values printed for each bin in +of output. The third describes the four values printed for each bin in the histogram. ---------- @@ -344,13 +352,14 @@ the histogram. 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 -are relevant to this fix. +No information about this fix is written to +:doc:`binary restart files `. +None of the :doc:`fix_modify ` options are relevant to this fix. This fix produces a global vector and global array which can be accessed by various :doc:`output commands `. The values -can only be accessed on timesteps that are multiples of *Nfreq* since -that is when a histogram is generated. The global vector has 4 +can only be accessed on timesteps that are multiples of :math:`N_\text{freq}` +since that is when a histogram is generated. The global vector has four values: * 1 = total counts in the histogram @@ -358,19 +367,20 @@ values: * 3 = min value of all input values, including ones not histogrammed * 4 = max value of all input values, including ones not histogrammed -The global array has # of rows = Nbins and # of columns = 3. The +The global array has :math:`N_\text{bins}` rows and three columns. The first column has the bin coordinate, the second column has the count of values in that histogram bin, and the third column has the bin count divided by the total count (not including missing counts), so that the values in the third column sum to 1.0. The vector and array values calculated by this fix are all treated as -intensive. If this is not the case, e.g. due to histogramming -per-atom input values, then you will need to account for that when +intensive. If this is not the case (e.g., due to histogramming +per-atom input values), then you will need to account for that when interpreting the values produced by this fix. 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 """""""""""" @@ -379,7 +389,8 @@ Restrictions Related commands """""""""""""""" -:doc:`compute `, :doc:`fix ave/atom `, :doc:`fix ave/chunk `, :doc:`fix ave/time `, +:doc:`compute `, :doc:`fix ave/atom `, +:doc:`fix ave/chunk `, :doc:`fix ave/time `, :doc:`variable `, :doc:`fix ave/correlate `, Default diff --git a/doc/src/fix_ave_time.rst b/doc/src/fix_ave_time.rst index bcc7dd4997..782f0850cc 100644 --- a/doc/src/fix_ave_time.rst +++ b/doc/src/fix_ave_time.rst @@ -6,15 +6,15 @@ fix ave/time command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID ave/time Nevery Nrepeat Nfreq value1 value2 ... keyword args ... * ID, group-ID are documented in :doc:`fix ` command * ave/time = style name of this fix command -* Nevery = use input values every this many timesteps +* Nevery = use input values every this many time steps * Nrepeat = # of times to use input values for calculating averages -* Nfreq = calculate averages every this many timesteps +* Nfreq = calculate averages every this many time steps * one or more input values can be listed * value = c_ID, c_ID[N], f_ID, f_ID[N], v_name @@ -40,7 +40,7 @@ Syntax running = output cumulative average of all previous Nfreq steps window M = output average of M most recent Nfreq steps *start* args = Nstart - Nstart = start averaging on this timestep + Nstart = start averaging on this time step *off* arg = M = do not average this value M = value # from 1 to Nvalues *file* arg = filename @@ -69,7 +69,7 @@ Examples Description """"""""""" -Use one or more global values as inputs every few timesteps, and +Use one or more global values as inputs every few time steps, and average them over longer timescales. The resulting averages can be used by other :doc:`output commands ` such as :doc:`thermo_style custom `, and can also be written to a @@ -86,9 +86,11 @@ Each listed value can be the result of a :doc:`compute ` or :doc:`variable `. In each case, the compute, fix, or variable must produce a global quantity, not a per-atom or local quantity. If you wish to spatial- or time-average or histogram per-atom quantities -from a compute, fix, or variable, then see the :doc:`fix ave/chunk `, :doc:`fix ave/atom `, +from a compute, fix, or variable, then see the +:doc:`fix ave/chunk `, :doc:`fix ave/atom `, or :doc:`fix ave/histo ` commands. If you wish to sum a -per-atom quantity into a single global quantity, see the :doc:`compute reduce ` command. +per-atom quantity into a single global quantity, see the +:doc:`compute reduce ` command. :doc:`Computes ` that produce global quantities are those which do not have the word *atom* in their style name. Only a few @@ -100,13 +102,13 @@ be used, since they produce per-atom values. The input values must either be all scalars or all vectors depending on the setting of the *mode* keyword. In both cases, the averaging is -performed independently on each input value. I.e. each input scalar +performed independently on each input value (i.e., each input scalar is averaged independently or each element of each input vector is -averaged independently. +averaged independently). If *mode* = scalar, then the input values must be scalars, or vectors -with a bracketed term appended, indicating the Ith value of the vector -is used. +with a bracketed term appended, indicating the :math:`I^\text{th}` value of the +vector is used. If *mode* = vector, then the input values must be vectors, or arrays with a bracketed term appended, indicating the Ith column of the array @@ -118,17 +120,17 @@ the vector or number of rows in the array. For input values from a compute or fix or variable, the bracketed index I can be specified using a wildcard asterisk with the index to effectively specify multiple values. This takes the form "\*" or -"\*n" or "n\*" or "m\*n". If N = the size of the vector (for *mode* = +"\*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 N. -A leading asterisk means all indices from 1 to n (inclusive). A -trailing asterisk means all indices from n to N (inclusive). A middle -asterisk means all indices from m to n (inclusive). +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 elements of the -vector or columns of the array had been listed one by one. E.g. these -2 fix ave/time commands are equivalent, since the :doc:`compute rdf -` command creates, in this case, a global array with 3 +vector or columns of the array had been listed one by one. For example, the +following two fix ave/time commands are equivalent, since the :doc:`compute rdf +` command creates, in this case, a global array with three columns, each of length 50: .. code-block:: LAMMPS @@ -147,22 +149,24 @@ columns, each of length 50: ---------- -The *Nevery*, *Nrepeat*, and *Nfreq* arguments specify on what -timesteps the input values will be used in order to contribute to the -average. The final averaged quantities are generated on timesteps -that are a multiple of *Nfreq*\ . The average is over *Nrepeat* -quantities, computed in the preceding portion of the simulation every -*Nevery* timesteps. *Nfreq* must be a multiple of *Nevery* and -*Nevery* must be non-zero even if *Nrepeat* is 1. Also, the timesteps +The :math:`N_\text{every}`, :math:`N_\text{repeat}`, and :math:`N_\text{freq}` +arguments specify on what time steps the input values will be used in order to +contribute to the average. The final averaged quantities are generated on +time steps that are a multiple of :math:`N_\text{freq}`\ . The average is over +:math:`N_\text{repeat}` quantities, computed in the preceding portion of the +simulation every :math:`N_\text{every}` time steps. :math:`N_\text{freq}` must +be a multiple of :math:`N_\text{every}` and :math:`N_\text{every}` must be +non-zero even if :math:`N_\text{repeat} = 1`. Also, the time steps contributing to the average value cannot overlap, i.e. Nrepeat\*Nevery can not exceed Nfreq. -For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on -timesteps 90,92,94,96,98,100 will be used to compute the final average -on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on -timestep 200, etc. If Nrepeat=1 and Nfreq = 100, then no time -averaging is done; values are simply generated on timesteps -100,200,etc. +For example, if :math:`N_\text{every}=2`, :math:`N_\text{repeat}=6`, and +:math:`N_\text{freq}=100`, then values on time steps 90, 92, 94, 96, 98, and +100 will be used to compute the final average on time step 100. Similarly for +time steps 190, 192, 194, 196, 198, and 200 on time step 200, etc. +If :math:`N_\text{repeat}=1` and :math:`N_\text{freq} = 100`, then no time +averaging is done; values are simply generated on time steps +100, 200, etc. ---------- @@ -178,8 +182,8 @@ See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values. Note that there is a :doc:`compute reduce ` command -which can sum per-atom quantities into a global scalar or vector which -can thus be accessed by fix ave/time. Or it can be a compute defined +that can sum per-atom quantities into a global scalar or vector, which +can then be accessed by fix ave/time. It can also be a compute defined not in your input script, but by :doc:`thermodynamic output ` or other fixes such as :doc:`fix nvt ` or :doc:`fix temp/rescale `. See the doc pages for @@ -198,7 +202,7 @@ global array calculated by the fix is used. See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values. -Note that some fixes only produce their values on certain timesteps, +Note that some fixes only produce their values on certain time steps, which must be compatible with *Nevery*, else an error will result. Users can also write code for their own fix styles and :doc:`add them to LAMMPS `. @@ -228,32 +232,32 @@ vectors, or columns of global arrays. They can also be global arrays, which are converted into a series of global vectors (one per column), as explained above. -The *ave* keyword determines how the values produced every *Nfreq* -steps are averaged with values produced on previous steps that were -multiples of *Nfreq*, before they are accessed by another output -command or written to a file. +The *ave* keyword determines how the values produced every +:math:`N_\text{freq}` steps are averaged with values produced on previous steps +that were multiples of :math:`N_\text{freq}`, before they are accessed by +another output command or written to a file. -If the *ave* setting is *one*, then the values produced on timesteps -that are multiples of *Nfreq* are independent of each other; they are -output as-is without further averaging. +If the *ave* setting is *one*, then the values produced on time steps +that are multiples of :math:`N_\text{freq}` are independent of each other; they +are output as-is without further averaging. If the *ave* setting is *running*, then the values produced on -timesteps that are multiples of *Nfreq* are summed and averaged in a -cumulative sense before being output. Each output value is thus the -average of the value produced on that timestep with all preceding +time steps that are multiples of :math:`N_\text{freq}` are summed and averaged +in a cumulative sense before being output. Each output value is thus the +average of the value produced on that time step with all preceding values. This running average begins when the fix is defined; it can only be restarted by deleting the fix via the :doc:`unfix ` command, or by re-defining the fix by re-specifying it. If the *ave* setting is *window*, then the values produced on -timesteps that are multiples of *Nfreq* are summed and averaged within +time steps that are multiples of *Nfreq* are summed and averaged within a moving "window" of time, so that the last M values are used to -produce the output. E.g. if M = 3 and Nfreq = 1000, then the output -on step 10000 will be the average of the individual values on steps -8000,9000,10000. Outputs on early steps will average over less than M -values if they are not available. +produce the output. For example, if :math:`M = 3` and +:math:`N_\text{freq} = 1000`, then the output on step 10000 will be the average +of the individual values on steps 8000, 9000, and 10000. Outputs on early +steps will average over less than :math:`M` values if they are not available. -The *start* keyword specifies what timestep averaging will begin on. +The *start* keyword specifies what time step averaging will begin on. The default is step 0. Often input values can be 0.0 at time 0, so setting *start* to a larger value can avoid including a 0.0 in a running or windowed average. @@ -262,9 +266,9 @@ The *off* keyword can be used to flag any of the input values. If a value is flagged, it will not be time averaged. Instead the most recent input value will always be stored and output. This is useful if one of more of the inputs produced by a compute or fix or variable -are effectively constant or are simply current values. E.g. they are +are effectively constant or are simply current values (e.g., they are being written to a file with other time-averaged values for purposes -of creating well-formatted output. +of creating well-formatted output). The *file* keyword allows a filename to be specified. Every *Nfreq* steps, one quantity or vector of quantities is written to the file for @@ -288,13 +292,13 @@ effort in Python using the *pyyaml*, *pandas*, and *matplotlib* packages. The *overwrite* keyword will continuously overwrite the output file -with the latest output, so that it only contains one timestep worth of +with the latest output, so that it only contains one time step worth of output. This option can only be used with the *ave running* setting. The *format* keyword sets the numeric format of each value when it is printed to a file via the *file* keyword. Note that all values are floating point quantities. The default format is %g. You can specify -a higher precision if desired, e.g. %20.16g. +a higher precision if desired (e.g., %20.16g). The *title1* and *title2* and *title3* keywords allow specification of the strings that will be printed as the first 2 or 3 lines of the @@ -340,8 +344,8 @@ a YAML format file this name will be in the list of keywords. This fix produces a global scalar or global vector or global array which can be accessed by various :doc:`output commands `. -The values can only be accessed on timesteps that are multiples of -*Nfreq* since that is when averaging is performed. +The values can only be accessed on time steps that are multiples of +:math:`N_\text{freq}` since that is when averaging is performed. A scalar is produced if only a single input value is averaged and *mode* = scalar. A vector is produced if multiple input values are @@ -354,17 +358,18 @@ of rows = length of the input vectors and # of columns = number of inputs. If the fix produces a scalar or vector, then the scalar and each -element of the vector can be either "intensive" or "extensive", +element of the vector can be either "intensive" or "extensive," depending on whether the values contributing to the scalar or vector -element are "intensive" or "extensive". If the fix produces an array, +element are "intensive" or "extensive." If the fix produces an array, then all elements in the array must be the same, either "intensive" or -"extensive". If a compute or fix provides the value being time +"extensive." If a compute or fix provides the value being time averaged, then the compute or fix determines whether the value is intensive or extensive; see the page for that compute or fix for further info. Values produced by a variable are treated as intensive. 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 """""""""""" @@ -373,7 +378,8 @@ Restrictions Related commands """""""""""""""" -:doc:`compute `, :doc:`fix ave/atom `, :doc:`fix ave/chunk `, :doc:`fix ave/histo `, +:doc:`compute `, :doc:`fix ave/atom `, +:doc:`fix ave/chunk `, :doc:`fix ave/histo `, :doc:`variable `, :doc:`fix ave/correlate `, Default diff --git a/doc/src/fix_aveforce.rst b/doc/src/fix_aveforce.rst index 414fa497ed..ea535697f4 100644 --- a/doc/src/fix_aveforce.rst +++ b/doc/src/fix_aveforce.rst @@ -6,7 +6,7 @@ fix aveforce command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID aveforce fx fy fz keyword value ... @@ -48,13 +48,13 @@ component. The actual force on each atom is then set to the average value plus the component specified in this command. This means each atom in the group receives the same force. -Any of the fx,fy,fz values can be specified as NULL which means the -force in that dimension is not changed. Note that this is not the +Any of the *fx*, *fy*, or *fz* values can be specified as :code:`NULL`, which +means the force in that dimension is not changed. Note that this is not the same as specifying a 0.0 value, since that sets all forces to the same average value without adding in any additional force. -Any of the 3 quantities defining the force components can be specified -as an equal-style :doc:`variable `, namely *fx*, *fy*, *fz*\ . +Any of the three quantities defining the force components, namely *fx*, *fy*, +and *fz*, can be specified as an equal-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 timestep, and its value used to determine the average @@ -78,17 +78,17 @@ to it. 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 ` *respa* option is supported by this 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 3-vector of forces, which can be accessed +This fix computes a global three-vector of forces, which can be accessed by various :doc:`output commands `. This is the total force on the group of atoms before the forces on individual atoms are -changed by the fix. The vector values calculated by this fix are -"extensive". +changed by the fix. The vector 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. diff --git a/doc/src/fix_balance.rst b/doc/src/fix_balance.rst index 66457cb61a..7afb077881 100644 --- a/doc/src/fix_balance.rst +++ b/doc/src/fix_balance.rst @@ -6,7 +6,7 @@ fix balance command Syntax """""" -.. parsed-literal:: +.. code-block:: LAMMPS fix ID group-ID balance Nfreq thresh style args keyword args ... @@ -19,7 +19,7 @@ Syntax .. parsed-literal:: shift args = dimstr Niter stopthresh - dimstr = sequence of letters containing "x" or "y" or "z", each not more than once + dimstr = sequence of letters containing *x* or *y* or *z*, each not more than once Niter = # of times to iterate within each dimension of dimstr sequence stopthresh = stop balancing when this imbalance threshold is reached *rcb* args = none @@ -72,10 +72,10 @@ perform "static" balancing, before or between runs, see the Load-balancing is typically most useful if the particles in the simulation box have a spatially-varying density distribution or where the computational cost varies significantly between different -atoms. E.g. a model of a vapor/liquid interface, or a solid with +atoms (e.g., a model of a vapor/liquid interface, or a solid with an irregular-shaped geometry containing void regions, or -:doc:`hybrid pair style simulations ` which combine -pair styles with different computational cost. In these cases, the +:doc:`hybrid pair style simulations ` that combine +pair styles with different computational cost). In these cases, the LAMMPS default of dividing the simulation box volume into a regular-spaced grid of 3d bricks, with one equal-volume sub-domain per processor, may assign numbers of particles per processor in a @@ -92,28 +92,30 @@ processor. .. note:: The weighting options listed above are documented with the - :doc:`balance ` command in :ref:`this section of the balance command ` doc page. That section + :doc:`balance ` command in :ref:`this section of the balance + command ` doc page. That section describes the various weighting options and gives a few examples of how they can be used. The weighting options are the same for both the fix balance and :doc:`balance ` commands. Note that the :doc:`processors ` command allows some control over how the box volume is split across processors. Specifically, for -a Px by Py by Pz grid of processors, it allows choice of Px, Py, and -Pz, subject to the constraint that Px \* Py \* Pz = P, the total number -of processors. This is sufficient to achieve good load-balance for +a :math:`P_x \times P_y \times P_z` grid of processors, it allows choices of +:math:`P_x`, :math:`P_y`, and :math:`P_z` subject to the constraint that +:math:`P_x P_y P_z = P`, the total number of processors. +This is sufficient to achieve good load-balance for some problems on some processor counts. However, all the processor -sub-domains will still have the same shape and same volume. +sub-domains will still have the same shape and the same volume. -On a particular timestep, a load-balancing operation is only performed +On a particular time step, a load-balancing operation is only performed if the current "imbalance factor" in particles owned by each processor exceeds the specified *thresh* parameter. The imbalance factor is defined as the maximum number of particles (or weight) owned by any processor, divided by the average number of particles (or weight) per -processor. Thus an imbalance factor of 1.0 is perfect balance. +processor. Thus, an imbalance factor of 1.0 is perfect balance. As an example, for 10000 particles running on 10 processors, if the -most heavily loaded processor has 1200 particles, then the factor is +most heavily loaded processor has 1200 particles, then the imbalance factor is 1.2, meaning there is a 20% imbalance. Note that re-balances can be forced even if the current balance is perfect (1.0) be specifying a *thresh* < 1.0. @@ -125,28 +127,29 @@ forced even if the current balance is perfect (1.0) be specifying a may not be achieved. For example, "grid" methods (defined below) that create a logical 3d grid cannot achieve perfect balance for many irregular distributions of particles. Likewise, if a portion of the - system is a perfect lattice, e.g. the initial system is generated by - the :doc:`create_atoms ` command, then "grid" methods may - be unable to achieve exact balance. This is because entire lattice - planes will be owned or not owned by a single processor. + system is a perfect, non-rotated lattice (e.g., the initial system is + generated by the :doc:`create_atoms ` command with no + rotations), then "grid" methods may be unable to achieve exact balance. + This is because entire lattice planes will be owned or not owned by a single + processor. .. note:: The imbalance factor is also an estimate of the maximum speed-up you can hope to achieve by running a perfectly balanced simulation - versus an imbalanced one. In the example above, the 10000 particle + versus an imbalanced one. In the example above, the 10000-particle simulation could run up to 20% faster if it were perfectly balanced, versus when imbalanced. However, computational cost is not strictly proportional to particle count, and changing the relative size and shape of processor sub-domains may lead to additional computational - and communication overheads, e.g. in the PPPM solver used via the - :doc:`kspace_style ` command. Thus you should benchmark + and communication overheads (e.g., in the PPPM solver used via the + :doc:`kspace_style ` command). Thus, you should benchmark the run times of a simulation before and after balancing. ---------- The method used to perform a load balance is specified by one of the -listed styles, which are described in detail below. There are 2 kinds +listed styles, which are described in detail below. There are two kinds of styles. The *shift* style is a "grid" method which produces a logical 3d grid @@ -198,11 +201,12 @@ The *group-ID* is ignored. However the impact of balancing on different groups of atoms can be affected by using the *group* weight style as described below. -The *Nfreq* setting determines how often a re-balance is performed. If -*Nfreq* > 0, then re-balancing will occur every *Nfreq* steps. Each -time a re-balance occurs, a reneighboring is triggered, so *Nfreq* -should not be too small. If *Nfreq* = 0, then re-balancing will be -done every time reneighboring normally occurs, as determined by the +The :math:`N_\text{freq}` setting determines how often a re-balance is +performed. If :math:`N_\text{freq} > 0`, then re-balancing will occur every +:math:`N_\text{freq}` steps. Each time a re-balance occurs, a reneighboring is +triggered, so :math:`N_\text{freq}` should not be too small. If +:math:`N_\text{freq} = 0`, then re-balancing will be done every time +reneighboring normally occurs, as determined by the the :doc:`neighbor ` and :doc:`neigh_modify ` command settings. @@ -216,7 +220,7 @@ above. It changes the positions of cutting planes between processors in an iterative fashion, seeking to reduce the imbalance factor. The *dimstr* argument is a string of characters, each of which must be -an "x" or "y" or "z". Each character can appear zero or one time, +*x* or *y* or *z*. Each character can appear zero or one time, since there is no advantage to balancing on a dimension more than once. You should normally only list dimensions where you expect there to be a density variation in the particles. @@ -224,8 +228,8 @@ to be a density variation in the particles. Balancing proceeds by adjusting the cutting planes in each of the dimensions listed in *dimstr*, one dimension at a time. For a single dimension, the balancing operation (described below) is iterated on up -to *Niter* times. After each dimension finishes, the imbalance factor -is re-computed, and the balancing operation halts if the *stopthresh* +to :math:`N_\text{iter}` times. After each dimension finishes, the imbalance +factor is re-computed, and the balancing operation halts if the *stopthresh* criterion is met. A re-balance operation in a single dimension is performed using a @@ -265,15 +269,15 @@ the normal reneighboring procedure. by the extent of a processor's sub-domain in one dimension. The size of this bracketing region shrinks based on the local density, as described above, which should typically be 1/2 or more every - iteration. Thus if *Niter* is specified as 10, the cutting plane will - typically be positioned to better than 1 part in 1000 accuracy - (relative to the perfect target position). For *Niter* = 20, it will - be accurate to better than 1 part in a million. Thus there is no need - to set *Niter* to a large value. This is especially true if you are - re-balancing often enough that each time you expect only an incremental - adjustment in the cutting planes is necessary. LAMMPS will check if - the threshold accuracy is reached (in a dimension) is less iterations - than *Niter* and exit early. + iteration. Thus if :math:`N_\text{iter}` is specified as 10, the cutting + plane will typically be positioned to better than 1 part in 1000 accuracy + (relative to the perfect target position). For :math:`N_\text{iter} = 20`, + it will be accurate to better than 1 part in a million. Thus there is no + need to set :math:`N_\text{iter}` to a large value. This is especially true + if you are re-balancing often enough that each time you expect only an + incremental adjustment in the cutting planes is necessary. LAMMPS will + check if the threshold accuracy is reached (in a dimension) is less + iterations than :math:`N_\text{iter}` and exit early. ---------- @@ -281,12 +285,12 @@ The *rcb* style invokes a "tiled" method for balancing, as described above. It performs a recursive coordinate bisectioning (RCB) of the simulation domain. The basic idea is as follows. -The simulation domain is cut into 2 boxes by an axis-aligned cut in +The simulation domain is cut into two boxes by an axis-aligned cut in the longest dimension, leaving one new box on either side of the cut. -All the processors are also partitioned into 2 groups, half assigned +All the processors are also partitioned into two groups, half assigned to the box on the lower side of the cut, and half to the box on the -upper side. (If the processor count is odd, one side gets an extra -processor.) The cut is positioned so that the number of atoms in the +upper side. If the processor count is odd, one side gets an extra +processor. The cut is positioned so that the number of atoms in the lower box is exactly the number that the processors assigned to that box should own for load balance to be perfect. This also makes load balance for the upper box perfect. The positioning is done @@ -309,7 +313,7 @@ results of each re-balancing operation. The file contains the bounds of the sub-domain for each processor after the balancing operation completes. The format of the file is compatible with the `Pizza.py `_ *mdump* tool which has support for manipulating and -visualizing mesh files. An example is shown here for a balancing by 4 +visualizing mesh files. An example is shown here for a balancing by four processors for a 2d problem: .. parsed-literal:: @@ -349,27 +353,28 @@ processors for a 2d problem: 3 1 9 10 11 12 4 1 13 14 15 16 -The coordinates of all the vertices are listed in the NODES section, 5 -per processor. Note that the 4 sub-domains share vertices, so there +The coordinates of all the vertices are listed in the NODES section, five +per processor. Note that the four sub-domains share vertices, so there will be duplicate nodes in the list. -The "SQUARES" section lists the node IDs of the 4 vertices in a +The "SQUARES" section lists the node IDs of the four vertices in a rectangle for each processor (1 to 4). -For a 3d problem, the syntax is similar with 8 vertices listed for -each processor, instead of 4, and "SQUARES" replaced by "CUBES". +For a 3d problem, the syntax is similar but with eight vertices listed for +each processor instead of four, and "SQUARES" replaced by "CUBES." ---------- 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 -are relevant to this fix. +No information about this fix is written to +:doc:`binary restart files `. None of the +:doc:`fix_modify ` options are relevant to this fix. This fix computes a global scalar which is the imbalance factor after the most recent re-balance and a global vector of length 3 with -additional information about the most recent re-balancing. The 3 +additional information about the most recent re-balancing. The three values in the vector are as follows: * 1 = max # of particles per processor @@ -380,22 +385,24 @@ As explained above, the imbalance factor is the ratio of the maximum number of particles (or total weight) on any processor to the average number of particles (or total weight) per processor. -These quantities can be accessed by various :doc:`output commands `. The scalar and vector values calculated -by this fix are "intensive". +These quantities can be accessed by various +:doc:`output commands `. The scalar and vector values calculated +by this fix are "intensive." 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 """""""""""" -For 2d simulations, the *z* style cannot be used. Nor can a "z" +For 2d simulations, the *z* style cannot be used, nor can *z* appear in *dimstr* for the *shift* style. Balancing through recursive bisectioning (\ *rcb* style) requires -:doc:`comm_style tiled ` +:doc:`comm_style tiled `\ . Related commands """""""""""""""" diff --git a/doc/src/pair_mesocnt.rst b/doc/src/pair_mesocnt.rst index e150c66721..4833ea6eb8 100644 --- a/doc/src/pair_mesocnt.rst +++ b/doc/src/pair_mesocnt.rst @@ -92,7 +92,7 @@ segments. Friction forces are a function of the relative velocity between a segment and its neighboring approximate chain (even in *segment* mode) and only act along the axes of the interacting segment and chain. In this potential, friction forces acting per unit length -of a nanotube segent are modelled as a shifted logistic function: +of a nanotube segment are modelled as a shifted logistic function: .. math:: From 40b1b1c48214342137ebfe3579287ed35c7bbc83 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Fri, 2 Sep 2022 21:33:30 -0400 Subject: [PATCH 6/7] support paths with blanks and avoid race condition when updating potentials --- cmake/Modules/LAMMPSUtils.cmake | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/cmake/Modules/LAMMPSUtils.cmake b/cmake/Modules/LAMMPSUtils.cmake index 9f624fc007..9b75209e16 100644 --- a/cmake/Modules/LAMMPSUtils.cmake +++ b/cmake/Modules/LAMMPSUtils.cmake @@ -110,14 +110,16 @@ function(FetchPotentials pkgfolder potfolder) math(EXPR plusone "${blank}+1") string(SUBSTRING ${line} 0 ${blank} pot) string(SUBSTRING ${line} ${plusone} -1 sum) - if(EXISTS ${LAMMPS_POTENTIALS_DIR}/${pot}) + if(EXISTS "${LAMMPS_POTENTIALS_DIR}/${pot}") file(MD5 "${LAMMPS_POTENTIALS_DIR}/${pot}" oldsum) endif() if(NOT sum STREQUAL oldsum) - message(STATUS "Checking external potential ${pot} from ${LAMMPS_POTENTIALS_URL}") - file(DOWNLOAD "${LAMMPS_POTENTIALS_URL}/${pot}.${sum}" "${CMAKE_BINARY_DIR}/${pot}" + message(STATUS "Downloading external potential ${pot} from ${LAMMPS_POTENTIALS_URL}") + string(MD5 TMP_EXT "${CMAKE_BINARY_DIR}") + file(DOWNLOAD "${LAMMPS_POTENTIALS_URL}/${pot}.${sum}" "${CMAKE_BINARY_DIR}/${pot}.${TMP_EXT}" EXPECTED_HASH MD5=${sum} SHOW_PROGRESS) - file(COPY "${CMAKE_BINARY_DIR}/${pot}" DESTINATION ${LAMMPS_POTENTIALS_DIR}) + file(COPY "${CMAKE_BINARY_DIR}/${pot}.${TMP_EXT}" DESTINATION "${LAMMPS_POTENTIALS_DIR}") + file(RENAME "${LAMMPS_POTENTIALS_DIR}/${pot}.${TMP_EXT}" "${LAMMPS_POTENTIALS_DIR}/${pot}") endif() endforeach() endif() From 61a72846769a73eee4a1f443f4fb46f9fb3a7043 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 6 Sep 2022 23:02:59 -0400 Subject: [PATCH 7/7] fix broken formatting --- doc/src/compute_property_atom.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/src/compute_property_atom.rst b/doc/src/compute_property_atom.rst index dad83ee79c..71cf4dda72 100644 --- a/doc/src/compute_property_atom.rst +++ b/doc/src/compute_property_atom.rst @@ -198,8 +198,8 @@ Related commands """""""""""""""" :doc:`dump custom `, :doc:`compute reduce `, -:doc:`fix ave/atom `, :doc:`fix ave/chunk` -:doc:``, `fix property/atom ` +:doc:`fix ave/atom `, :doc:`fix ave/chunk `, +:doc:`fix property/atom ` Default """""""