Update docs and docstrings

doc/src/pg_lib_properties.rst

@@ -84,11 +84,22 @@ event as atoms are migrating between sub-domains.
 
 -----------------------
 
+.. doxygenfunction:: lammps_extract_global_datatype
+   :project: progguide
+
+-----------------------
+
 .. doxygenfunction:: lammps_extract_global
    :project: progguide
 
 -----------------------
 
+.. doxygenfunction:: lammps_extract_atom_datatype
+   :project: progguide
+
+
+-----------------------
+
 .. doxygenfunction:: lammps_extract_atom
    :project: progguide
 

doc/src/pg_python.rst

@@ -359,6 +359,10 @@ The :py:mod:`lammps` module additionally contains several constants
 and the :py:class:`NeighList <lammps.NeighList>` class:
 
 .. _py_data_constants:
+
+Data Types
+----------
+
 .. py:data:: LAMMPS_INT, LAMMPS_INT_2D, LAMMPS_DOUBLE, LAMMPS_DOUBLE_2D, LAMMPS_INT64, LAMMPS_INT64_2D, LAMMPS_STRING
    :type: int
 
@@ -369,6 +373,10 @@ and the :py:class:`NeighList <lammps.NeighList>` class:
    C library interface.
 
 .. _py_style_constants:
+
+Style Constants
+---------------
+
 .. py:data:: LMP_STYLE_GLOBAL, LMP_STYLE_ATOM, LMP_STYLE_LOCAL
    :type: int
 
@@ -378,6 +386,10 @@ and the :py:class:`NeighList <lammps.NeighList>` class:
    :py:func:`lammps.extract_compute` and :py:func:`lammps.extract_fix`.
 
 .. _py_type_constants:
+
+Type Constants
+--------------
+
 .. py:data:: LMP_TYPE_SCALAR, LMP_TYLE_VECTOR, LMP_TYPE_ARRAY, LMP_SIZE_VECTOR, LMP_SIZE_ROWS, LMP_SIZE_COLS
    :type: int
 
@@ -387,12 +399,19 @@ and the :py:class:`NeighList <lammps.NeighList>` class:
    :py:func:`lammps.extract_compute` and :py:func:`lammps.extract_fix`.
 
 .. _py_var_constants:
+
+Variable Style Constants
+------------------------
+
 .. py:data:: LMP_VAR_EQUAL, LMP_VAR_ATOM
    :type: int
 
    Constants in the :py:mod:`lammps` module to select what style of
    variable to query when calling :py:func:`lammps.extract_variable`.
 
+Classes representing internal objects
+-------------------------------------
+
 .. autoclass:: lammps.NeighList
    :members:
    :no-undoc-members:

python/lammps.py

@@ -486,11 +486,12 @@ class lammps(object):
           function of the C-library interface. Its documentation includes a
           list of the supported keywords and their data types.
           Since Python needs to know the data type to be able to interpret
-          the result, by default, this function will try to auto-detect the datatype
+          the result, by default, this function will try to auto-detect the data 
-          by asking the library. You can also force a specific datatype.  For
+          type by asking the library. You can also force a specific data type.
-          that purpose the :py:mod:`lammps` module contains the constants
+          For that purpose the :py:mod:`lammps` module contains the constants
-          ``LAMMPS_INT``, ``LAMMPS_DOUBLE``, ``LAMMPS_BIGINT``,
+          ``LAMMPS_INT``, ``LAMMPS_INT_2D``, ``LAMMPS_DOUBLE``,
-          ``LAMMPS_TAGINT``, and ``LAMMPS_STRING``.
+          ``LAMMPS_DOUBLE_2D``, ``LAMMPS_INT64``, ``LAMMPS_INT64_2D``, and
+          ``LAMMPS_STRING``.
           This function returns ``None`` if either the keyword is not
           recognized, or an invalid data type constant is used.
 
@@ -505,7 +506,7 @@ class lammps(object):
 
           :param name: name of the property
           :type name:  string
-          :param dtype: type of the returned data
+          :param dtype: type of the returned data (see :ref:`py_data_constants`)
           :type dtype:  int, optional
           :param nelem: number of elements in array
           :type nelem:  int, optional
@@ -887,7 +888,8 @@ class lammps(object):
     recognized. Otherwise it will return a positive integer value that
     corresponds to one of the constants define in the :py:mod:`lammps` module:
     ``LAMMPS_INT``, ``LAMMPS_INT_2D``, ``LAMMPS_DOUBLE``, ``LAMMPS_DOUBLE_2D``,
