Wrote documentation for extract_fix, extract_variable

doc/src/Fortran.rst

@@ -10,7 +10,7 @@ written in C, C++, or Fortran.
 While C libraries have a defined binary interface (ABI) and can thus be
 used from multiple compiler versions from different vendors for as long
 as they are compatible with the hosting operating system, the same is
-not true for Fortran codes.  Thus the LAMMPS Fortran module needs to be
+not true for Fortran programs.  Thus, the LAMMPS Fortran module needs to be
 compiled alongside the code using it from the source code in
 ``fortran/lammps.f90``.  When linking, you also need to
 :doc:`link to the LAMMPS library <Build_link>`.  A typical command line
@@ -20,19 +20,19 @@ for a simple program using the Fortran interface would be:
 
    mpifort -o testlib.x lammps.f90 testlib.f90 -L. -llammps
 
-Please note, that the MPI compiler wrapper is only required when the
+Please note that the MPI compiler wrapper is only required when the
-calling the library from an MPI parallel code.  Otherwise, using the
+calling the library from an MPI-parallelized program.  Otherwise, using the
 fortran compiler (gfortran, ifort, flang, etc.) will suffice.  It may be
-necessary to link to additional libraries depending on how LAMMPS was
+necessary to link to additional libraries, depending on how LAMMPS was
 configured and whether the LAMMPS library :doc:`was compiled as a static
-or shared library <Build_link>`.
+or dynamic library <Build_link>`.
 
 If the LAMMPS library itself has been compiled with MPI support, the
 resulting executable will still be able to run LAMMPS in parallel with
-``mpirun`` or equivalent.  Please also note that the order of the source
+``mpiexec`` or equivalent.  Please also note that the order of the source
 files matters: the ``lammps.f90`` file needs to be compiled first, since
 it provides the ``LIBLAMMPS`` module that is imported by the Fortran
-code using the interface.  A working example code can be found together
+code that uses the interface.  A working example can be found together
 with equivalent examples in C and C++ in the ``examples/COUPLE/simple``
 folder of the LAMMPS distribution.
 
@@ -62,15 +62,15 @@ Creating or deleting a LAMMPS object
 With the Fortran interface, the creation of a :cpp:class:`LAMMPS
 <LAMMPS_NS::LAMMPS>` instance is included in the constructor for
 creating the :f:func:`lammps` derived type.  To import the definition of
-that type and its type bound procedures, you need to add a ``USE
+that type and its type-bound procedures, you need to add a ``USE
-LIBLAMMPS`` statement.  Internally it will call either
+LIBLAMMPS`` statement.  Internally, it will call either
 :cpp:func:`lammps_open_fortran` or :cpp:func:`lammps_open_no_mpi` from
 the C library API to create the class instance.  All arguments are
-optional and :cpp:func:`lammps_mpi_init` will be called automatically,
+optional and :cpp:func:`lammps_mpi_init` will be called automatically
 if it is needed.  Similarly, a possible call to
 :cpp:func:`lammps_mpi_finalize` is integrated into the :f:func:`close`
 function and triggered with the optional logical argument set to
-``.true.``. Here is a simple example:
+``.TRUE.``. Here is a simple example:
 
 .. code-block:: fortran
 
@@ -78,15 +78,15 @@ function and triggered with the optional logical argument set to
      USE LIBLAMMPS                 ! include the LAMMPS library interface
      IMPLICIT NONE
      TYPE(lammps) :: lmp           ! derived type to hold LAMMPS instance
-     CHARACTER(len=*), PARAMETER :: args(3) = &
+     CHARACTER(LEN=*), PARAMETER :: args(3) = &
-         [ CHARACTER(len=12) :: 'liblammps', '-log', 'none' ]
+         [ CHARACTER(LEN=12) :: 'liblammps', '-log', 'none' ]
 
      ! create a LAMMPS instance (and initialize MPI)
      lmp = lammps(args)
      ! get and print numerical version code
      PRINT*, 'LAMMPS Version: ', lmp%version()
-     ! delete LAMMPS instance (and shuts down MPI)
+     ! delete LAMMPS instance (and shutdown MPI)
-     CALL lmp%close(.true.)
+     CALL lmp%close(.TRUE.)
    END PROGRAM testlib
 
 It is also possible to pass command line flags from Fortran to C/C++ and
@@ -103,7 +103,7 @@ version of the previous example:
      USE LIBLAMMPS                 ! include the LAMMPS library interface
      IMPLICIT NONE
      TYPE(lammps) :: lmp           ! derived type to hold LAMMPS instance
-     CHARACTER(len=128), ALLOCATABLE :: command_args(:)
+     CHARACTER(LEN=128), ALLOCATABLE :: command_args(:)
      INTEGER :: i, argc
 
      ! copy command line flags to `command_args()`
@@ -131,9 +131,9 @@ Executing LAMMPS commands
 Once a LAMMPS instance is created, it is possible to "drive" the LAMMPS
 simulation by telling LAMMPS to read commands from a file or to pass
 individual or multiple commands from strings or lists of strings.  This
-is done similarly to how it is implemented in the :doc:`C-library
+is done similarly to how it is implemented in the :doc:`C library
 interface <Library_execute>`. Before handing off the calls to the
