diff --git a/doc/src/Howto_grid.rst b/doc/src/Howto_grid.rst index efc19a2cb4..3b7e503f18 100644 --- a/doc/src/Howto_grid.rst +++ b/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 -grid cell, or at its center. Each grid cell (or point) stores one or -more values (data). +point. Internally, the grid point is typically the center point of +the grid cell, though that is a coding option when using grids. Each +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 -the spatial sub-domain of the processor. If needed for its -computations, it may also store ghost grid points with data. +Each processor owns the grid cells (and their data) whose grid points +lie within the spatial sub-domain of the processor. If needed for its +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 ` doc page for an @@ -27,31 +27,42 @@ box size, i.e. as set by the :doc:`boundary ` command for fixed or shrink-wrapped boundaries. If load-balancing is invoked by the :doc:`balance ` or -:doc:`fix balance ` commands, then the sub-domain owned by -a processor will change which would also change which grid points they -own. Some of the commands listed below support that operation; others -do not. Eventually we plan to have all commands which define and -store per-grid data support load-balancing. +:doc:`fix balance ` commands, then the sub-domain owned +by a processor will change which may also change which grid points +they own. + +Post-processing and visualization of per-grid data can be enabled by +the :doc:`dump grid `, :doc:`dump grid/vtk `, and +:doc:`dump image ` commands, the latter by using its +optional *grid* keyword. The `OVITO visualization tool +`_ also plans (as of Nov 2022) to add support +for visualizing per-grid data (along with atoms) using the :doc:`dump +grid ` 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 - fix which needs a distributed grid, these are the classes to look - at. A new pair style could use a distributed grid by having a fix - define it. - + communication of ghost grid data as well as load balancing. If you + write a new compute or fix which needs a distributed grid, these + are the classes to look at. A new pair style could use a + distributed grid by having a fix define it. We plan (as of + Nov 2022) to add a section in the :doc:`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 ` - time average per-atom or per-grid values * :doc:`fix ttm/grid ` - store electron temperature on grid +* :doc:`fix ave/grid ` - time average per-atom or per-grid values * :doc:`compute property/grid ` - generate grid IDs and coords -* :doc:`dump grid ` - output per-grid values +* :doc:`dump grid ` - output per-grid values in LAMMPS format +* :doc:`dump grid/vtk ` - output per-grid values in VTK format +* :doc:`dump image grid ` - include colored grid in output images * :doc:`kspace_style pppm ` (and variants) - FFT grids * :doc:`kspace_style msm ` (and variants) - MSM grids diff --git a/src/utils.cpp b/src/utils.cpp index defe6f3a49..841877859a 100644 --- a/src/utils.cpp +++ b/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 - idata = index of which data field in igrid + igrid = index of which grid in compute/fix (0 to N-1) + 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, diff --git a/src/utils.h b/src/utils.h index 0f0fcb323e..b88c93f463 100644 --- a/src/utils.h +++ b/src/utils.h @@ -379,13 +379,28 @@ 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); - + char *&id, int &igrid, int &idata, int &index, LAMMPS *lmp); /*! Parse grid reference into 3 sub-strings *