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

document ubuf union in developer guide

Browse Source
This commit is contained in:
Axel Kohlmeyer
2020-09-18 11:55:06 -04:00
parent 1264184e7b
commit edbfdde372
2 changed files with 37 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
doc/src/pg_dev_utils.rst
View File

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

33
src/lmptype.h
View File

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