-C-library interface, the corresponding Fortran versions of the calls
+C library interface, the corresponding Fortran versions of the calls
 (:f:func:`file`, :f:func:`command`, :f:func:`commands_list`, and
 :f:func:`commands_string`) have to make a copy of the strings passed as
 arguments so that they can be modified to be compatible with the
@@ -176,13 +176,13 @@ Below is a small demonstration of the uses of the different functions:
 Accessing system properties
 ***************************
 
-The C-library interface allows the :doc:`extraction of different kinds
+The C library interface allows the :doc:`extraction of different kinds
 of information <Library_properties>` about the active simulation
-instance and also - in some cases - to apply modifications to it.  In
+instance and also---in some cases---to apply modifications to it.  In
-some cases, the C-library interface makes pointers to internal data
+some cases, the C library interface makes pointers to internal data
-structures accessible, thus when accessing them from Fortran, special
+structures accessible; when accessing them through the library interfaces, 
-care is needed to avoid data corruption and crashes.  Thus please see
+special care is needed to avoid data corruption and crashes.  Please see
-the documentation of the individual type bound procedures for details.
+the documentation of the individual type-bound procedures for details.
 
 Below is an example demonstrating some of the possible uses.
 
@@ -191,35 +191,36 @@ Below is an example demonstrating some of the possible uses.
   PROGRAM testprop
     USE LIBLAMMPS
     USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_double, c_int64_t
+    USE, INTRINSIC :: ISO_FORTRAN_ENV, ONLY : OUTPUT_UNIT
     TYPE(lammps) :: lmp
-    INTEGER(kind=8)  :: natoms
+    INTEGER(KIND=c_int64_t) :: natoms
-    REAL(c_double), POINTER :: dt
+    REAL(KIND=c_double), POINTER :: dt
-    INTEGER(c_int64_t), POINTER :: ntimestep
+    INTEGER(KIND=c_int64_t), POINTER :: ntimestep
-    REAL(kind=8) :: pe, ke
+    REAL(KIND=c_double) :: pe, ke
 
     lmp = lammps()
     CALL lmp%file('in.sysinit')
-    natoms = INT(lmp%get_natoms(),8)
+    natoms = lmp%extract_setting('natoms')
-    WRITE(6,'(A,I8,A)') 'Running a simulation with', natoms, ' atoms'
+    WRITE(OUTPUT_UNIT,'(A,I8,A)') 'Running a simulation with', natoms, ' atoms'
-    WRITE(6,'(I8,A,I8,A,I3,A)') lmp%extract_setting('nlocal'), ' local and', &
+    WRITE(OUTPUT_UNIT,'(I8,A,I8,A,I3,A)') lmp%extract_setting('nlocal'), &
-        lmp%extract_setting('nghost'), ' ghost atom. ',                      &
+        ' local and', lmp%extract_setting('nghost'), ' ghost atom. ', &
         lmp%extract_setting('ntypes'), ' atom types'
 
     CALL lmp%command('run 2 post no')
     dt = lmp%extract_global('dt')
     ntimestep = lmp%extract_global('ntimestep')
-    WRITE(6,'(A,I4,A,F4.1,A)') 'At step:', ntimestep, '  Changing timestep from', dt, ' to 0.5'
+    WRITE(OUTPUT_UNIT,'(A,I4,A,F4.1,A)') 'At step:', ntimestep, &
-    dt = 0.5
+        '  Changing timestep from', dt, ' to 0.5'
+    dt = 0.5_c_double
     CALL lmp%command('run 2 post no')
 
-    WRITE(6,'(A,I4)') 'At step:', ntimestep
+    WRITE(OUTPUT_UNIT,'(A,I0)') 'At step:', ntimestep
     pe = lmp%get_thermo('pe')
     ke = lmp%get_thermo('ke')
     PRINT*, 'PE = ', pe
     PRINT*, 'KE = ', ke
 
     CALL lmp%close(.TRUE.)
-
   END PROGRAM testprop
 
 ---------------
@@ -237,6 +238,8 @@ of the contents of the ``LIBLAMMPS`` Fortran interface to LAMMPS.
    class instance that any of the included calls are forwarded to.
 
    :f c_ptr handle: reference to the LAMMPS class
+   :f type(lammps_style) style: derived type to access lammps style constants
+   :f type(lammps_type) type: derived type to access lammps type constants
    :f subroutine close: :f:func:`close`
    :f subroutine error: :f:func:`error`
    :f subroutine file: :f:func:`file`
@@ -248,10 +251,18 @@ of the contents of the ``LIBLAMMPS`` Fortran interface to LAMMPS.
    :f subroutine extract_box: :f:func:`extract_box`
    :f subroutine reset_box: :f:func:`reset_box`
    :f subroutine memory_usage: :f:func:`memory_usage`
+   :f function get_mpi_comm: :f:func:`get_mpi_comm`
    :f function extract_setting: :f:func:`extract_setting`
    :f function extract_global: :f:func:`extract_global`
+   :f function extract_atom: :f:func:`extract_atom`
+   :f function extract_compute: :f:func:`extract_compute`
+   :f function extract_fix: :f:func:`extract_fix`
+   :f function extract_variable: :f:func:`extract_variable`
    :f function version: :f:func:`version`
+   :f subroutine flush_buffers: :f:func:`flush_buffers`
    :f function is_running: :f:func:`is_running`
+   :f function has_error: :f:func:`has_error`
+   :f subroutine get_last_error_message: :f:func:`get_last_error_message`
 
 --------
 
@@ -290,6 +301,24 @@ of the contents of the ``LIBLAMMPS`` Fortran interface to LAMMPS.
            lmp = lammps(MPI_COMM_SELF%MPI_VAL)
          END PROGRAM testmpi
 
+.. f:type:: lammps_style
+
+   This derived type is there to provide a convenient interface for the style
+   constants used with :f:func:`extract_compute`, :f:func:`extract_fix`, and
+   :f:func:`extract_variable`. Assuming your LAMMPS instance is called ``lmp``,
+   these constants will be ``lmp%style%global``, ``lmp%style%atom``,
+   and ``lmp%style%local``. These values are identical to the values described
+   in :cpp:enum:`_LMP_STYLE_CONST` for the C library interface.
+
+.. f:type:: lammps_type
+
+   This derived type is there to provide a convenient interface for the type
+   constants used with :f:func:`extract_compute`, :f:func:`extract_fix`, and
+   :f:func:`extract_variable`. Assuming your LAMMPS instance is called ``lmp``,
+   these constants will be ``lmp%type%scalar``, ``lmp%type%vector``, and
+   ``lmp%type%array``. These values are identical to the values described
+   in :cpp:enum:`_LMP_TYPE_CONST` for the C library interface.
+
 Procedures Bound to the lammps Derived Type
 ===========================================
 
@@ -301,7 +330,7 @@ Procedures Bound to the lammps Derived Type
    :cpp:func:`lammps_mpi_finalize`.
 
    :o logical finalize [optional]: shut down the MPI environment of the LAMMPS
-    library if true.
+    library if ``.TRUE.``.
 
 --------
 
@@ -571,6 +600,8 @@ Procedures Bound to the lammps Derived Type
    LAMMPS data tied to the :cpp:class:`Atom` class, depending on the data
    requested through *name*.
 
+   .. versionadded:: TBD
+
    Note that this function actually does not return a pointer, but rather
    associates the pointer on the left side of the assignment to point
    to internal LAMMPS data. Pointers must be of the correct type, kind, and
@@ -645,6 +676,8 @@ Procedures Bound to the lammps Derived Type
    required to specify which set of data is to be returned through the
    *style* and *type* variables.
 
+   .. versionadded:: TBD
+
    Note that this function actually does not return a value, but rather
    associates the pointer on the left side of the assignment to point to
    internal LAMMPS data. Pointers must be of the correct data type to point to
@@ -719,6 +752,11 @@ Procedures Bound to the lammps Derived Type
     (global, per-atom, or local)
    :p integer(c_int) type: value indicating the type of data to extract
     (scalar, vector, or array)
+   :r polymorphic: pointer to LAMMPS data. The left-hand side of the assignment
+    should be a C-compatible pointer (e.g., ``REAL (C_double), POINTER :: x``)
+    to the extracted property. If expecting vector data, the pointer should
+    have dimension ":"; if expecting array (matrix) data, the pointer should
+    have dimension ":,:".
 
    .. note::
 
@@ -738,9 +776,220 @@ Procedures Bound to the lammps Derived Type
 
 --------
 
+.. f:function:: extract_fix(id, style, type, [nrow,] [ncol])
+
+   This function calls :c:func:`lammps_extract_fix` and returns a pointer to
+   LAMMPS data tied to the :cpp:class:`Fix` class, specifically data provided
+   by the fix identified by *id*. Fixes may provide global, per-atom, or
+   local data, and those data may be a scalar, a vector, or an array. Since
+   many fixes provide multiple kinds of data, the user is required to specify
+   which set of data is to be returned through the *style* and *type*
+   variables.
+
+   .. versionadded:: TBD
+
+   Global data are calculated at the time they are requested and are only
+   available element-by-element. As such, the user is expected to provide
+   the *nrow* variable to specify which element of a global vector or the
+   *nrow* and *ncol* variables to specify which element of a global array the
+   user wishes LAMMPS to return. The *ncol* variable is optional for global
+   scalar or vector data, and both *nrow* and *ncol* are optional when a
+   global scalar is requested, as well as when per-atom or local data are
+   requested.
+
+   In the case of global data, this function returns a value of type
+   ``real(C_double)``. For per-atom or local data, this function does not
+   return a value but instead associates the pointer on the left side of the
+   assignment to point to internal LAMMPS data. Pointers must be of the correct
+   data type to point to said data (i.e., ``REAL(c_double)``) and have
+   compatible rank.  The pointer being associated with LAMMPS data is type-,
+   kind-, and rank-checked at run-time via an overloaded assignment operator.
+
+   For example,
+
+   .. code-block:: Fortran
+
+      TYPE(lammps) :: lmp
+      REAL(c_double) :: dr, dx, dy, dz
+      ! more code to set up, etc.
+      lmp%command('fix george all recenter 2 2 2')
+      ! more code
+      dr = lmp%extract_fix("george", lmp%style%global, lmp%style%scalar)
+      dx = lmp%extract_fix("george", lmp%style%global, lmp%style%vector, 1)
+      dy = lmp%extract_fix("george", lmp%style%global, lmp%style%vector, 2)
+      dz = lmp%extract_fix("george", lmp%style%global, lmp%style%vector, 3)
+
+   will extract the global scalar calculated by
+   :doc:`fix recenter <fix_recenter>` into the variable *dr* and the
+   three elements of the global vector calculated by fix recenter into the
+   variables *dx*, *dy*, and *dz*, respectively.
+
+   If asked for per-atom or local data, :f:func:`extract_compute` returns a
+   pointer to actual LAMMPS data. The pointer so returned will have the
+   appropriate size to match the internal data, and will be
+   type/kind/rank-checked at the time of the assignment. For example,
+
+   .. code-block:: Fortran
+
+      TYPE(lammps) :: lmp
+      REAL(c_double), DIMENSION(:), POINTER :: r
+      ! more code to set up, etc.
+      lmp%command('fix state all store/state 0 x y z')
+      ! more code
+      r = lmp%extract_fix('state', lmp%style%atom, lmp%type%array)
+
+   will bind the pointer *r* to internal LAMMPS data representing the per-atom
+   array computed by :doc:`fix store/state <fix_store_state>` when three
+   inputs are specified. Similarly,
+
+   .. code-block:: Fortran
+
+      TYPE(lammps) :: lmp
+      REAL(c_double), DIMENSION(:), POINTER :: x
+      ! more code to set up, etc.
+      lmp%command('fix state all store/state 0 x')
+      ! more code
+      x = lmp%extract_fix('state', lmp%style%atom, lmp%type%vector)
+
+   will associate the pointer *x* with internal LAMMPS data corresponding to
+   the per-atom vector computed by :doc:`fix store/state <fix_store_state>`
+   when only one input is specified. Similar examples with ``lmp%style%atom``
+   replaced by ``lmp%style%local`` will extract local data from fixes that
+   define local vectors and/or arrays.
+
+   .. warning::
+
+      The pointers returned by this function for per-atom or local data are
+      generally not persistent, since the computed data may be redistributed,
+      reallocated, and reordered at every invocation of the fix.  It is thus
+      advisable to reinvoke this function before the data are accessed or to
+      make a copy if the data are to be used after other LAMMPS commands have
+      been issued.
+
+   .. note::
+
+      LAMMPS cannot easily check if it is valid to access the data, so it
+      may fail with an error.  The caller has to avoid such an error.
+
+   :p character(len=\*) id: string with the name of the fix from which
+    to extract data
+   :p integer(c_int) style: value indicating the style of data to extract
+    (global, per-atom, or local)
+   :p integer(c_int) type: value indicating the type of data to extract
+    (scalar, vector, or array)
+   :p integer(c_int) nrow: row index (used only for global vectors and arrays)
+   :p integer(c_int) ncol: column index (only used for global arrays)
+   :r polymorphic: LAMMPS data (for global data) or a pointer to LAMMPS data
+    (for per-atom or local data). The left-hand side of the assignment should
+    be of type ``REAL(C_double)`` and have appropriate rank (i.e.,
+    ``DIMENSION(:)`` if expecting per-atom or local vector data and
+    ``DIMENSION(:,:)`` if expecting per-atom or local array data). If expecting
+    global or per-atom data, it should have the ``POINTER`` attribute.
+
+   .. admonition:: Array index order
+
+      Two-dimensional global, per-atom, or local array data from
+      :f:func:`extract_fix` will be **transposed** from equivalent arrays in
+      C (or in the ordinary LAMMPS interface accessed through thermodynamic
+      output), and they will be indexed from 1, not 0. This is true even for
+      global data, which are returned as scalars---this is done primarily so
+      the interface is consistent, as there is no choice but to transpose the
+      indices for per-atom or local array data. See the similar note under
+      :f:func:`extract_atom` for further details.
+
+--------
+
+.. f:function:: extract_variable(name[,group])
+
+   This function calls :c:func:`lammps_extract_variable` and returns a scalar,
+   vector, or string containing the value of the variable identified by
+   *name*. When the variable is an *equal*-style variable (or one compatible
+   with that style such as *internal*), the variable is evaluated and the
+   corresponding value returned. When the variable is an *atom*-style variable,
+   the variable is evaluated and a vector of values is returned. With all
+   other variables, a string is returned. The *group* argument is only used
+   for *atom* style variables and is ignored otherwise. If *group* is absent
+   for *atom*-style variables, the group is assumed to be "all".
+
+   .. versionadded:: TBD
+
+   This function returns the values of the variables, not pointers to them.
+   Vectors pointing to *atom*-style variables should be of type
+   ``REAL(C_double)``, be of rank 1 (i.e., ``DIMENSION(:)``), and either have
+   the ``ALLOCATABLE`` attribute or be long enough to contain the data without
+   reallocation.
+
+   .. note::
+
+      Unlike the C library interface, the Fortran interface does not require
+      you to deallocate memory when you are through; this is done for you,
+      behind the scenes.
+
+   For example,
+
+   .. code-block:: Fortran
+
+      TYPE(lammps) :: lmp
+      REAL(c_double) :: area
+      ! more code to set up, etc.
+      lmp%command('variable A equal lx*ly')
+      ! more code
+      area = lmp%extract_variable("A")
+
+   will extract the *x*\ --*y* cross-sectional area of the simulation into the
+   variable *area*.
+
+   :p character(len=\*) name: variable name to evaluate
+   :o character(len=\*) group [optional]: group for which to extract per-atom
+    data (if absent, use "all")
+   :r polymorphic: scalar of type ``REAL(C_double)`` (for *equal*-style
+    variables and others that are *equal*-compatible), vector of type
+    ``REAL(C_double), DIMENSION(nlocal)`` for *atom*-style variables, or
+    ``CHARACTER(LEN=:), ALLOCATABLE`` for *string*-style and compatible
+    variables. Non-allocatable strings whose length is too short to hold the
+    result will be truncated.
+
+.. note::
+
+   LAMMPS cannot easily check if it is valid to access the data
+   referenced by the variables (e.g., computes, fixes, or thermodynamic
+   info), so it may fail with an error.  The caller has to make certain
+   that the data are extracted only when it safe to evaluate the variable
+   and thus an error and crash are avoided.
+
+--------
+
 .. f:function:: version()
 
    This method returns the numeric LAMMPS version like
    :cpp:func:`lammps_version` does.
 
    :r integer: LAMMPS version
+
+--------
+
+.. f:subroutine:: flush_buffers
+
+..
+    TODO
+
+--------
+
+.. f:function:: is_running
+
+..
+    TODO
+
+--------
+
+.. f:function:: has_error
+
+..
+    TODO
+
+--------
+
+.. f:subroutine:: get_last_error_message
+
+..
+    TODO

doc/src/Library_objects.rst

@@ -21,6 +21,11 @@ fixes, or variables in LAMMPS using the following functions:
 
 -----------------------
 
+.. doxygenfunction:: lammps_extract_variable_datatype
+   :project: progguide
+
+-----------------------
+
 .. doxygenfunction:: lammps_extract_variable
    :project: progguide
 
@@ -36,3 +41,5 @@ fixes, or variables in LAMMPS using the following functions:
 .. doxygenenum:: _LMP_STYLE_CONST
 
 .. doxygenenum:: _LMP_TYPE_CONST
+
+.. doxygenenum:: _LMP_VAR_CONST

src/library.cpp

@@ -2068,9 +2068,9 @@ use to avoid a memory leak. Example:
 
 For *atom*\ -style variables the data returned is a pointer to an
 allocated block of storage of double of the length ``atom->nlocal``.
-Since the data is returned a copy, the location will persist, but its
+Since the data returned are a copy, the location will persist, but its
-content will not be updated, in case the variable is re-evaluated.
+content will not be updated in case the variable is re-evaluated.
-To avoid a memory leak this pointer needs to be freed after use in
+To avoid a memory leak, this pointer needs to be freed after use in
 the calling program.
 
 For other variable styles the returned pointer needs to be cast to
@@ -2084,10 +2084,10 @@ a char pointer.
 .. note::
 
    LAMMPS cannot easily check if it is valid to access the data
-   referenced by the variables, e.g. computes or fixes or thermodynamic
+   referenced by the variables (e.g., computes or fixes or thermodynamic
-   info, so it may fail with an error.  The caller has to make certain,
+   info), so it may fail with an error.  The caller has to make certain
-   that the data is extracted only when it safe to evaluate the variable
+   that the data are extracted only when it safe to evaluate the variable
-   and thus an error and crash is avoided.
+   and thus an error or crash are avoided.
 
 \endverbatim
  *
@@ -2130,7 +2130,7 @@ void *lammps_extract_variable(void *handle, const char *name, const char *group)
 
 /* ---------------------------------------------------------------------- */
 
-/** Get data type of a LAMMPS variable
+/** Get data type of a LAMMPS variable.
  *
 \verbatim embed:rst
 
@@ -2207,12 +2207,12 @@ int lammps_set_variable(void *handle, char *name, char *str)
      requirement for consecutive atom IDs (1 to N)
    see gather_atoms_concat() to return data for all atoms, unordered
    see gather_atoms_subset() to return data for only a subset of atoms
-   name = desired quantity, e.g. x or charge
+   name = desired quantity (e.g., x or charge)
    type = 0 for integer values, 1 for double values
-   count = # of per-atom values, e.g. 1 for type or charge, 3 for x or f
+   count = # of per-atom values (e.g., 1 for type or charge, 3 for x or f)
      use count = 3 with "image" if want single image flag unpacked into xyz
    return atom-based values in 1d data, ordered by count, then by atom ID
-     e.g. x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...
+     (e.g., x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...);
      data must be pre-allocated by caller to correct length
      correct length = count*Natoms, as queried by get_natoms()
    method:
@@ -2344,12 +2344,12 @@ void lammps_gather_atoms(void *handle, char *name, int type, int count, void *da
      can do a gather_atoms_concat for "id" if need to know atom IDs
    see gather_atoms() to return data ordered by consecutive atom IDs
    see gather_atoms_subset() to return data for only a subset of atoms
-   name = desired quantity, e.g. x or charge
+   name = desired quantity (e.g., x or charge)
    type = 0 for integer values, 1 for double values
-   count = # of per-atom values, e.g. 1 for type or charge, 3 for x or f
+   count = # of per-atom values (e.g., 1 for type or charge, 3 for x or f)
      use count = 3 with "image" if want single image flag unpacked into xyz
    return atom-based values in 1d data, ordered by count, then by atom
-     e.g. x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...
+     (e.g., x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...)
      data must be pre-allocated by caller to correct length
      correct length = count*Natoms, as queried by get_natoms()
    method:
@@ -2488,14 +2488,14 @@ void lammps_gather_atoms_concat(void *handle, char *name, int type, int count, v
      no requirement for consecutive atom IDs (1 to N)
    see gather_atoms() to return data for all atoms, ordered by consecutive IDs
    see gather_atoms_concat() to return data for all atoms, unordered
-   name = desired quantity, e.g. x or charge
+   name = desired quantity (e.g., x or charge)
    type = 0 for integer values, 1 for double values
-   count = # of per-atom values, e.g. 1 for type or charge, 3 for x or f
+   count = # of per-atom values (e.g., 1 for type or charge, 3 for x or f)
      use count = 3 with "image" if want single image flag unpacked into xyz
    ndata = # of atoms to return data for (could be all atoms)
    ids = list of Ndata atom IDs to return data for
    return atom-based values in 1d data, ordered by count, then by atom
-     e.g. x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...
+     (e.g., x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...)
      data must be pre-allocated by caller to correct length
      correct length = count*Ndata
    method:
@@ -2632,12 +2632,12 @@ void lammps_gather_atoms_subset(void *handle, char *name, int type, int count,
    data is ordered by atom ID
      requirement for consecutive atom IDs (1 to N)
    see scatter_atoms_subset() to scatter data for some (or all) atoms, unordered
-   name = desired quantity, e.g. x or charge
+   name = desired quantity (e.g., x or charge)
    type = 0 for integer values, 1 for double values
-   count = # of per-atom values, e.g. 1 for type or charge, 3 for x or f
+   count = # of per-atom values (e.g., 1 for type or charge, 3 for x or f)
      use count = 3 with "image" for xyz to be packed into single image flag
    data = atom-based values in 1d data, ordered by count, then by atom ID
-     e.g. x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...
+     (e.g., x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...)
      data must be correct length = count*Natoms, as queried by get_natoms()
    method:
      loop over Natoms, if I own atom ID, set its values from data
@@ -2748,14 +2748,14 @@ void lammps_scatter_atoms(void *handle, char *name, int type, int count, void *d
    data is ordered by provided atom IDs
      no requirement for consecutive atom IDs (1 to N)
    see scatter_atoms() to scatter data for all atoms, ordered by consecutive IDs
-   name = desired quantity, e.g. x or charge
+   name = desired quantity (e.g., x or charge)
    type = 0 for integer values, 1 for double values
-   count = # of per-atom values, e.g. 1 for type or charge, 3 for x or f
+   count = # of per-atom values (e.g., 1 for type or charge, 3 for x or f)
      use count = 3 with "image" for xyz to be packed into single image flag
    ndata = # of atoms in ids and data (could be all atoms)
    ids = list of Ndata atom IDs to scatter data to
    data = atom-based values in 1d data, ordered by count, then by atom ID
-     e.g. x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...
+     (e.g., x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...)
      data must be correct length = count*Ndata
    method:
      loop over Ndata, if I own atom ID, set its values from data
@@ -2992,10 +2992,10 @@ void lammps_gather_bonds(void *handle, void *data)
          "d2_name" or "i2_name" for fix property/atom arrays with count > 1
          will return error if fix/compute isn't atom-based
   type = 0 for integer values, 1 for double values
-  count = # of per-atom values, e.g. 1 for type or charge, 3 for x or f
+  count = # of per-atom values (e.g., 1 for type or charge, 3 for x or f)
     use count = 3 with "image" if want single image flag unpacked into xyz
   return atom-based values in 1d data, ordered by count, then by atom ID
-    e.g. x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...
+    (e.g., x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...)
     data must be pre-allocated by caller to correct length
     correct length = count*Natoms, as queried by get_natoms()
   method:
@@ -3227,10 +3227,10 @@ void lammps_gather(void *handle, char *name, int type, int count, void *data)
          "d2_name" or "i2_name" for fix property/atom arrays with count > 1
          will return error if fix/compute isn't atom-based
   type = 0 for integer values, 1 for double values
-  count = # of per-atom values, e.g. 1 for type or charge, 3 for x or f
+  count = # of per-atom values (e.g., 1 for type or charge, 3 for x or f)
     use count = 3 with "image" if want single image flag unpacked into xyz
   return atom-based values in 1d data, ordered by count, then by atom ID
-    e.g. x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...
+    (e.g., x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...)
     data must be pre-allocated by caller to correct length
     correct length = count*Natoms, as queried by get_natoms()
   method:
@@ -3479,10 +3479,10 @@ void lammps_gather_concat(void *handle, char *name, int type, int count, void *d
          "d2_name" or "i2_name" for fix property/atom arrays with count > 1
          will return error if fix/compute isn't atom-based
   type = 0 for integer values, 1 for double values
-  count = # of per-atom values, e.g. 1 for type or charge, 3 for x or f
+  count = # of per-atom values (e.g., 1 for type or charge, 3 for x or f)
     use count = 3 with "image" if want single image flag unpacked into xyz
   return atom-based values in 1d data, ordered by count, then by atom ID
-    e.g. x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...
+    (e.g., x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...)
     data must be pre-allocated by caller to correct length
     correct length = count*Natoms, as queried by get_natoms()
   method:
@@ -3727,10 +3727,10 @@ void lammps_gather_subset(void *handle, char *name,
          "d2_name" or "i2_name" for fix property/atom arrays with count > 1
          will return error if fix/compute isn't atom-based
   type = 0 for integer values, 1 for double values
-  count = # of per-atom values, e.g. 1 for type or charge, 3 for x or f
+  count = # of per-atom values (e.g., 1 for type or charge, 3 for x or f)
     use count = 3 with "image" if want single image flag unpacked into xyz
   return atom-based values in 1d data, ordered by count, then by atom ID
-    e.g. x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...
+    (e.g., x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...)
     data must be pre-allocated by caller to correct length
     correct length = count*Natoms, as queried by get_natoms()
   method:
@@ -3945,12 +3945,12 @@ void lammps_scatter(void *handle, char *name, int type, int count, void *data)
           "f_fix", "c_compute" for fixes / computes
           will return error if fix/compute doesn't isn't atom-based
    type = 0 for integer values, 1 for double values
-   count = # of per-atom values, e.g. 1 for type or charge, 3 for x or f
+   count = # of per-atom values (e.g., 1 for type or charge, 3 for x or f)
      use count = 3 with "image" for xyz to be packed into single image flag
    ndata = # of atoms in ids and data (could be all atoms)
    ids = list of Ndata atom IDs to scatter data to
    data = atom-based values in 1d data, ordered by count, then by atom ID
-     e.g. x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...
+     (e.g., x[0][0],x[0][1],x[0][2],x[1][0],x[1][1],x[1][2],x[2][0],...)
      data must be correct length = count*Ndata
    method:
      loop over Ndata, if I own atom ID, set its values from data
@@ -4193,8 +4193,8 @@ boundaries atoms will be wrapped back into the simulation cell and its
 image flags adjusted accordingly, unless explicit image flags are
 provided.
 
-The function returns the number of atoms created or -1 on failure, e.g.
+The function returns the number of atoms created or -1 on failure (e.g.,
-when called before as box has been created.
+when called before as box has been created).
 
 Coordinates and velocities have to be given in a 1d-array in the order
 X(1),Y(1),Z(1),X(2),Y(2),Z(2),...,X(N),Y(N),Z(N).
@@ -4552,7 +4552,7 @@ int lammps_config_has_mpi_support()
  * files via a pipe to gzip or similar compression programs
 
 \verbatim embed:rst
-Several LAMMPS commands (e.g. :doc:`read_data`, :doc:`write_data`,
+Several LAMMPS commands (e.g., :doc:`read_data`, :doc:`write_data`,
 :doc:`dump styles atom, custom, and xyz <dump>`) support reading and
 writing compressed files via creating a pipe to the ``gzip`` program.
 This function checks whether this feature was :ref:`enabled at compile
