From 2dd956043963e1632a4cc6ad5f704f40887dbcd1 Mon Sep 17 00:00:00 2001
From: Axel Kohlmeyer <akohlmey@gmail.com>
Date: Tue, 19 Mar 2024 22:39:05 -0400
Subject: [PATCH] add notes to python versions of lammps_extract_fix() that for
 global data one can only retrieve scalars

---
 python/lammps/core.py          | 26 +++++++++++++++++---------
 python/lammps/numpy_wrapper.py |  7 +++++++
 src/library.cpp                |  3 ++-
 3 files changed, 26 insertions(+), 10 deletions(-)

diff --git a/python/lammps/core.py b/python/lammps/core.py
index 28b384d6ba..3498041454 100644
--- a/python/lammps/core.py
+++ b/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`
-    function of the C-library interface.
-    This function returns ``None`` if either the fix id is not
-    recognized, or an invalid combination of :ref:`fstyle <py_style_constants>`
-    and :ref:`ftype <py_type_constants>` constants is used. The
-    names and functionality of the constants are the same as for
-    the corresponding C-library function.  For requests to return
-    a scalar or a size, the value is returned, also when accessing
-    global vectors or arrays, otherwise a pointer.
+    This is a wrapper around the :cpp:func:`lammps_extract_fix` function
+    of the C-library interface.  This function returns ``None`` if
+    either the fix id is not recognized, or an invalid combination of
+    :ref:`fstyle <py_style_constants>` and :ref:`ftype
+    <py_type_constants>` constants is used. The names and functionality
+    of the constants are the same as for the corresponding C-library
+    function.  For requests to return a scalar or a size, the value is
+    returned, also when accessing global vectors or arrays, otherwise a
+    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
diff --git a/python/lammps/numpy_wrapper.py b/python/lammps/numpy_wrapper.py
index a29853d16a..91042c43c8 100644
--- a/python/lammps/numpy_wrapper.py
+++ b/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`
diff --git a/src/library.cpp b/src/library.cpp
index a2eb1473a9..f81f52305e 100644
--- a/src/library.cpp
+++ b/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);