ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update docs for new image features

Browse Source
This commit is contained in:
Steve Plimpton
2022-11-23 10:52:46 -07:00
parent 9ab4c65f31
commit dd8a14789b
3 changed files with 54 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
doc/src/Howto_grid.rst
View File

@ -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 <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
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 <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 <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
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 <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

8
src/utils.cpp
View File

@ -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,

23
src/utils.h
View File

@ -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