-    ``LAMMPS_BIGINT``, ``LAMMPS_TAGINT``, ``LAMMPS_TAGINT2D``, and ``LAMMPS_STRING``.
+    ``LAMMPS_INT64``, ``LAMMPS_INT64_2D``, and ``LAMMPS_STRING``. These values
+    are equivalent to the ones defined in :cpp:enum:`_LMP_DATATYPE_CONST`.
 
     :param name: name of the property
     :type name:  string
@@ -914,16 +916,17 @@ class lammps(object):
     the result, by default, this function will try to auto-detect the data type
     by asking the library. You can also force a specific data type.  For that
     purpose the :py:mod:`lammps` module contains the constants ``LAMMPS_INT``,
-    ``LAMMPS_DOUBLE``, ``LAMMPS_INT64``, and ``LAMMPS_STRING``.
+    ``LAMMPS_DOUBLE``, ``LAMMPS_INT64``, and ``LAMMPS_STRING``. These values
+    are equivalent to the ones defined in :cpp:enum:`_LMP_DATATYPE_CONST`.
     This function returns ``None`` if either the keyword is not recognized,
     or an invalid data type constant is used.
 
     :param name: name of the property
     :type name:  string
-    :param dtype: type of the returned data
+    :param dtype: data type of the returned data (see :ref:`py_data_constants`)
     :type dtype:  int, optional
-    :return: value of the property
+    :return: value of the property or None
-    :rtype: integer or double or string or None
+    :rtype: int, float, or NoneType
     """
     if dtype == LAMMPS_AUTODETECT:
       dtype = self.extract_global_datatype(name)
@@ -933,19 +936,22 @@ class lammps(object):
 
     if dtype == LAMMPS_INT:
       self.lib.lammps_extract_global.restype = POINTER(c_int32)
-    elif dtype == LAMMPS_DOUBLE:
+      target_type = int
-      self.lib.lammps_extract_global.restype = POINTER(c_double)
     elif dtype == LAMMPS_INT64:
       self.lib.lammps_extract_global.restype = POINTER(c_int64)
+      target_type = int
+    elif dtype == LAMMPS_DOUBLE:
+      self.lib.lammps_extract_global.restype = POINTER(c_double)
+      target_type = float
     elif dtype == LAMMPS_STRING:
       self.lib.lammps_extract_global.restype = c_char_p
-      ptr = self.lib.lammps_extract_global(self.lmp, name)
+      target_type = lambda x: str(x, 'ascii')
-      return str(ptr,'ascii')
-    else: return None
 
     ptr = self.lib.lammps_extract_global(self.lmp, name)
-    if ptr: return ptr[0]
+    if ptr:
-    else: return None
+      return target_type(ptr[0])
+    return None
+
 
   # -------------------------------------------------------------------------
   # extract per-atom info datatype
@@ -957,14 +963,15 @@ class lammps(object):
     function of the C-library interface. Its documentation includes a
     list of the supported keywords.
     This function returns ``None`` if the keyword is not
-    recognized. Otherwise it will return a positive integer value that
+    recognized. Otherwise it will return an integer value that
     corresponds to one of the constants define in the :py:mod:`lammps` module:
     ``LAMMPS_INT``, ``LAMMPS_INT_2D``, ``LAMMPS_DOUBLE``, ``LAMMPS_DOUBLE_2D``,
-    ``LAMMPS_INT64``, ``LAMMPS_INT64_2D``, and ``LAMMPS_STRING``.
+    ``LAMMPS_INT64``, ``LAMMPS_INT64_2D``, and ``LAMMPS_STRING``. These values
+    are equivalent to the ones defined in :cpp:enum:`_LMP_DATATYPE_CONST`.
 
     :param name: name of the property
     :type name:  string
-    :return: datatype of per-atom property
+    :return: data type of per-atom property (see :ref:`py_data_constants`)
     :rtype: int
     """
     if name: name = name.encode()
@@ -985,7 +992,8 @@ class lammps(object):
     by asking the library. You can also force a specific data type.  For
     that purpose the :py:mod:`lammps` module contains the constants
     ``LAMMPS_INT``, ``LAMMPS_INT_2D``, ``LAMMPS_DOUBLE``, ``LAMMPS_DOUBLE_2D``,
-    ``LAMMPS_INT64``, ``LAMMPS_INT64_2D``, and ``LAMMPS_STRING``.
+    ``LAMMPS_INT64``, ``LAMMPS_INT64_2D``, and ``LAMMPS_STRING``. These values
+    are equivalent to the ones defined in :cpp:enum:`_LMP_DATATYPE_CONST`.
     This function returns ``None`` if either the keyword is not
     recognized, or an invalid data type constant is used.
 
