add python interface with optional numpy support for lammps_gather_bonds()

unit tests are included

python/lammps/core.py

@@ -201,6 +201,9 @@ class lammps(object):
       [c_void_p,c_char_p,c_int,c_int,c_int,POINTER(c_int),c_void_p]
     self.lib.lammps_scatter_atoms_subset.restype = None
 
+    self.lib.lammps_gather_bonds.argtypes = [c_void_p,c_void_p]
+    self.lib.lammps_gather_bonds.restype = None
+
     self.lib.lammps_gather.argtypes = \
       [c_void_p,c_char_p,c_int,c_int,c_void_p]
     self.lib.lammps_gather.restype = None
@@ -1206,6 +1209,32 @@ class lammps(object):
     with ExceptionCheck(self):
       self.lib.lammps_scatter_atoms_subset(self.lmp,name,dtype,count,ndata,ids,data)
 
+
+  # -------------------------------------------------------------------------
+
+  def gather_bonds(self):
+    """Retrieve global list of bonds
+
+    This is a wrapper around the :cpp:func:`lammps_gather_bonds`
+    function of the C-library interface.
+
+    This function returns a tuple with the number of bonds and a
+    flat list of ctypes integer values with the bond type, bond atom1,
+    bond atom2 for each bond.
+
+    .. versionadded:: 28Jul2021
+
+    :return: a tuple with the number of bonds and a list of c_int or c_long
+    :rtype: (int, 3*nbonds*c_tagint)
+    """
+    nbonds = self.extract_global("nbonds")
+    with ExceptionCheck(self):
+        data = ((3*nbonds)*self.c_tagint)()
+        self.lib.lammps_gather_bonds(self.lmp,data)
+        return nbonds,data
+
+  # -------------------------------------------------------------------------
+
   # return vector of atom/compute/fix properties gathered across procs
   # 3 variants to match src/library.cpp
   # name = atom property recognized by LAMMPS in atom->extract()

python/lammps/numpy_wrapper.py

@@ -248,6 +248,24 @@ class numpy_wrapper:
 
     # -------------------------------------------------------------------------
 
+  def gather_bonds(self):
+    """Retrieve global list of bonds as NumPy array
+
+    This is a wrapper around :py:meth:`lammps.gather_bonds() <lammps.lammps.gather_bonds()>`
+    It behaves the same as the original method, but returns a NumPy array instead
+    of a ``ctypes`` list.
+
+    .. versionadded:: 28Jul2021
+
+    :return: the requested data as a 2d-integer numpy array
+    :rtype: numpy.array(nbonds,3)
+    """
+    import numpy as np
+    nbonds, value = self.lmp.gather_bonds()
+    return np.ctypeslib.as_array(value).reshape(nbonds,3)
+
+    # -------------------------------------------------------------------------
+
   def fix_external_get_force(self, fix_id):
     """Get access to the array with per-atom forces of a fix external instance with a given fix ID.