more edits to C library chapter
This commit is contained in:
Steve Plimpton
@ -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.
|
||||
|
||||
@ -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 <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 <exceptions>`, avoiding them proactively is a safer
|
||||
approach.
|
||||
|
||||
.. code-block:: C
|
||||
:caption: Example for using configuration settings functions
|
||||
|
||||
@ -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`
|
||||
|
||||
@ -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`
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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`
|
||||
|
||||
Reference in New Issue
Block a user