@@ -1000,10 +1008,13 @@ class lammps(object):
 
     :param name: name of the property
     :type name:  string
-    :param dtype: type of the returned data
+    :param dtype: data type of the returned data (see :ref:`py_data_constants`)
     :type dtype:  int, optional
-    :return: requested data
+    :return: requested data or ``None``
-    :rtype: pointer to integer or double or None
+    :rtype: ctypes.POINTER(ctypes.c_int32), ctypes.POINTER(ctypes.POINTER(ctypes.c_int32)),
+            ctypes.POINTER(ctypes.c_int64), ctypes.POINTER(ctypes.POINTER(ctypes.c_int64)),
+            ctypes.POINTER(ctypes.c_double), ctypes.POINTER(ctypes.POINTER(ctypes.c_double)),
+            or NoneType
     """
     if dtype == LAMMPS_AUTODETECT:
       dtype = self.extract_atom_datatype(name)
@@ -1970,6 +1981,11 @@ class Atom(object):
 # -------------------------------------------------------------------------
 
 class Atom2D(Atom):
+  """
+  A wrapper class then represents a single 2D atom inside of LAMMPS
+
+  It provides access to properties of the atom and allows you to change some of them.
+  """
   def __init__(self, pylammps_instance, index):
     super(Atom2D, self).__init__(pylammps_instance, index)
 

src/library.cpp

@@ -1208,9 +1208,13 @@ void *lammps_extract_atom(void *handle, const char *name)
 
 /** Get data type of internal global LAMMPS variables or arrays.
  *
- * TODO
 \verbatim embed:rst
 
+This function returns an integer that encodes the data type of the global
+property with the specified name. See :cpp:enum:`_LMP_DATATYPE_CONST` for valid
+values. Callers of :cpp:func:`lammps_extract_global` can use this information
+to then decide how to cast the (void*) pointer and access the data.
+
 .. versionadded:: 18Sep2020
 
 \endverbatim
@@ -1218,7 +1222,7 @@ void *lammps_extract_atom(void *handle, const char *name)
  * \param  handle   pointer to a previously created LAMMPS instance
  * \param  name     string with the name of the extracted property
  * \return          integer constant encoding the data type of the property
-                    or -1 if not found. */
+ *                  or -1 if not found. */
 
 int lammps_extract_global_datatype(void *handle, const char *name)
 {
@@ -1288,9 +1292,13 @@ int lammps_extract_global_datatype(void *handle, const char *name)
 
 /** Get data type of a LAMMPS per-atom property
  *
- * TODO
 \verbatim embed:rst
 
+This function returns an integer that encodes the data type of the per-atom
+property with the specified name. See :cpp:enum:`_LMP_DATATYPE_CONST` for valid
+values. Callers of :cpp:func:`lammps_extract_atom` can use this information
+to then decide how to cast the (void*) pointer and access the data.
+
 .. versionadded:: 18Sep2020
 
 \endverbatim
@@ -1298,7 +1306,8 @@ int lammps_extract_global_datatype(void *handle, const char *name)
  * \param  handle  pointer to a previously created LAMMPS instance
  * \param  name    string with the name of the extracted property
  * \return         integer constant encoding the data type of the property
- *                 or -1 if not found. */
+ *                 or -1 if not found.
+ * */
 
 int lammps_extract_atom_datatype(void *handle, const char *name)
 {

src/library.h

@@ -45,13 +45,13 @@
  * Must be kept in sync with the equivalent constants in lammps.py */
 
 enum _LMP_DATATYPE_CONST {
-  LAMMPS_INT    = 0,
+  LAMMPS_INT    = 0,       /*!< 32-bit integer (array) */
-  LAMMPS_INT_2D  = 1,
+  LAMMPS_INT_2D  = 1,      /*!< two-dimensional 32-bit integer array */
-  LAMMPS_DOUBLE = 2,
+  LAMMPS_DOUBLE = 2,       /*!< 64-bit double (array) */
-  LAMMPS_DOUBLE_2D = 3,
+  LAMMPS_DOUBLE_2D = 3,    /*!< two-dimensional 64-bit double array */
-  LAMMPS_INT64 = 4,
+  LAMMPS_INT64 = 4,        /*!< 64-bit integer (array) */
-  LAMMPS_INT64_2D = 5,
+  LAMMPS_INT64_2D = 5,     /*!< two-dimensional 64-bit integer array */
-  LAMMPS_STRING = 6
+  LAMMPS_STRING = 6        /*!< C-String */
 };
 
 /** Style constants for extracting data from computes and fixes.