[pull] develop from lammps:develop

doc/src/dump_image.rst

@@ -212,13 +212,13 @@ Examples
 Description
 """""""""""
 
-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 <dump_modify>` command control what is
-included in the image or movie and how it appears.  A series of such
-images can easily be manually converted into an animated movie of your
-simulation or the process can be automated without writing the
+Dump a high-quality rendered image of the atom configuration every
+:math:`N` timesteps and save the images either as a sequence of JPEG,
+PNG, TGA, or PPM files, or as a single movie file.  The options for this
+command as well as the :doc:`dump_modify <dump_modify>` command control
+what is included in the image or movie and how it appears.  A series of
+such images can easily be manually converted into an animated movie of
+your simulation or the process can be automated without writing the
 intermediate files using the dump movie style; see further details
 below.  Other dump styles store snapshots of numerical data associated
 with atoms in various formats, as discussed on the :doc:`dump <dump>`
@@ -251,23 +251,30 @@ Here are five sample images, rendered as JPEG or PNG files.
 A detailed discussion of advanced graphics settings and workflows
 with examples is provided in the :doc:`Howto_viz` howto.
 
+.. versionadded:: TBD
+
+   support for writing compressed TGA files
+
 Only atoms in the specified group are rendered in the image.  The
 :doc:`dump_modify region and thresh <dump_modify>` commands can also
 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
-<jpeg_format_>`_ file is created, if the suffix is ".png", then a `PNG
-format <png_format_>`_ is created, else a `PPM (aka NETPBM) format
-<ppm_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 compression, and PPM files are
-uncompressed but can be compressed with a supported compression program,
-if LAMMPS has been compiled with :ref:`compression support <gzip>` and a
-supported suffix is used.
+determines whether a JPEG, PNG, TGA, or PPM file is created with the
+*image* dump style.  If the suffix is ".jpg" or ".jpeg", then a `JPEG
+format <jpeg_format_>`_ file is created, if the suffix is ".png", then a
+`PNG format <png_format_>`_ file is created, if the suffix is ".tga",
+then a compressed 24-bit RGB `TGA or TARGA format <tga_format_>`_
+file is created, else a `PPM (aka NETPBM) format <ppm_format_>`_ file is
+created.  The JPEG, PNG, and TGA files are binary; PPM has a text mode
+header followed by binary data. JPEG images have lossy compression, PNG
+and TGA have lossless compression, and PPM files are uncompressed but can
+be compressed with a supported compression program, if LAMMPS has been
+compiled with :ref:`compression support <gzip>` and a supported suffix
+is used.
 
 .. _jpeg_format: https://jpeg.org/jpeg/
 .. _png_format: https://en.wikipedia.org/wiki/Portable_Network_Graphics
 .. _ppm_format: https://en.wikipedia.org/wiki/Netpbm
+.. _tga_format: https://en.wikipedia.org/wiki/Truevision_TGA
 
 Similarly, the format of the resulting movie is chosen with the *movie*
 dump style. This is handled by the underlying FFmpeg converter and thus

doc/src/fix_bond_react.rst

@@ -363,19 +363,19 @@ contain any atom within three bonds of reacting atoms.
 Some atoms in the pre-reacted template that are not reacting may have
 missing topology with respect to the simulation. For example, the
 pre-reacted template may contain an atom that, in the simulation, is
-currently connected to the rest of a long polymer chain. These are
-referred to as edge atoms, and are also specified in the map file. All
-pre-reaction template atoms should be linked to an initiator atom, via
-at least one path that does not involve edge atoms. When the
-pre-reaction template contains edge atoms, not all atoms, bonds, etc.
-specified in the reaction templates will be updated. Specifically, topology
-that involves only atoms that are "too near" to template edges will not be
-updated. The definition of "too near the edge" depends on which
-interactions are defined in the simulation. If the simulation has defined
-dihedrals, atoms within two bonds of edge atoms are considered "too near
-the edge." If the simulation defines angles, but not dihedrals, atoms
-within one bond of edge atoms are considered "too near the edge." If just
-bonds are defined, only edge atoms are considered "too near the edge."
+currently connected to the rest of a long polymer chain. These are referred
+to as edge atoms, and are specified in the map file in the EdgeIDs section.
+All pre-reaction template atoms should be linked to an initiator atom, via
+at least one path that does not involve edge atoms. When the pre-reaction
+template contains edge atoms, not all atoms, bonds, etc. specified in the
+reaction templates will be updated. Specifically, topology that involves
+only atoms that are "too near" to template edges will not be updated. The
+definition of "too near the edge" depends on which interactions are defined
+in the simulation. If the simulation has defined dihedrals, atoms within
+two bonds of edge atoms are considered "too near the edge." If the
+simulation defines angles, but not dihedrals, atoms within one bond of edge
+atoms are considered "too near the edge." If just bonds are defined, only
+edge atoms are considered "too near the edge."
 
 .. note::
 
@@ -392,6 +392,25 @@ command page. It is highly recommended to use :doc:`Type labels <Howto_type_labe
 files, which automates the process of syncing atom types between
 different input files.
 
+Wildcard atoms match to any atom type in the simulation.  Wildcard atoms
+can be used to reduce the number of reaction templates needed to model a
+set of similar reactions.  Wildcard atoms are specified in the Wildcards
+section of the map file.  The atom types of wildcard atoms in the
+simulation are not updated.  Any bond, angle, dihedral, or improper, that
+is defined in the reaction templates and contains a wildcard atom, will be
+updated by inferring its type from its constituent atom types.  To use
+wildcard atoms, a specific :doc:`type label <Howto_type_labels>` format is
+necessary to infer the types of higher-order interactions.  Bond, angle,
+dihedral, and improper type labels must contain their constituent atom
+types delimited by hyphens, e.g., ‘c2-c2-c2-n’ for a dihedral that contains
+three atoms of type 'c2' and one atom of 'n'.  Certain symmetries are
+considered to account for equivalent ways of writing higher-order
+interactions.  Type labels for bonds, angles, and dihedrals are assumed to
+be equivalent to those written in reverse order.  For example, an angle
+with type label 'c1-c2-n' is equivalent to 'n-c2-c1'.  Symmetries for
+impropers are more complex and are described on the doc page for each
+improper style in the 'Symmetry convention' section.
+
 The post-reacted molecule template contains a sample of the reaction
 site and its surrounding topology after the reaction has occurred. It
 must contain the same number of atoms as the pre-reacted template
@@ -422,12 +441,13 @@ mandatory keyword is *equivalences*\ :
 
    N *equivalences* = # of atoms N in the reaction molecule templates
 
-The optional keywords are *edgeIDs*\ , *deleteIDs*\ , *chiralIDs*\ , and
-*constraints*\ :
+The optional keywords are *edgeIDs*\ , *wildcards*\ ,*deleteIDs*\ ,
+*createIDs*\ , *chiralIDs*\ , and *constraints*\ :
 
 .. parsed-literal::
 
    N *edgeIDs* = # of edge atoms N in the pre-reacted molecule template
+   N *wildcards* = # of atoms with wildcard atom types N
    N *deleteIDs* = # of atoms N that are deleted
    N *createIDs* = # of atoms N that are created
    N *chiralIDs* = # of chiral centers N
@@ -443,16 +463,17 @@ templates. The first column is an atom ID of the pre-reacted molecule
 template, and the second column is the corresponding atom ID of the
 post-reacted molecule template. The first optional section begins with
 the keyword "EdgeIDs" and lists the atom IDs of edge atoms in the
-pre-reacted molecule template. The second optional section begins with
-the keyword "DeleteIDs" and lists the atom IDs of pre-reaction
-template atoms to delete. The third optional section begins with the
-keyword "CreateIDs" and lists the atom IDs of the post-reaction
-template atoms to create. The fourth optional section begins with the
-keyword "ChiralIDs" lists the atom IDs of chiral atoms whose
-handedness should be enforced. The fifth optional section begins with
-the keyword "Constraints" and lists additional criteria that must be
-satisfied in order for the reaction to occur. Currently, there are
-six types of constraints available, as discussed below: "distance",
+pre-reacted molecule template.  The second optional section begins with
+the keyword "Wildcards" and lists the pre-reaction atom IDs of atoms that
+have wildcard atom types.  The third optional section begins with the
+keyword "DeleteIDs" and lists the atom IDs of pre-reaction template atoms
+to delete. The fourth optional section begins with the keyword "CreateIDs"
+and lists the atom IDs of the post-reaction template atoms to create. The
+fifth optional section begins with the keyword "ChiralIDs" lists the atom
+IDs of chiral atoms whose handedness should be enforced. The sixth optional
+section begins with the keyword "Constraints" and lists additional criteria
+that must be satisfied in order for the reaction to occur. Currently, there
+are six types of constraints available, as discussed below: "distance",
 "angle", "dihedral", "arrhenius", "rmsd", and "custom".
 
 A sample map file is given below:

doc/src/improper_amoeba.rst

@@ -41,7 +41,7 @@ information about the implementation of AMOEBA and HIPPO in LAMMPS.
 If the 4 atoms in an improper quadruplet (listed in the data file read
 by the :doc:`read_data <read_data>` command are ordered I,J,K,L then
 atoms I,K,L are considered to lie in a plane and atom J is
-out-of-place.  The angle :math:`\chi_0` is computed as the Allinger
+out-of-plane.  The angle :math:`\chi_0` is computed as the Allinger
 angle which is defined as the angle between the plane of I,K,L, and
 the vector from atom I to atom J.
 
@@ -58,6 +58,15 @@ Note that the angle :math:`\chi` is computed in radians; hence
 
 ----------
 
+Symmetry convention
+"""""""""""""""""""
+
+For the *amoeba* improper style, the second atom in the quadruplet is the
+atom of symmetry; all other atoms are considered interchangeable.  This
+convention is relevant for operations that require knowledge of how atoms
+are ordered, such as automatic assignment of new improper types by
+:doc:`fix bond/react <fix_bond_react>`.
+
 Restrictions
 """"""""""""
 

doc/src/improper_class2.rst

@@ -104,6 +104,15 @@ converts them to radians internally; hence the hence the various
 
 ----------
 
+Symmetry convention
+"""""""""""""""""""
+
+For the *class2* improper style, the second atom in the quadruplet is the
+atom of symmetry; all other atoms are considered interchangeable.  This
+convention is relevant for operations that require knowledge of how atoms
+are ordered, such as automatic assignment of new improper types by
+:doc:`fix bond/react <fix_bond_react>`.
+
 Restrictions
 """"""""""""
 

doc/src/improper_cossq.rst

@@ -60,6 +60,15 @@ commands:
 
 ----------
 
+Symmetry convention
+"""""""""""""""""""
+
+For the *cossq* improper style, the first atom in the quadruplet is the
+atom of symmetry; all other atoms are considered interchangeable.  This
+convention is relevant for operations that require knowledge of how atoms
+are ordered, such as automatic assignment of new improper types by
+:doc:`fix bond/react <fix_bond_react>`.
+
 Restrictions
 """"""""""""
 

doc/src/improper_cvff.rst

@@ -62,6 +62,15 @@ commands:
 
 ----------
 
+Symmetry convention
+"""""""""""""""""""
+
+For the *cvff* improper style, the first atom in the quadruplet is the
+atom of symmetry; all other atoms are considered interchangeable.  This
+convention is relevant for operations that require knowledge of how atoms
+are ordered, such as automatic assignment of new improper types by
+:doc:`fix bond/react <fix_bond_react>`.
+
 Restrictions
 """"""""""""
 

doc/src/improper_distance.rst

@@ -50,6 +50,15 @@ file or restart files read by the read_data or read_restart commands:
 
 ----------
 
+Symmetry convention
+"""""""""""""""""""
+
+For the *distance* improper style, the first atom in the quadruplet is the
+atom of symmetry; all other atoms are considered interchangeable.  This
+convention is relevant for operations that require knowledge of how atoms
+are ordered, such as automatic assignment of new improper types by
+:doc:`fix bond/react <fix_bond_react>`.
+
 Restrictions
 """"""""""""
 

doc/src/improper_distharm.rst

@@ -44,6 +44,15 @@ file or restart files read by the read_data or read_restart commands:
 
 ----------
 
+Symmetry convention
+"""""""""""""""""""
+
+For the *distharm* improper style, the fourth atom in the quadruplet is the
+atom of symmetry; all other atoms are considered interchangeable.  This
+convention is relevant for operations that require knowledge of how atoms
+are ordered, such as automatic assignment of new improper types by
+:doc:`fix bond/react <fix_bond_react>`.
+
 Restrictions
 """"""""""""
 

doc/src/improper_fourier.rst

@@ -56,6 +56,15 @@ commands:
 
 ----------
 
+Symmetry convention
+"""""""""""""""""""
+
+For the *fourier* improper style, the first and fourth atoms in the
+quadruplet are atoms of symmetry; only the second and third atoms are
+considered interchangeable.  This convention is relevant for operations
+that require knowledge of how atoms are ordered, such as automatic
+assignment of new improper types by :doc:`fix bond/react <fix_bond_react>`.
+
 Restrictions
 """"""""""""
 

doc/src/improper_harmonic.rst

@@ -68,6 +68,15 @@ radian\^2.
 
 ----------
 
+Symmetry convention
+"""""""""""""""""""
+
+For the *harmonic* improper style, the first atom in the quadruplet is the
+atom of symmetry; all other atoms are considered interchangeable.  This
+convention is relevant for operations that require knowledge of how atoms
+are ordered, such as automatic assignment of new improper types by
+:doc:`fix bond/react <fix_bond_react>`.
+
 Restrictions
 """"""""""""
 

doc/src/improper_inversion_harmonic.rst

@@ -54,6 +54,15 @@ with a barrier in between.
 
 ----------
 
+Symmetry convention
+"""""""""""""""""""
+
+For the *inversion/harmonic* improper style, the first atom in the
+quadruplet is the atom of symmetry; all other atoms are considered
+interchangeable.  This convention is relevant for operations that require
+knowledge of how atoms are ordered, such as automatic assignment of new
+improper types by :doc:`fix bond/react <fix_bond_react>`.
+
 Restrictions
 """"""""""""
 

doc/src/improper_ring.rst

@@ -68,6 +68,15 @@ commands:
 
 ----------
 
+Symmetry convention
+"""""""""""""""""""
+
+For the *ring* improper style, the second atom in the quadruplet is the
+atom of symmetry; all other atoms are considered interchangeable.  This
+convention is relevant for operations that require knowledge of how atoms
+are ordered, such as automatic assignment of new improper types by
+:doc:`fix bond/react <fix_bond_react>`.
+
 Restrictions
 """"""""""""
 

doc/src/improper_sqdistharm.rst

@@ -45,6 +45,15 @@ Note that :math:`{d_0}^2` (in units distance\^2) has be provided and not :math:`
 
 ----------
 
+Symmetry convention
+"""""""""""""""""""
+
+For the *sqdistharm* improper style, the fourth atom in the quadruplet is the
+atom of symmetry; all other atoms are considered interchangeable.  This
+convention is relevant for operations that require knowledge of how atoms
+are ordered, such as automatic assignment of new improper types by
+:doc:`fix bond/react <fix_bond_react>`.
+
 Restrictions
 """"""""""""
 

doc/src/improper_umbrella.rst

@@ -60,6 +60,15 @@ commands:
 
 ----------
 
+Symmetry convention
+"""""""""""""""""""
+
+For the *umbrella* improper style, the first and fourth atoms in the
+quadruplet are atoms of symmetry; only the second and third atoms are
+considered interchangeable.  This convention is relevant for operations
+that require knowledge of how atoms are ordered, such as automatic
+assignment of new improper types by :doc:`fix bond/react <fix_bond_react>`.
+
 Restrictions
 """"""""""""
 

doc/utils/sphinx-config/false_positives.txt

@@ -3883,6 +3883,7 @@ textrm
 tfac
 tfmc
 tfMC
+tga
 tgnpt
 tgnvt
 th

examples/GRAPHICS/.gitignore

@@ -0,0 +1,10 @@
+*.png
+*.tga
+*.ppm
+*.mp4
+*.mkv
+*.avi
+*.mpg
+*.mpeg
+*.jpg
+*.jpeg

examples/GRAPHICS/README

@@ -10,5 +10,6 @@ automatically as they are created.
 
 Here is a list of the inputs and which graphics features they demonstrate
 
-- in.cubes-and-pyramids:    visualization of body particles
+- in.cubes-and-pyramids:    visualization of body particles, uses progress bar
 - in.breakable:             using autobond, color-by-property, adding objects and text
+- in.water-arrows:          box of water molecules, uses many kinds of arrows