add notes to python versions of lammps_extract_fix() that for global data one can only retrieve scalars

python/lammps/core.py

@@ -1078,15 +1078,23 @@ class lammps(object):
   def extract_fix(self,fid,fstyle,ftype,nrow=0,ncol=0):
     """Retrieve data from a LAMMPS fix
 
-    This is a wrapper around the :cpp:func:`lammps_extract_fix`
+    This is a wrapper around the :cpp:func:`lammps_extract_fix` function
-    function of the C-library interface.
+    of the C-library interface.  This function returns ``None`` if
-    This function returns ``None`` if either the fix id is not
+    either the fix id is not recognized, or an invalid combination of
-    recognized, or an invalid combination of :ref:`fstyle <py_style_constants>`
+    :ref:`fstyle <py_style_constants>` and :ref:`ftype
-    and :ref:`ftype <py_type_constants>` constants is used. The
+    <py_type_constants>` constants is used. The names and functionality
-    names and functionality of the constants are the same as for
+    of the constants are the same as for the corresponding C-library
-    the corresponding C-library function.  For requests to return
+    function.  For requests to return a scalar or a size, the value is
-    a scalar or a size, the value is returned, also when accessing
+    returned, also when accessing global vectors or arrays, otherwise a
-    global vectors or arrays, otherwise a pointer.
+    pointer.
+
+    .. note::
+
+       When requesting global data, the fix data can only be accessed
+       one item at a time without access to the whole vector or array.
+       Thus this function will always return a scalar.  To access vector
+       or array elements the "nrow" and "ncol" arguments need to be set
+       accordingly (they default to 0).
 
     :param fid: fix ID
     :type fid:  string

python/lammps/numpy_wrapper.py

@@ -203,6 +203,13 @@ class numpy_wrapper:
     It behaves the same as the original method, but returns NumPy arrays
     instead of ``ctypes`` pointers.
 
+    .. note::
+
+       When requesting global data, the fix data can only be accessed one
+       item at a time without access to the whole vector or array.  Thus this
+       function will always return a scalar.  To access vector or array elements
+       the "nrow" and "ncol" arguments need to be set accordingly (they default to 0).
+
     :param fid: fix ID
     :type fid:  string
     :param fstyle: style of the data retrieve (global, atom, or local), see :ref:`py_style_constants`

src/library.cpp

@@ -2137,7 +2137,8 @@ available.
 
    .. code-block:: c
 
-      double *dptr = (double *) lammps_extract_fix(handle,name,0,1,0,0);
+      double *dptr = (double *) lammps_extract_fix(handle, name,
+                                LMP_STYLE_GLOBAL, LMP_TYPE_VECTOR, 0, 0);
       double value = *dptr;
       lammps_free((void *)dptr);