diff --git a/doc/src/Library_add.rst b/doc/src/Library_add.rst index e58b6c2b73..ef91c98ab0 100644 --- a/doc/src/Library_add.rst +++ b/doc/src/Library_add.rst @@ -2,11 +2,11 @@ Adding code to the Library interface ==================================== The functionality of the LAMMPS library interface has historically -always been motivated by the needs of its users and functions were -added or expanded as they were needed and used. Contributions to -the interface are always welcome. However with a refactoring of -the library interface and its documentation that started in 2020, -there are now a few requirements for inclusion of changes. +been motivated by the needs of its users. Functions have been added +or expanded as they were needed and used. Contributions to the +interface are always welcome. However with a refactoring of the +library interface and its documentation that started in 2020, there +are now a few requirements for including new changes or extensions. - New functions should be orthogonal to existing ones and not implement functionality that can already be achieved with the @@ -17,17 +17,18 @@ there are now a few requirements for inclusion of changes. ``doc/src`` folder. - If possible, new unit tests to test those new features should be added. - - The new feature should also be implemented and documented for - the Python and Fortran modules. + - The new feature should also be implemented and documented not + just for the C interface, but also the Python and Fortran interfaces. - All additions should work and be compatible with ``-DLAMMPS_BIGBIG``, - ``-DLAMMPS_SMALLBIG``, ``-DLAMMPS_SMALLSMALL`` and compiling + ``-DLAMMPS_SMALLBIG``, ``-DLAMMPS_SMALLSMALL`` and when compiling with and without MPI support. - The ``library.h`` file should be kept compatible to C code at a level similar to C89. Its interfaces may not reference any - custom data types (e.g. ``bigint``, ``tagint``, and so on) only - known inside of LAMMPS. - - only C style comments, not C++ style + custom data types (e.g. ``bigint``, ``tagint``, and so on) that + are only known inside of LAMMPS. + - only use C style comments, not C++ style + +Please note that these are *not* *strict* requirements, but the LAMMPS +developers appreciate if they are followed and can assist with +implementing what is missing. -Please note, that these are *not* *strict* requirements, but the -LAMMPS developers appreciate if they are followed closely and will -assist with implementing what is missing. diff --git a/doc/src/Library_config.rst b/doc/src/Library_config.rst index 0c07896ff6..3389d52173 100644 --- a/doc/src/Library_config.rst +++ b/doc/src/Library_config.rst @@ -18,18 +18,18 @@ This section documents the following functions: -------------------- -The following library functions can be used to query the LAMMPS library -about compile time settings and included packages and styles. This -enables programs that use the library interface to run LAMMPS -simulations to determine, whether the linked LAMMPS library is compatible -with the requirements of the application without crashing during the -LAMMPS functions (e.g. due to missing pair styles from packages) or to -choose between different options (e.g. whether to use ``lj/cut``, -``lj/cut/opt``, ``lj/cut/omp`` or ``lj/cut/intel``). Most of the -functions can be called directly without first creating a LAMMPS -instance. While crashes within LAMMPS may be recovered from through -enabling :ref:`exceptions `, avoiding them proactively is -a safer approach. +These library functions can be used to query the LAMMPS library for +compile time settings and included packages and styles. This enables +programs that use the library interface to determine whether the +linked LAMMPS library is compatible with the requirements of the +application without crashing during the LAMMPS functions (e.g. due to +missing pair styles from packages) or to choose between different +options (e.g. whether to use ``lj/cut``, ``lj/cut/opt``, +``lj/cut/omp`` or ``lj/cut/intel``). Most of the functions can be +called directly without first creating a LAMMPS instance. While +crashes within LAMMPS may be recovered from by enabling +:ref:`exceptions `, avoiding them proactively is a safer +approach. .. code-block:: C :caption: Example for using configuration settings functions diff --git a/doc/src/Library_neighbor.rst b/doc/src/Library_neighbor.rst index 3179b669f1..f50d28b81e 100644 --- a/doc/src/Library_neighbor.rst +++ b/doc/src/Library_neighbor.rst @@ -1,8 +1,8 @@ Accessing LAMMPS Neighbor lists =============================== -The following functions allow to access neighbor lists -generated by LAMMPS or query their properties: +The following functions enable access to neighbor lists generated by +LAMMPS or querying of their properties: - :cpp:func:`lammps_find_compute_neighlist` - :cpp:func:`lammps_find_fix_neighlist` diff --git a/doc/src/Library_objects.rst b/doc/src/Library_objects.rst index 3b87842169..5ce03f84a3 100644 --- a/doc/src/Library_objects.rst +++ b/doc/src/Library_objects.rst @@ -1,8 +1,8 @@ Retrieving or setting properties of LAMMPS objects ================================================== -This section documents accessing or modifying data from objects like -computes, fixes, or variables in LAMMPS using following functions: +This section documents accessing or modifying data stored by computes, +fixes, or variables in LAMMPS using the following functions: - :cpp:func:`lammps_extract_compute` - :cpp:func:`lammps_extract_fix` diff --git a/doc/src/Library_scatter.rst b/doc/src/Library_scatter.rst index e3ca34e999..9594593172 100644 --- a/doc/src/Library_scatter.rst +++ b/doc/src/Library_scatter.rst @@ -1,7 +1,16 @@ Library functions for scatter/gather operations ================================================ -This section documents the following functions: +This section has functions which gather per-atom data from one or more +processors into a contiguous global list ordered by atom ID. The same +list is returned to all calling processors. It also contains +functions which scatter per-atom data from a contiguous global list +across the processors that own those atom IDs. It also has a +create_atoms() function which can create a new simulation by +scattering atms appropriately to owning processors in the LAMMPS +spatial decomposition. + +It documents the following functions: - :cpp:func:`lammps_gather_atoms` - :cpp:func:`lammps_gather_atoms_concat` @@ -14,8 +23,6 @@ This section documents the following functions: - :cpp:func:`lammps_scatter` - :cpp:func:`lammps_scatter_subset` -.. TODO add description - ----------------------- .. doxygenfunction:: lammps_gather_atoms diff --git a/doc/src/Library_utility.rst b/doc/src/Library_utility.rst index 3d2fae53d3..6cc3337d48 100644 --- a/doc/src/Library_utility.rst +++ b/doc/src/Library_utility.rst @@ -1,8 +1,8 @@ Library interface utility functions =================================== -To simplify some of the tasks, the library interface contains -some utility functions that are not directly calling LAMMPS: +To simplify some tasks, the library interface contains these utility +functions. They do not directly call the LAMMPS library. - :cpp:func:`lammps_encode_image_flags` - :cpp:func:`lammps_decode_image_flags`