From edbfdde372ca0c95a209968dcb3075dab40d577b Mon Sep 17 00:00:00 2001
From: Axel Kohlmeyer <akohlmey@gmail.com>
Date: Fri, 18 Sep 2020 11:55:06 -0400
Subject: [PATCH] document ubuf union in developer guide

---
 doc/src/pg_dev_utils.rst | 21 +++++++++++++++++++++
 src/lmptype.h            | 33 ++++++++++++++++-----------------
 2 files changed, 37 insertions(+), 17 deletions(-)

diff --git a/doc/src/pg_dev_utils.rst b/doc/src/pg_dev_utils.rst
index 55217f17e0..4235e8e56c 100644
--- a/doc/src/pg_dev_utils.rst
+++ b/doc/src/pg_dev_utils.rst
@@ -171,6 +171,27 @@ Customized standard functions
 
 ---------------------------
 
+Communication buffer coding with *ubuf*
+=========================================
+
+LAMMPS uses communication buffers where it collects data from various
+class instances and then exchanges the data with neighboring subdomains.
+For simplicity those buffers are defined as ``double`` buffers and
+used for doubles and integer numbers. This presents a unique problem
+when 64-bit integers are used.  While the storage needed for a ``double``
+is also 64-bit, it cannot be used by a simple assignment.  To get around
+that limitation, LAMMPS uses the :cpp:union:`ubuf <LAMMPS_NS::ubuf>`
+union.  It is used in the various "pack" and "unpack" functions in the
+LAMMPS classes to store and retrieve integers that may be 64-bit from
+the communication buffers.
+
+---------------------------
+
+.. doxygenunion:: LAMMPS_NS::ubuf
+   :project: progguide
+
+---------------------------
+
 Tokenizer classes
 =================
 
diff --git a/src/lmptype.h b/src/lmptype.h
index e0e081dd12..e5fe9e180b 100644
--- a/src/lmptype.h
+++ b/src/lmptype.h
@@ -79,6 +79,7 @@ namespace LAMMPS_NS {
 
 // for atomic problems that exceed 2 billion (2^31) atoms
 // 32-bit smallint/imageint/tagint, 64-bit bigint
+// atom IDs and molecule IDs are limited to 32-bit
 
 #ifdef LAMMPS_SMALLBIG
 
@@ -171,22 +172,21 @@ typedef int bigint;
 
 #endif
 
-  /// Data structe for packing 32-bit and 64-bit integers
-  /// into double (communication) buffers
-  ///
-  /// Using this union avoids aliasing issues by having member types
-  /// (double, int) referencing the same buffer memory location.
-  ///
-  /// The explicit constructor for 32-bit integers prevents compilers
-  /// from (incorrectly) calling the double constructor when storing
-  ///  an int into a double buffer.
-  /*
+/** Data structure for packing 32-bit and 64-bit integers
+ * into double (communication) buffers
+ *
+ * Using this union avoids aliasing issues by having member types
+ * (double, int) referencing the same buffer memory location.
+ *
+ * The explicit constructor for 32-bit integers prevents compilers
+ * from (incorrectly) calling the double constructor when storing
+ * an int into a double buffer.
 \verbatim embed:rst
+
 **Usage:**
 
-To copy an integer into a double buffer:
-
-.. code-block: c++
+.. code-block:: c++
+   :caption: To copy an integer into a double buffer:
 
    double buf[2];
    int    foo =   1;
@@ -194,14 +194,13 @@ To copy an integer into a double buffer:
    buf[1] = ubuf(foo).d;
    buf[2] = ubuf(bar).d;
 
-To copy from a double buffer back to an int:
-
-.. code-block: c++
+.. code-block:: c++
+   :caption: To copy from a double buffer back to an int:
 
    foo = (int)    ubuf(buf[1]).i;
    bar = (tagint) ubuf(buf[2]).i;
 
-The typecast prevents compiler warnings about possible truncations.
+The typecasts prevent compiler warnings about possible truncations.
 \endverbatim
   */
   union ubuf {