update docs for new image features

doc/src/Howto_grid.rst

@@ -5,14 +5,14 @@ LAMMPS has internal capabilities to create uniformly spaced grids
 which overlay the simulation domain.  For 2d and 3d simulations these
 are 2d and 3d grids respectively.  Conceptually a grid can be thought
 of as a collection of grid cells, each of which has an associated grid
-point.  Internally, the grid point can either be a corner point of the
+point.  Internally, the grid point is typically the center point of
-grid cell, or at its center.  Each grid cell (or point) stores one or
+the grid cell, though that is a coding option when using grids.  Each
-more values (data).
+grid cell stores one or more values (data).
 
 The grid points and data they store are distributed across processors.
-Each processor owns the grid points (and their data) that lie within
+Each processor owns the grid cells (and their data) whose grid points
-the spatial sub-domain of the processor.  If needed for its
+lie within the spatial sub-domain of the processor.  If needed for its
-computations, it may also store ghost grid points with data.
+computations, it may also store ghost grid cells with their data.
 
 These grids can overlay orthogonal or triclinic simulation boxes; see
 the :doc:`Howto triclinic <Howto_triclinic>` doc page for an
@@ -27,31 +27,42 @@ box size, i.e. as set by the :doc:`boundary <boundary>` command for
 fixed or shrink-wrapped boundaries.
 
 If load-balancing is invoked by the :doc:`balance <balance>` or
-:doc:`fix balance <fix_balance>` commands, then the sub-domain owned by
+:doc:`fix balance <fix_balance>` commands, then the sub-domain owned
-a processor will change which would also change which grid points they
+by a processor will change which may also change which grid points
-own.  Some of the commands listed below support that operation; others
+they own.
-do not.  Eventually we plan to have all commands which define and
+
-store per-grid data support load-balancing.
+Post-processing and visualization of per-grid data can be enabled by
+the :doc:`dump grid <dump>`, :doc:`dump grid/vtk <dump>`, and
+:doc:`dump image <dump_image>` commands, the latter by using its
+optional *grid* keyword.  The `OVITO visualization tool
+<https://www.ovito.org>`_ also plans (as of Nov 2022) to add support
+for visualizing per-grid data (along with atoms) using the :doc:`dump
+grid <dump>` output format.
 
 .. note::
 
    For developers, distributed grids are implemented within the code
    via two classes: Grid2d and Grid3d.  These partition the grid
    across processors and have methods which allow forward and reverse
-   communication of ghost grid data.  If you write a new compute or
+   communication of ghost grid data as well as load balancing.  If you
-   fix which needs a distributed grid, these are the classes to look
+   write a new compute or fix which needs a distributed grid, these
-   at.  A new pair style could use a distributed grid by having a fix
+   are the classes to look at.  A new pair style could use a
-   define it.
+   distributed grid by having a fix define it.  We plan (as of
+   Nov 2022) to add a section in the :doc:`Developer <Developer>`
+   section of the manual with a detailed description of how to use
+   these classes.
         
 ----------
 
 These are the commands which currently define or use distributed
 grids:
 
-* :doc:`fix ave/grid <fix_ave_grid>` - time average per-atom or per-grid values
 * :doc:`fix ttm/grid <fix_ttm>` - store electron temperature on grid
+* :doc:`fix ave/grid <fix_ave_grid>` - time average per-atom or per-grid values
 * :doc:`compute property/grid <compute_property_grid>` - generate grid IDs and coords
-* :doc:`dump grid <dump>` - output per-grid values
+* :doc:`dump grid <dump>` - output per-grid values in LAMMPS format
+* :doc:`dump grid/vtk <dump>` - output per-grid values in VTK format
+* :doc:`dump image grid <dump_image>` - include colored grid in output images
 * :doc:`kspace_style pppm <kspace_style>` (and variants) - FFT grids
 * :doc:`kspace_style msm <kspace_style>` (and variants) - MSM grids
 

src/utils.cpp

@@ -868,13 +868,15 @@ char *utils::expand_type(const char *file, int line, const std::string &str, int
    Check grid reference for valid Compute or Fix which produces per-grid data
    errstr = name of calling command used if error is generated
    ref = grid reference as it appears in an input script
+     e.g. c_myCompute:grid:data[2], ditto for a fix
+   nevery = frequency at which caller will access fix, not used if a compute
    return arguments:
      id = ID of compute or fix
-     igrid = index of which grid in compute/fix
+     igrid = index of which grid in compute/fix (0 to N-1)
-     idata = index of which data field in igrid
+     idata = index of which data field in igrid (0 to N-1)
      index = index into data field (0 for vector, 1-N for column of array)
    method return = ArgInfo::COMPUTE or ArgInfo::FIX or -1 for neither
-     caller decides what to do if not COMPUTE or FIX
+     caller decides what to do if arg is not a COMPUTE or FIX reference
 ------------------------------------------------------------------------- */
 
 int utils::check_grid_reference(char *errstr, char *ref, int nevery,

src/utils.h

@@ -379,14 +379,29 @@ namespace utils {
 
   char *expand_type(const char *file, int line, const std::string &str, int mode, LAMMPS *lmp);
 
-
+  /*! Check grid reference for valid Compute or Fix which produces per-grid data
-
+   *
-
+   *  This function checks if a command argument in the input script
+   *  is a valid reference to per-grid data produced by a Compute or Fix.
+   *  If it is, the ID of the compute/fix is returned which the caller must
+   *  free with delete [].  It also returns igrid/idata/index integers
+   *  which allow the caller to access the per-grid data.
+   *  A flag is also returned to indicate compute vs fix vs error.
+   *
+   * \param errstr  name of calling command, e.g. "Fix ave/grid"
+   * \param ref     per-grid reference from input script, e.g. "c_10:grid:data[2]"
+   * \param nevery  frequency at which caller will access fix for per-grid info,
+   *                ignored when reference is to a compute
+   * \param lmp     pointer to top-level LAMMPS class instance
+   * \return id     ID of Compute or Fix
+   * \return igrid  which grid is referenced (0 to N-1)
+   * \return idata  which data on grid is referenced (0 to N-1)
+   * \return index  which column of data is referenced (0 for vec, 1-N for array)
+   * \return        ArgINFO::COMPUTE or FIX or UNKNOWN or NONE */
 
   int check_grid_reference(char *errstr, char *ref, int nevery,
                            char *&id, int &igrid, int &idata, int &index, LAMMPS *lmp);
   
-  
   /*! Parse grid reference into 3 sub-strings
    *
    * Format of grid ID reference = id:gname:dname