@@ -5224,8 +5224,8 @@ data structures can change as well as the order of atom as they migrate
 between MPI processes because of the domain decomposition
 parallelization, this function should be always called immediately
 before the forces are going to be set to get an up-to-date pointer.
- You can use e.g. :cpp:func:`lammps_get_natoms` to obtain the number
+You can use, for example, :cpp:func:`lammps_extract_setting` to obtain the
-of local atoms `nlocal` and then assume the dimensions of the returned
+number of local atoms `nlocal` and then assume the dimensions of the returned
 force array as ``double force[nlocal][3]``.
 
 This is an alternative to the callback mechanism in fix external set up by
@@ -5511,7 +5511,7 @@ void lammps_fix_external_set_vector_length(void *handle, const char *id, int len
 This is a companion function to :cpp:func:`lammps_set_fix_external_callback` and
 :cpp:func:`lammps_fix_external_get_force` to set the values of a global vector of
 properties that will be stored with the fix.  And can be accessed from
-within LAMMPS input commands (e.g. fix ave/time or variables) when used
+within LAMMPS input commands (e.g., fix ave/time or variables) when used
 in a vector context.
 
 This function needs to be called **after** a call to

src/library.h

@@ -91,7 +91,7 @@ enum _LMP_ERROR_CONST {
   LMP_ERROR_UNIVERSE = 8 /*!< error on Comm::universe */
 };
 
-/** Variable style constants for extracting data from variables
+/** Variable style constants for extracting data from variables.
  *
  * Must be kept in sync with the equivalent constants in lammps/constants.py
  * and fortran/lammps.f90 */