add note about porting legacy code to the new Grid3d/Grid2d classes

doc/src/Developer_updating.rst

@@ -25,6 +25,7 @@ Available topics in mostly chronological order are:
 - `Simplified and more compact neighbor list requests`_
 - `Split of fix STORE into fix STORE/GLOBAL and fix STORE/PERATOM`_
 - `Use Output::get_dump_by_id() instead of Output::find_dump()`_
+- `Refactored grid communication using Grid3d/Grid2d classes instead of GridComm`_
 
 ----
 
@@ -423,3 +424,56 @@ New:
    if (dumpflag) for (auto idump : dumplist) idump->write();
 
 This change is **required** or else the code will not compile.
+
+Refactored grid communication using Grid3d/Grid2d classes instead of GridComm
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 22Dec2022
+
+The ``GridComm`` class was for creating and communicating distributed
+grids was replaced by the ``Grid3d`` class with added functionality.
+A ``Grid2d`` class was also added for additional flexibility.
+
+The new functionality and commands using the two grid classes are
+discussed on the following documentation pages:
+
+- :doc:`Howto_grid`
+- :doc:`Developer_grid`
+
+If you have custom LAMMPS code, which uses the GridComm class, here are some notes
+on how to adapt it for using the Grid3d class.
+
+(1) The constructor has changed to allow the ``Grid3d`` / ``Grid2d``
+    classes to partition the global grid across processors, both for
+    owned and ghost grid cells.  Previously any class which called
+    ``GridComm`` performed the partitioning itself and that information
+    was passed in the ``GridComm::GridComm()`` constructor.  There are
+    several "set" functions which can be called to alter how ``Grid3d``
+    / ``Grid2d`` perform the partitioning.  They should be sufficient
+    for most use cases of the grid classes.
+
+(2) The partitioning is triggered by the ``setup_grid()`` method.
+
+(3) The ``setup()`` method of the ``GridComm`` class has been replaced
+    by the ``setup_comm()`` method in the new grid classes.  The syntax
+    for the ``forward_comm()`` and ``reverse_comm()`` methods is
+    slightly altered as is the syntax of the associated pack/unpack
+    callback methods.  But the functionality of these operations is the
+    same as before.
+
+(4) The new ``Grid3d`` / ``Grid2d`` classes have additional
+    functionality for dynamic load-balancing of grids and their
+    associated data across processors.  This did not exist in the
+    ``GridComm`` class.
+
+This and more is explained in detail on the :doc:`Developer_grid` page.
+The following LAMMPS source files can be used as illustrative examples
+for how the new grid classes are used by computes, fixes, and various
+KSpace solvers which use distributed FFT grids:
+
+- ``src/fix_ave_grid.cpp``
+- ``src/compute_property_grid.cpp``
+- ``src/EXTRA-FIX/fix_ttm_grid.cpp``
+- ``src/KSPACE/pppm.cpp``
+
+This change is **required** or else the code will not compile.

doc/src/Howto_grid.rst

@@ -1,5 +1,5 @@
-Distributed grids
-=================
+Using distributed grids
+=======================
 
 .. versionadded:: TBD